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