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