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    }