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