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