001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved 005 * 006 * The contents of this file are subject to the terms 007 * of the Common Development and Distribution License 008 * (the License). You may not use this file except in 009 * compliance with the License. 010 * 011 * You can obtain a copy of the License at 012 * https://opensso.dev.java.net/public/CDDLv1.0.html or 013 * opensso/legal/CDDLv1.0.txt 014 * See the License for the specific language governing 015 * permission and limitations under the License. 016 * 017 * When distributing Covered Code, include this CDDL 018 * Header Notice in each file and include the License file 019 * at opensso/legal/CDDLv1.0.txt. 020 * If applicable, add the following below the CDDL Header, 021 * with the fields enclosed by brackets [] replaced by 022 * your own identifying information: 023 * "Portions Copyrighted [year] [name of copyright owner]" 024 * 025 * $Id: SearchControl.java,v 1.5 2009/01/28 05:34:51 ww203982 Exp $ 026 * 027 * Portions Copyright 2015 ForgeRock AS. 028 */ 029 030package com.iplanet.ums; 031 032import java.util.Hashtable; 033 034import org.forgerock.opendj.ldap.SearchScope; 035 036/** 037 * This class provides a way to customize Search behaviors. Common behaviors are 038 * time limit, result limit and Virtual list view. In future, we will provide 039 * ways for client to define different hierarchical tree through SearchControl. 040 * 041 * @supported.api 042 */ 043public class SearchControl implements java.io.Serializable { 044 045 private static final long serialVersionUID = -8755868973524858945L; 046 047 static final String KeyVlvRange = "vlvRange"; 048 049 static final String KeyVlvJumpTo = "vlvJumpTo"; 050 051 static final String KeyTimeOut = "timeOut"; 052 053 static final String KeySortKeys = "sortKeys"; 054 055 static final String KeyMaxResults = "maxResults"; 056 057 static final String KeySearchScope = "searchScope"; 058 059 static final int DEFAULT_MAX_RESULTS = 0; 060 061 static final int DEFAULT_TIMEOUT = 0; 062 063 // Disabled by default 064 private static boolean getAllAttributesEnabled = false; 065 066 /** 067 * Search scope for one level. You use this search scope in getting 068 * immediate children of a container. This is the default search scope in 069 * getChildren method in search API. One can use 070 * SearchControl.setSearchScope to override the default search scope in 071 * getChildren. 072 * 073 * @supported.api 074 */ 075 public static final int SCOPE_ONE = SearchScope.SINGLE_LEVEL.intValue(); 076 077 /** 078 * Search scope for subtree level. This scope is used as the default search 079 * scope in the search API. One can use SearchControl.setSearchScope to 080 * override the default search scope in search methods. 081 * 082 * @supported.api 083 */ 084 public static final int SCOPE_SUB = SearchScope.WHOLE_SUBTREE.intValue(); 085 086 /** 087 * Search scope for just this object. 088 * 089 * @supported.api 090 */ 091 public static final int SCOPE_BASE = SearchScope.BASE_OBJECT.intValue(); 092 093 /** 094 * Set sort order based on attribute names. 095 * 096 * @param attributeNames 097 * array of attribute names to sort on 098 * @supported.api 099 */ 100 public void setSortKeys(String[] attributeNames) { 101 SortKey[] sortKeys; 102 if (attributeNames == null) 103 return; 104 105 sortKeys = new SortKey[attributeNames.length]; 106 for (int i = 0; i < sortKeys.length; i++) { 107 sortKeys[i] = new SortKey(); 108 sortKeys[i].attributeName = attributeNames[i]; 109 sortKeys[i].reverse = false; 110 } 111 112 set(KeySortKeys, sortKeys); 113 } 114 115 /** 116 * Set sort order based on SortKey 117 * 118 * @param sortKeys 119 * array of SortKey. 120 * @supported.api 121 */ 122 public void setSortKeys(SortKey[] sortKeys) { 123 set(KeySortKeys, sortKeys); 124 } 125 126 /** 127 * Get existing attribute names for sorting. 128 * @supported.api 129 */ 130 public SortKey[] getSortKeys() { 131 return (SortKey[]) get(KeySortKeys); 132 } 133 134 /** 135 * Set range for retrieving VLV data. 136 * 137 * @param startIndex 138 * starting position 139 * @param beforeCount 140 * Number of entries before the startIndex 141 * @param afterCount 142 * Number of entries after the startIndex. 143 * @supported.api 144 */ 145 public void setVLVRange(int startIndex, int beforeCount, int afterCount) { 146 int[] range = new int[3]; 147 range[0] = startIndex; 148 range[1] = beforeCount; 149 range[2] = afterCount; 150 151 set(KeyVlvRange, range); 152 } 153 154 /** 155 * Set range for retrieving VLV data. 156 * 157 * @param jumpTo 158 * Search expression defining the result set return 159 * @param beforeCount 160 * Number of entries before the startIndex 161 * @param afterCount 162 * Number of entries after the startIndex. 163 * @supported.api 164 */ 165 public void setVLVRange(String jumpTo, int beforeCount, int afterCount) { 166 int[] range = new int[3]; 167 168 range[0] = 0; 169 range[1] = beforeCount; 170 range[2] = afterCount; 171 172 set(KeyVlvJumpTo, jumpTo); 173 set(KeyVlvRange, range); 174 } 175 176 /** 177 * Get range for current VLV setting. 178 * 179 * @return array of int which contain startIndex, beforeCount and 180 * afterCount. 181 * @supported.api 182 */ 183 public int[] getVLVRange() { 184 return (int[]) get(KeyVlvRange); 185 } 186 187 /** 188 * Get jumpTo value for VLV range. 189 * 190 * @return jumpTo value. 191 * @supported.api 192 */ 193 public String getVLVJumpTo() { 194 return (String) get(KeyVlvJumpTo); 195 } 196 197 /** 198 * Sets the maximum number of milliseconds to wait for any operation for the 199 * search. 200 * 201 * @param timeOut 202 * Max number of milliseconds. 203 * @supported.api 204 */ 205 public void setTimeOut(int timeOut) { 206 set(KeyTimeOut, new Integer(timeOut)); 207 } 208 209 /** 210 * Get current time out setting. 211 * @supported.api 212 */ 213 public int getTimeOut() { 214 Integer i = (Integer) get(KeyTimeOut); 215 if (i == null) { 216 return DEFAULT_TIMEOUT; 217 } else { 218 return i.intValue(); 219 } 220 } 221 222 /** 223 * Sets the maximum number of search results to return; 0 means there is no 224 * limit. 225 * @supported.api 226 */ 227 public void setMaxResults(int maxNumber) { 228 set(KeyMaxResults, new Integer(maxNumber)); 229 } 230 231 /** 232 * Gets the maximum number of search results to return. return 0 means there 233 * is no limit. 234 * @supported.api 235 */ 236 public int getMaxResults() { 237 Integer i = (Integer) get(KeyMaxResults); 238 if (i == null) { 239 return DEFAULT_MAX_RESULTS; 240 } else { 241 return i.intValue(); 242 } 243 } 244 245 /** 246 * Sets the search scope in SearchControl. 247 * 248 * @param scope 249 * Search scope defined in the SearchControl to be used with the 250 * search API. 251 * @supported.api 252 */ 253 public void setSearchScope(int scope) { 254 set(KeySearchScope, new Integer(scope)); 255 } 256 257 /** 258 * Gets the search scope defined in the SearchControl. 259 * 260 * @return search scope defined in the SearchControl. If search scope is 261 * never defined in the SearchControl SCOPE_SUB for subtree type of 262 * search is assumed. 263 * @supported.api 264 */ 265 public int getSearchScope() { 266 Integer scope = (Integer) get(KeySearchScope); 267 if (scope != null) { 268 return scope.intValue(); 269 } else { 270 return SearchControl.SCOPE_SUB; 271 } 272 } 273 274 /** 275 * Gets the search scope defined in the SearchControl. Allow user to specify 276 * default search scope if nothing has been defined in the SearchControl 277 * yet. 278 * 279 * @param defaultScope 280 * Scope value to be used in case the SearchControl is not set up 281 * with a search scope 282 * 283 * @return Search scope defined in the SearchControl. Return defaultScope if 284 * scope is not defined in the control. 285 * @supported.api 286 */ 287 public int getSearchScope(int defaultScope) { 288 Integer scope = (Integer) get(KeySearchScope); 289 if (scope != null) { 290 return scope.intValue(); 291 } else { 292 return defaultScope; 293 } 294 } 295 296 /** 297 * Sets internal attribute value in SearchControl 298 */ 299 protected void set(String name, Object o) { 300 m_hashTable.put(name, o); 301 } 302 303 /** 304 * Gets internal attribute defined in SearchControl 305 * 306 * @param name 307 * Name of attribute to get 308 * @return Object representing the value of the attribute. Return null 309 * object if the given attribute name is not found 310 */ 311 protected Object get(String name) { 312 return m_hashTable.get(name); 313 } 314 315 /** 316 * Checks if an internal attribute is defined for the control 317 * 318 * @param name 319 * Name of internal attribute to check against 320 * @return <code>true</code> if internal attribute is defined in the 321 * control and <code>false</code> otherwise 322 */ 323 protected boolean contains(String name) { 324 return m_hashTable.containsKey(name); 325 } 326 327 /** 328 * Sets the specified boolean value to the variable. Boolean value is set to 329 * true, if all attributes of the entries need to be obtained as part of the 330 * search. 331 * 332 * NOTE: If this getAllReturnAttributes boolean is set to true as part of 333 * AMSearchControl, it overrides any other setReturnAttributes set as part 334 * of the AMSearchControl. This is similar to using a wildcard '*' in 335 * search. 336 * 337 * When all the return attributes are set, the return attributes can be 338 * obtained as a map with DN as map-key and set of attribute values as 339 * map-value from AMSearchResults object. 340 * 341 * @param getAllAttributes 342 * Boolean value set to true as part of the AMSearchControl to 343 * obtain all attributes as part of the search. 344 * 345 * 346 */ 347 public void setAllReturnAttributes(boolean getAllAttributes) { 348 getAllAttributesEnabled = getAllAttributes; 349 } 350 351 /** 352 * Method to check if the boolean getAllAttributesEnabled is enabled or 353 * disabled. 354 * 355 * @return Returns the value of the boolean getAllAttributesEnabled. Returns 356 * true or false. 357 */ 358 public boolean isGetAllReturnAttributesEnabled() { 359 return getAllAttributesEnabled; 360 } 361 362 private Hashtable m_hashTable = new Hashtable(); 363}