001    /*
002     * Copyright 2007-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2015 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 an array of all dereference policies defined in the LDAP SDK.
220       *
221       * @return  An array of all dereference policies defined in the LDAP SDK.
222       */
223      public static DereferencePolicy[] values()
224      {
225        return new DereferencePolicy[]
226        {
227          NEVER,
228          SEARCHING,
229          FINDING,
230          ALWAYS
231        };
232      }
233    
234    
235    
236      /**
237       * The hash code for this dereference policy.
238       *
239       * @return  The hash code for this dereference policy.
240       */
241      @Override()
242      public int hashCode()
243      {
244        return intValue;
245      }
246    
247    
248    
249      /**
250       * Indicates whether the provided object is equal to this dereference policy.
251       *
252       * @param  o  The object for which to make the determination.
253       *
254       * @return  {@code true} if the provided object is a dereference policy that
255       *          is equal to this dereference policy, or {@code false} if not.
256       */
257      @Override()
258      public boolean equals(final Object o)
259      {
260        if (o == null)
261        {
262          return false;
263        }
264        else if (o == this)
265        {
266          return true;
267        }
268        else if (o instanceof DereferencePolicy)
269        {
270          return (intValue == ((DereferencePolicy) o).intValue);
271        }
272        else
273        {
274          return false;
275        }
276      }
277    
278    
279    
280      /**
281       * Retrieves a string representation of this dereference policy.
282       *
283       * @return  A string representation of this dereference policy.
284       */
285      @Override()
286      public String toString()
287      {
288        return name;
289      }
290    }