001    /*
002     * Copyright 2007-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2016 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 dereference policy values.  Clients should
033     * generally use one of the {@code NEVER}, {@code SEARCHING}, {@code FINDING},
034     * or {@code ALWAYS} values, although it is possible to create a new dereference
035     * policy with a specified integer value if necessary using the
036     * {@code valueOf(int)} method.  The following dereference policy values are
037     * defined:
038     * <UL>
039     *   <LI>{@code NEVER} -- Indicates that the server should not dereference any
040     *       aliases that it encounters.</LI>
041     *   <LI>{@code SEARCHING} -- Indicates that the server should dereference any
042     *       aliases that it may encounter while examining candidate entries, but it
043     *       should not dereference the base entry if it happens to be an alias
044     *       entry.</LI>
045     *   <LI>{@code FINDING} -- Indicates that the server should dereference the
046     *       base entry if it happens to be an alias entry, but it should not
047     *       dereference any alias entries that may be encountered while examining
048     *       candidate entries.</LI>
049     *   <LI>{@code ALWAYS} -- Indicates that the server should dereference the base
050     *       entry if it happens to be an alias entry, and should also dereference
051     *       any entries that may be encountered while examining candidates.</LI>
052     * </UL>
053     */
054    public final class DereferencePolicy
055           implements Serializable
056    {
057      /**
058       * A predefined dereference policy value which indicates that the server
059       * should not dereference any aliases that it encounters.
060       */
061      public static final DereferencePolicy NEVER =
062           new DereferencePolicy("NEVER", 0);
063    
064    
065    
066      /**
067       * A predefined dereference policy value which indicates that the server
068       * should dereference any aliases that it may encounter while examining
069       * candidate entries, but it should not dereference the base entry if it
070       * happens to be an alias entry.
071       */
072      public static final DereferencePolicy SEARCHING =
073           new DereferencePolicy("SEARCHING", 1);
074    
075    
076    
077      /**
078       * A predefined dereference policy value which indicates that the server
079       * should dereference the base entry if it happens to be an alias entry, but
080       * it should not dereference any alias entries that may be encountered while
081       * examining candidate entries.
082       */
083      public static final DereferencePolicy FINDING =
084           new DereferencePolicy("FINDING", 2);
085    
086    
087    
088      /**
089       * A predefined dereference policy value which indicates that the server
090       * should dereference the base entry if it happens to be an alias entry, and
091       * should also dereference any entries that may be encountered while examining
092       * candidates.
093       */
094      public static final DereferencePolicy ALWAYS =
095           new DereferencePolicy("ALWAYS", 3);
096    
097    
098    
099      /**
100       * The set of dereference policy objects created with undefined int values.
101       */
102      private static final HashMap<Integer,DereferencePolicy> UNDEFINED_POLICIES =
103           new HashMap<Integer,DereferencePolicy>();
104    
105    
106    
107      /**
108       * The serial version UID for this serializable class.
109       */
110      private static final long serialVersionUID = 3722883359911755096L;
111    
112    
113    
114      // The integer value for this dereference policy.
115      private final int intValue;
116    
117      // The name to use for this dereference policy.
118      private final String name;
119    
120    
121    
122      /**
123       * Creates a new dereference policy with the specified integer value.
124       *
125       * @param  intValue  The integer value to use for this dereference policy.
126       */
127      private DereferencePolicy(final int intValue)
128      {
129        this.intValue = intValue;
130    
131        name = String.valueOf(intValue);
132      }
133    
134    
135    
136      /**
137       * Creates a new dereference policy with the specified name and integer value.
138       *
139       * @param  name      The name to use for this dereference policy.
140       * @param  intValue  The integer value to use for this dereference policy.
141       */
142      private DereferencePolicy(final String name, final int intValue)
143      {
144        this.name     = name;
145        this.intValue = intValue;
146      }
147    
148    
149    
150      /**
151       * Retrieves the name for this dereference policy.
152       *
153       * @return  The name for this dereference policy.
154       */
155      public String getName()
156      {
157        return name;
158      }
159    
160    
161    
162      /**
163       * Retrieves the integer value for this dereference policy.
164       *
165       * @return  The integer value for this dereference policy.
166       */
167      public int intValue()
168      {
169        return intValue;
170      }
171    
172    
173    
174      /**
175       * Retrieves the dereference policy with the specified integer value.
176       *
177       * @param  intValue  The integer value for which to retrieve the corresponding
178       *                   dereference policy.
179       *
180       * @return  The dereference policy with the specified integer value, or a new
181       *          dereference policy if the provided value does not match any of the
182       *          predefined policies.
183       */
184      public static DereferencePolicy valueOf(final int intValue)
185      {
186        switch (intValue)
187        {
188          case 0:
189            return NEVER;
190          case 1:
191            return SEARCHING;
192          case 2:
193            return FINDING;
194          case 3:
195            return ALWAYS;
196          default:
197            synchronized (UNDEFINED_POLICIES)
198            {
199              DereferencePolicy p = UNDEFINED_POLICIES.get(intValue);
200              if (p == null)
201              {
202                p = new DereferencePolicy(intValue);
203                UNDEFINED_POLICIES.put(intValue, p);
204              }
205    
206              return p;
207            }
208        }
209      }
210    
211    
212    
213      /**
214       * Retrieves the predefined dereference policy with the specified integer
215       * value.
216       *
217       * @param  intValue  The integer value for which to retrieve the corresponding
218       *                   dereference policy.
219       *
220       * @return  The dereference policy with the specified integer value, or
221       *          {@code null} if the provided value does not match any of the
222       *          predefined policies.
223       */
224      public static DereferencePolicy definedValueOf(final int intValue)
225      {
226        switch (intValue)
227        {
228          case 0:
229            return NEVER;
230          case 1:
231            return SEARCHING;
232          case 2:
233            return FINDING;
234          case 3:
235            return ALWAYS;
236          default:
237            return null;
238        }
239      }
240    
241    
242    
243      /**
244       * Retrieves an array of all dereference policies defined in the LDAP SDK.
245       *
246       * @return  An array of all dereference policies defined in the LDAP SDK.
247       */
248      public static DereferencePolicy[] values()
249      {
250        return new DereferencePolicy[]
251        {
252          NEVER,
253          SEARCHING,
254          FINDING,
255          ALWAYS
256        };
257      }
258    
259    
260    
261      /**
262       * The hash code for this dereference policy.
263       *
264       * @return  The hash code for this dereference policy.
265       */
266      @Override()
267      public int hashCode()
268      {
269        return intValue;
270      }
271    
272    
273    
274      /**
275       * Indicates whether the provided object is equal to this dereference policy.
276       *
277       * @param  o  The object for which to make the determination.
278       *
279       * @return  {@code true} if the provided object is a dereference policy that
280       *          is equal to this dereference policy, or {@code false} if not.
281       */
282      @Override()
283      public boolean equals(final Object o)
284      {
285        if (o == null)
286        {
287          return false;
288        }
289        else if (o == this)
290        {
291          return true;
292        }
293        else if (o instanceof DereferencePolicy)
294        {
295          return (intValue == ((DereferencePolicy) o).intValue);
296        }
297        else
298        {
299          return false;
300        }
301      }
302    
303    
304    
305      /**
306       * Retrieves a string representation of this dereference policy.
307       *
308       * @return  A string representation of this dereference policy.
309       */
310      @Override()
311      public String toString()
312      {
313        return name;
314      }
315    }