001/* 002 * Copyright 2007-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2014 UnboundID Corp. 007 * 008 * This program is free software; you can redistribute it and/or modify 009 * it under the terms of the GNU General Public License (GPLv2 only) 010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 011 * as published by the Free Software Foundation. 012 * 013 * This program is distributed in the hope that it will be useful, 014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 016 * GNU General Public License for more details. 017 * 018 * You should have received a copy of the GNU General Public License 019 * along with this program; if not, see <http://www.gnu.org/licenses>. 020 */ 021package com.unboundid.ldap.sdk; 022 023 024 025import java.io.Serializable; 026import java.util.HashMap; 027 028import com.unboundid.util.NotMutable; 029import com.unboundid.util.ThreadSafety; 030import com.unboundid.util.ThreadSafetyLevel; 031 032 033 034/** 035 * This class defines a data type for search scope values. Clients should 036 * generally use one of the {@code BASE}, {@code ONE}, {@code SUB}, or 037 * {@code SUBORDINATE_SUBTREE} values, although it is possible to create a new 038 * scope with a specified integer value if necessary using the 039 * {@link #valueOf(int)} method. The following search scope values are defined: 040 * <UL> 041 * <LI>{@code BASE} -- Indicates that only the entry specified by the base DN 042 * should be considered.</LI> 043 * <LI>{@code ONE} -- Indicates that only entries that are immediate 044 * subordinates of the entry specified by the base DN (but not the base 045 * entry itself) should be considered.</LI> 046 * <LI>{@code SUB} -- Indicates that the base entry itself and any subordinate 047 * entries (to any depth) should be considered.</LI> 048 * <LI>{@code SUBORDINATE_SUBTREE} -- Indicates that any subordinate entries 049 * (to any depth) below the entry specified by the base DN should be 050 * considered, but the base entry itself should not be considered, as 051 * described in draft-sermersheim-ldap-subordinate-scope.</LI> 052 * </UL> 053 */ 054@NotMutable() 055@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 056public final class SearchScope 057 implements Serializable 058{ 059 /** 060 * The integer value for the "base" search scope. 061 */ 062 public static final int BASE_INT_VALUE = 0; 063 064 065 066 /** 067 * A predefined baseObject scope value, which indicates that only the entry 068 * specified by the base DN should be considered. 069 */ 070 public static final SearchScope BASE = 071 new SearchScope("BASE", BASE_INT_VALUE); 072 073 074 075 /** 076 * The integer value for the "one" search scope. 077 */ 078 public static final int ONE_INT_VALUE = 1; 079 080 081 082 /** 083 * A predefined singleLevel scope value, which indicates that only entries 084 * that are immediate subordinates of the entry specified by the base DN (but 085 * not the base entry itself) should be considered. 086 */ 087 public static final SearchScope ONE = new SearchScope("ONE", ONE_INT_VALUE); 088 089 090 091 /** 092 * The integer value for the "sub" search scope. 093 */ 094 public static final int SUB_INT_VALUE = 2; 095 096 097 098 /** 099 * A predefined wholeSubtree scope value, which indicates that the base entry 100 * itself and any subordinate entries (to any depth) should be considered. 101 */ 102 public static final SearchScope SUB = new SearchScope("SUB", SUB_INT_VALUE); 103 104 105 106 /** 107 * The integer value for the "subordinate subtree" search scope. 108 */ 109 public static final int SUBORDINATE_SUBTREE_INT_VALUE = 3; 110 111 112 113 /** 114 * A predefined subordinateSubtree scope value, which indicates that any 115 * subordinate entries (to any depth) below the entry specified by the base DN 116 * should be considered, but the base entry itself should not be considered. 117 */ 118 public static final SearchScope SUBORDINATE_SUBTREE = 119 new SearchScope("SUBORDINATE_SUBTREE", SUBORDINATE_SUBTREE_INT_VALUE); 120 121 122 123 /** 124 * The set of search scope objects created with undefined int values. 125 */ 126 private static final HashMap<Integer,SearchScope> UNDEFINED_SCOPES = 127 new HashMap<Integer,SearchScope>(); 128 129 130 131 /** 132 * The serial version UID for this serializable class. 133 */ 134 private static final long serialVersionUID = 5381929718445793181L; 135 136 137 138 // The integer value for this search scope. 139 private final int intValue; 140 141 // The name to use for this search scope. 142 private final String name; 143 144 145 146 /** 147 * Creates a new search scope with the specified integer value. 148 * 149 * @param intValue The integer value to use for this search scope. 150 */ 151 private SearchScope(final int intValue) 152 { 153 this.intValue = intValue; 154 155 name = String.valueOf(intValue); 156 } 157 158 159 160 /** 161 * Creates a new search scope with the specified name and integer value. 162 * 163 * @param name The name to use for this search scope. 164 * @param intValue The integer value to use for this search scope. 165 */ 166 private SearchScope(final String name, final int intValue) 167 { 168 this.name = name; 169 this.intValue = intValue; 170 } 171 172 173 174 /** 175 * Retrieves the name for this search scope. 176 * 177 * @return The name for this search scope. 178 */ 179 public String getName() 180 { 181 return name; 182 } 183 184 185 186 /** 187 * Retrieves the integer value for this search scope. 188 * 189 * @return The integer value for this search scope. 190 */ 191 public int intValue() 192 { 193 return intValue; 194 } 195 196 197 198 /** 199 * Retrieves the search scope with the specified integer value. 200 * 201 * @param intValue The integer value for which to retrieve the corresponding 202 * search scope. 203 * 204 * @return The search scope with the specified integer value, or a new search 205 * scope if the provided value does not match any of the predefined 206 * scopes. 207 */ 208 public static SearchScope valueOf(final int intValue) 209 { 210 switch (intValue) 211 { 212 case 0: 213 return BASE; 214 case 1: 215 return ONE; 216 case 2: 217 return SUB; 218 case 3: 219 return SUBORDINATE_SUBTREE; 220 default: 221 synchronized (UNDEFINED_SCOPES) 222 { 223 SearchScope s = UNDEFINED_SCOPES.get(intValue); 224 if (s == null) 225 { 226 s = new SearchScope(intValue); 227 UNDEFINED_SCOPES.put(intValue, s); 228 } 229 230 return s; 231 } 232 } 233 } 234 235 236 237 /** 238 * Retrieves the predefined search scope with the specified integer value. 239 * 240 * @param intValue The integer value for which to retrieve the corresponding 241 * search scope. 242 * 243 * @return The search scope with the specified integer value, or {@code null} 244 * if the provided integer value does not represent a defined scope. 245 */ 246 public static SearchScope definedValueOf(final int intValue) 247 { 248 switch (intValue) 249 { 250 case 0: 251 return BASE; 252 case 1: 253 return ONE; 254 case 2: 255 return SUB; 256 case 3: 257 return SUBORDINATE_SUBTREE; 258 default: 259 return null; 260 } 261 } 262 263 264 265 /** 266 * Retrieves an array of all search scopes defined in the LDAP SDK. 267 * 268 * @return An array of all search scopes defined in the LDAP SDK. 269 */ 270 public static SearchScope[] values() 271 { 272 return new SearchScope[] 273 { 274 BASE, 275 ONE, 276 SUB, 277 SUBORDINATE_SUBTREE 278 }; 279 } 280 281 282 283 /** 284 * The hash code for this search scope. 285 * 286 * @return The hash code for this search scope. 287 */ 288 @Override() 289 public int hashCode() 290 { 291 return intValue; 292 } 293 294 295 296 /** 297 * Indicates whether the provided object is equal to this search scope. 298 * 299 * @param o The object for which to make the determination. 300 * 301 * @return {@code true} if the provided object is a search scope that is 302 * equal to this search scope, or {@code false} if not. 303 */ 304 @Override() 305 public boolean equals(final Object o) 306 { 307 if (o == null) 308 { 309 return false; 310 } 311 else if (o == this) 312 { 313 return true; 314 } 315 else if (o instanceof SearchScope) 316 { 317 return (intValue == ((SearchScope) o).intValue); 318 } 319 else 320 { 321 return false; 322 } 323 } 324 325 326 327 /** 328 * Retrieves a string representation of this search scope. 329 * 330 * @return A string representation of this search scope. 331 */ 332 @Override() 333 public String toString() 334 { 335 return name; 336 } 337}