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