001/*
002 * Copyright 2007-2020 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2007-2020 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2008-2020 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk;
037
038
039
040import java.io.Serializable;
041import java.util.HashMap;
042
043import com.unboundid.util.NotMutable;
044import com.unboundid.util.StaticUtils;
045import com.unboundid.util.ThreadSafety;
046import com.unboundid.util.ThreadSafetyLevel;
047
048
049
050/**
051 * This class defines a data type for dereference policy values.  Clients should
052 * generally use one of the {@code NEVER}, {@code SEARCHING}, {@code FINDING},
053 * or {@code ALWAYS} values, although it is possible to create a new dereference
054 * policy with a specified integer value if necessary using the
055 * {@link #valueOf(int)} method.  The following dereference policy values are
056 * defined:
057 * <UL>
058 *   <LI>{@code NEVER} -- Indicates that the server should not dereference any
059 *       aliases that it encounters.</LI>
060 *   <LI>{@code SEARCHING} -- Indicates that the server should dereference any
061 *       aliases that it may encounter while examining candidate entries, but it
062 *       should not dereference the base entry if it happens to be an alias
063 *       entry.</LI>
064 *   <LI>{@code FINDING} -- Indicates that the server should dereference the
065 *       base entry if it happens to be an alias entry, but it should not
066 *       dereference any alias entries that may be encountered while examining
067 *       candidate entries.</LI>
068 *   <LI>{@code ALWAYS} -- Indicates that the server should dereference the base
069 *       entry if it happens to be an alias entry, and should also dereference
070 *       any entries that may be encountered while examining candidates.</LI>
071 * </UL>
072 */
073@NotMutable()
074@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
075public final class DereferencePolicy
076       implements Serializable
077{
078  /**
079   * A predefined dereference policy value which indicates that the server
080   * should not dereference any aliases that it encounters.
081   */
082  public static final DereferencePolicy NEVER =
083       new DereferencePolicy("NEVER", 0);
084
085
086
087  /**
088   * A predefined dereference policy value which indicates that the server
089   * should dereference any aliases that it may encounter while examining
090   * candidate entries, but it should not dereference the base entry if it
091   * happens to be an alias entry.
092   */
093  public static final DereferencePolicy SEARCHING =
094       new DereferencePolicy("SEARCHING", 1);
095
096
097
098  /**
099   * A predefined dereference policy value which indicates that the server
100   * should dereference the base entry if it happens to be an alias entry, but
101   * it should not dereference any alias entries that may be encountered while
102   * examining candidate entries.
103   */
104  public static final DereferencePolicy FINDING =
105       new DereferencePolicy("FINDING", 2);
106
107
108
109  /**
110   * A predefined dereference policy value which indicates that the server
111   * should dereference the base entry if it happens to be an alias entry, and
112   * should also dereference any entries that may be encountered while examining
113   * candidates.
114   */
115  public static final DereferencePolicy ALWAYS =
116       new DereferencePolicy("ALWAYS", 3);
117
118
119
120  /**
121   * The set of dereference policy objects created with undefined int values.
122   */
123  private static final HashMap<Integer,DereferencePolicy> UNDEFINED_POLICIES =
124       new HashMap<>(StaticUtils.computeMapCapacity(10));
125
126
127
128  /**
129   * The serial version UID for this serializable class.
130   */
131  private static final long serialVersionUID = 3722883359911755096L;
132
133
134
135  // The integer value for this dereference policy.
136  private final int intValue;
137
138  // The name to use for this dereference policy.
139  private final String name;
140
141
142
143  /**
144   * Creates a new dereference policy with the specified integer value.
145   *
146   * @param  intValue  The integer value to use for this dereference policy.
147   */
148  private DereferencePolicy(final int intValue)
149  {
150    this.intValue = intValue;
151
152    name = String.valueOf(intValue);
153  }
154
155
156
157  /**
158   * Creates a new dereference policy with the specified name and integer value.
159   *
160   * @param  name      The name to use for this dereference policy.
161   * @param  intValue  The integer value to use for this dereference policy.
162   */
163  private DereferencePolicy(final String name, final int intValue)
164  {
165    this.name     = name;
166    this.intValue = intValue;
167  }
168
169
170
171  /**
172   * Retrieves the name for this dereference policy.
173   *
174   * @return  The name for this dereference policy.
175   */
176  public String getName()
177  {
178    return name;
179  }
180
181
182
183  /**
184   * Retrieves the integer value for this dereference policy.
185   *
186   * @return  The integer value for this dereference policy.
187   */
188  public int intValue()
189  {
190    return intValue;
191  }
192
193
194
195  /**
196   * Retrieves the dereference policy with the specified integer value.
197   *
198   * @param  intValue  The integer value for which to retrieve the corresponding
199   *                   dereference policy.
200   *
201   * @return  The dereference policy with the specified integer value, or a new
202   *          dereference policy if the provided value does not match any of the
203   *          predefined policies.
204   */
205  public static DereferencePolicy valueOf(final int intValue)
206  {
207    switch (intValue)
208    {
209      case 0:
210        return NEVER;
211      case 1:
212        return SEARCHING;
213      case 2:
214        return FINDING;
215      case 3:
216        return ALWAYS;
217      default:
218        synchronized (UNDEFINED_POLICIES)
219        {
220          DereferencePolicy p = UNDEFINED_POLICIES.get(intValue);
221          if (p == null)
222          {
223            p = new DereferencePolicy(intValue);
224            UNDEFINED_POLICIES.put(intValue, p);
225          }
226
227          return p;
228        }
229    }
230  }
231
232
233
234  /**
235   * Retrieves the predefined dereference policy with the specified integer
236   * value.
237   *
238   * @param  intValue  The integer value for which to retrieve the corresponding
239   *                   dereference policy.
240   *
241   * @return  The dereference policy with the specified integer value, or
242   *          {@code null} if the provided value does not match any of the
243   *          predefined policies.
244   */
245  public static DereferencePolicy definedValueOf(final int intValue)
246  {
247    switch (intValue)
248    {
249      case 0:
250        return NEVER;
251      case 1:
252        return SEARCHING;
253      case 2:
254        return FINDING;
255      case 3:
256        return ALWAYS;
257      default:
258        return null;
259    }
260  }
261
262
263
264  /**
265   * Retrieves an array of all dereference policies defined in the LDAP SDK.
266   *
267   * @return  An array of all dereference policies defined in the LDAP SDK.
268   */
269  public static DereferencePolicy[] values()
270  {
271    return new DereferencePolicy[]
272    {
273      NEVER,
274      SEARCHING,
275      FINDING,
276      ALWAYS
277    };
278  }
279
280
281
282  /**
283   * The hash code for this dereference policy.
284   *
285   * @return  The hash code for this dereference policy.
286   */
287  @Override()
288  public int hashCode()
289  {
290    return intValue;
291  }
292
293
294
295  /**
296   * Indicates whether the provided object is equal to this dereference policy.
297   *
298   * @param  o  The object for which to make the determination.
299   *
300   * @return  {@code true} if the provided object is a dereference policy that
301   *          is equal to this dereference policy, or {@code false} if not.
302   */
303  @Override()
304  public boolean equals(final Object o)
305  {
306    if (o == null)
307    {
308      return false;
309    }
310    else if (o == this)
311    {
312      return true;
313    }
314    else if (o instanceof DereferencePolicy)
315    {
316      return (intValue == ((DereferencePolicy) o).intValue);
317    }
318    else
319    {
320      return false;
321    }
322  }
323
324
325
326  /**
327   * Retrieves a string representation of this dereference policy.
328   *
329   * @return  A string representation of this dereference policy.
330   */
331  @Override()
332  public String toString()
333  {
334    return name;
335  }
336}