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