001 /*
002 * Copyright 2007-2016 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2008-2016 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 import com.unboundid.util.NotMutable;
029 import com.unboundid.util.ThreadSafety;
030 import 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)
059 public 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 the predefined dereference policy with the specified integer
220 * value.
221 *
222 * @param intValue The integer value for which to retrieve the corresponding
223 * dereference policy.
224 *
225 * @return The dereference policy with the specified integer value, or
226 * {@code null} if the provided value does not match any of the
227 * predefined policies.
228 */
229 public static DereferencePolicy definedValueOf(final int intValue)
230 {
231 switch (intValue)
232 {
233 case 0:
234 return NEVER;
235 case 1:
236 return SEARCHING;
237 case 2:
238 return FINDING;
239 case 3:
240 return ALWAYS;
241 default:
242 return null;
243 }
244 }
245
246
247
248 /**
249 * Retrieves an array of all dereference policies defined in the LDAP SDK.
250 *
251 * @return An array of all dereference policies defined in the LDAP SDK.
252 */
253 public static DereferencePolicy[] values()
254 {
255 return new DereferencePolicy[]
256 {
257 NEVER,
258 SEARCHING,
259 FINDING,
260 ALWAYS
261 };
262 }
263
264
265
266 /**
267 * The hash code for this dereference policy.
268 *
269 * @return The hash code for this dereference policy.
270 */
271 @Override()
272 public int hashCode()
273 {
274 return intValue;
275 }
276
277
278
279 /**
280 * Indicates whether the provided object is equal to this dereference policy.
281 *
282 * @param o The object for which to make the determination.
283 *
284 * @return {@code true} if the provided object is a dereference policy that
285 * is equal to this dereference policy, or {@code false} if not.
286 */
287 @Override()
288 public boolean equals(final Object o)
289 {
290 if (o == null)
291 {
292 return false;
293 }
294 else if (o == this)
295 {
296 return true;
297 }
298 else if (o instanceof DereferencePolicy)
299 {
300 return (intValue == ((DereferencePolicy) o).intValue);
301 }
302 else
303 {
304 return false;
305 }
306 }
307
308
309
310 /**
311 * Retrieves a string representation of this dereference policy.
312 *
313 * @return A string representation of this dereference policy.
314 */
315 @Override()
316 public String toString()
317 {
318 return name;
319 }
320 }