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 */
021package com.unboundid.ldap.sdk;
022
023
024
025import java.io.Serializable;
026import java.util.HashMap;
027
028import com.unboundid.util.NotMutable;
029import com.unboundid.util.ThreadSafety;
030import 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)
059public 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}