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}