001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2006-2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.core; 028 029 import java.util.LinkedHashSet; 030 import java.util.List; 031 032 import org.opends.server.controls.MatchedValuesControl; 033 import org.opends.server.types.ByteString; 034 import org.opends.server.types.Control; 035 import org.opends.server.types.DN; 036 import org.opends.server.types.DereferencePolicy; 037 import org.opends.server.types.DirectoryException; 038 import org.opends.server.types.Entry; 039 import org.opends.server.types.Operation; 040 import org.opends.server.types.RawFilter; 041 import org.opends.server.types.SearchFilter; 042 import org.opends.server.types.SearchResultEntry; 043 import org.opends.server.types.SearchResultReference; 044 import org.opends.server.types.SearchScope; 045 046 /** 047 * This interface defines an operation used to search for entries 048 * in the Directory Server. 049 */ 050 public interface SearchOperation extends Operation 051 { 052 053 /** 054 * Retrieves the raw, unprocessed base DN as included in the request from the 055 * client. This may or may not contain a valid DN, as no validation will have 056 * been performed. 057 * 058 * @return The raw, unprocessed base DN as included in the request from the 059 * client. 060 */ 061 public abstract ByteString getRawBaseDN(); 062 063 /** 064 * Specifies the raw, unprocessed base DN as included in the request from the 065 * client. This method should only be called by pre-parse plugins. 066 * 067 * @param rawBaseDN The raw, unprocessed base DN as included in the request 068 * from the client. 069 */ 070 public abstract void setRawBaseDN(ByteString rawBaseDN); 071 072 /** 073 * Retrieves the base DN for this search operation. This should not be called 074 * by pre-parse plugins, as the raw base DN will not yet have been processed. 075 * Instead, they should use the <CODE>getRawBaseDN</CODE> method. 076 * 077 * @return The base DN for this search operation, or <CODE>null</CODE> if the 078 * raw base DN has not yet been processed. 079 */ 080 public abstract DN getBaseDN(); 081 082 /** 083 * Specifies the base DN for this search operation. This method is only 084 * intended for internal use. 085 * 086 * @param baseDN The base DN for this search operation. 087 */ 088 public abstract void setBaseDN(DN baseDN); 089 090 /** 091 * Retrieves the scope for this search operation. 092 * 093 * @return The scope for this search operation. 094 */ 095 public abstract SearchScope getScope(); 096 097 /** 098 * Specifies the scope for this search operation. This should only be called 099 * by pre-parse plugins. 100 * 101 * @param scope The scope for this search operation. 102 */ 103 public abstract void setScope(SearchScope scope); 104 105 /** 106 * Retrieves the alias dereferencing policy for this search operation. 107 * 108 * @return The alias dereferencing policy for this search operation. 109 */ 110 public abstract DereferencePolicy getDerefPolicy(); 111 112 /** 113 * Specifies the alias dereferencing policy for this search operation. This 114 * should only be called by pre-parse plugins. 115 * 116 * @param derefPolicy The alias dereferencing policy for this search 117 * operation. 118 */ 119 public abstract void setDerefPolicy(DereferencePolicy derefPolicy); 120 121 /** 122 * Retrieves the size limit for this search operation. 123 * 124 * @return The size limit for this search operation. 125 */ 126 public abstract int getSizeLimit(); 127 128 /** 129 * Specifies the size limit for this search operation. This should only be 130 * called by pre-parse plugins. 131 * 132 * @param sizeLimit The size limit for this search operation. 133 */ 134 public abstract void setSizeLimit(int sizeLimit); 135 136 /** 137 * Retrieves the time limit for this search operation. 138 * 139 * @return The time limit for this search operation. 140 */ 141 public abstract int getTimeLimit(); 142 143 /** 144 * Get the time after which the search time limit has expired. 145 * 146 * @return the timeLimitExpiration 147 */ 148 public abstract Long getTimeLimitExpiration(); 149 150 /** 151 * Specifies the time limit for this search operation. This should only be 152 * called by pre-parse plugins. 153 * 154 * @param timeLimit The time limit for this search operation. 155 */ 156 public abstract void setTimeLimit(int timeLimit); 157 158 /** 159 * Retrieves the typesOnly flag for this search operation. 160 * 161 * @return The typesOnly flag for this search operation. 162 */ 163 public abstract boolean getTypesOnly(); 164 165 /** 166 * Specifies the typesOnly flag for this search operation. This should only 167 * be called by pre-parse plugins. 168 * 169 * @param typesOnly The typesOnly flag for this search operation. 170 */ 171 public abstract void setTypesOnly(boolean typesOnly); 172 173 /** 174 * Retrieves the raw, unprocessed search filter as included in the request 175 * from the client. It may or may not contain a valid filter (e.g., 176 * unsupported attribute types or values with an invalid syntax) because no 177 * validation will have been performed on it. 178 * 179 * @return The raw, unprocessed search filter as included in the request from 180 * the client. 181 */ 182 public abstract RawFilter getRawFilter(); 183 184 /** 185 * Specifies the raw, unprocessed search filter as included in the request 186 * from the client. This method should only be called by pre-parse plugins. 187 * 188 * @param rawFilter The raw, unprocessed search filter as included in the 189 * request from the client. 190 */ 191 public abstract void setRawFilter(RawFilter rawFilter); 192 193 /** 194 * Retrieves the filter for this search operation. This should not be called 195 * by pre-parse plugins, because the raw filter will not yet have been 196 * processed. 197 * 198 * @return The filter for this search operation, or <CODE>null</CODE> if the 199 * raw filter has not yet been processed. 200 */ 201 public abstract SearchFilter getFilter(); 202 203 /** 204 * Retrieves the set of requested attributes for this search operation. Its 205 * contents should not be be altered. 206 * 207 * @return The set of requested attributes for this search operation. 208 */ 209 public abstract LinkedHashSet<String> getAttributes(); 210 211 /** 212 * Specifies the set of requested attributes for this search operation. It 213 * should only be called by pre-parse plugins. 214 * 215 * @param attributes The set of requested attributes for this search 216 * operation. 217 */ 218 public abstract void setAttributes(LinkedHashSet<String> attributes); 219 220 /** 221 * Retrieves the number of entries sent to the client for this search 222 * operation. 223 * 224 * @return The number of entries sent to the client for this search 225 * operation. 226 */ 227 public abstract int getEntriesSent(); 228 229 /** 230 * Retrieves the number of search references sent to the client for this 231 * search operation. 232 * 233 * @return The number of search references sent to the client for this search 234 * operation. 235 */ 236 public abstract int getReferencesSent(); 237 238 /** 239 * Used as a callback for backends to indicate that the provided entry matches 240 * the search criteria and that additional processing should be performed to 241 * potentially send it back to the client. 242 * 243 * @param entry The entry that matches the search criteria and should be 244 * sent to the client. 245 * @param controls The set of controls to include with the entry (may be 246 * <CODE>null</CODE> if none are needed). 247 * 248 * @return <CODE>true</CODE> if the caller should continue processing the 249 * search request and sending additional entries and references, or 250 * <CODE>false</CODE> if not for some reason (e.g., the size limit 251 * has been reached or the search has been abandoned). 252 */ 253 public abstract boolean returnEntry(Entry entry, List<Control> controls); 254 255 /** 256 * Used as a callback for backends to indicate that the provided search 257 * reference was encountered during processing and that additional processing 258 * should be performed to potentially send it back to the client. 259 * 260 * @param reference The search reference to send to the client. 261 * @param dn The DN related to the specified search reference. 262 * 263 * @return <CODE>true</CODE> if the caller should continue processing the 264 * search request and sending additional entries and references , or 265 * <CODE>false</CODE> if not for some reason (e.g., the size limit 266 * has been reached or the search has been abandoned). 267 */ 268 public abstract boolean returnReference(DN dn, 269 SearchResultReference reference); 270 271 /** 272 * Sends the search result done message to the client. Note that this method 273 * should only be called from external classes in special cases (e.g., 274 * persistent search) where they are sure that the result won't be sent by the 275 * core server. Also note that the result code and optionally the error 276 * message should have been set for this operation before this method is 277 * called. 278 */ 279 public abstract void sendSearchResultDone(); 280 281 /** 282 * Set the time after which the search time limit has expired. 283 * 284 * @param timeLimitExpiration - Time after which the search has expired 285 */ 286 public abstract void setTimeLimitExpiration(Long timeLimitExpiration); 287 288 /** 289 * Indicates whether LDAP subentries should be returned or not. 290 * 291 * @return true if the LDAP subentries should be returned, false otherwise 292 */ 293 public abstract boolean isReturnLDAPSubentries(); 294 295 /** 296 * Set the flag indicating wether the LDAP subentries should be returned. 297 * 298 * @param returnLDAPSubentries - Boolean indicating wether the LDAP 299 * subentries should be returned or not 300 */ 301 public abstract void setReturnLDAPSubentries(boolean returnLDAPSubentries); 302 303 /** 304 * The matched values control associated with this search operation. 305 * 306 * @return the match values control 307 */ 308 public abstract MatchedValuesControl getMatchedValuesControl(); 309 310 /** 311 * Set the match values control. 312 * 313 * @param controls - The matched values control 314 */ 315 public abstract void setMatchedValuesControl(MatchedValuesControl controls); 316 317 /** 318 * Indicates whether to include the account usable response control with 319 * search result entries or not. 320 * 321 * @return true if the usable control has to be part of the search result 322 * entry 323 */ 324 public abstract boolean isIncludeUsableControl(); 325 326 /** 327 * Specify whether to include the account usable response control within the 328 * search result entries. 329 * 330 * @param includeUsableControl - True if the account usable response control 331 * has to be included within the search result 332 * entries, false otherwise 333 */ 334 public abstract void setIncludeUsableControl(boolean includeUsableControl); 335 336 /** 337 * Register the psearch in the search operation. 338 * 339 * @param psearch - Persistent search associated to that operation 340 */ 341 public abstract void setPersistentSearch(PersistentSearch psearch); 342 343 /** 344 * Get the psearch from the search operation. 345 * 346 * @return the psearch, or null if no psearch was registered 347 */ 348 public abstract PersistentSearch getPersistentSearch(); 349 350 /** 351 * Indicates whether the client is able to handle referrals. 352 * 353 * @return true, if the client is able to handle referrals 354 */ 355 public abstract boolean isClientAcceptsReferrals(); 356 357 /** 358 * Specify whether the client is able to handle referrals. 359 * 360 * @param clientAcceptReferrals - Boolean set to true if the client 361 * can handle referrals 362 */ 363 public abstract void setClientAcceptsReferrals(boolean clientAcceptReferrals); 364 365 /** 366 * Increments by 1 the number of entries sent to the client for this search 367 * operation. 368 */ 369 public abstract void incrementEntriesSent(); 370 371 /** 372 * Increments by 1 the number of search references sent to the client for this 373 * search operation. 374 */ 375 public abstract void incrementReferencesSent(); 376 377 /** 378 * Indicates wether the search result done message has to be sent 379 * to the client, or not. 380 * 381 * @return true if the search result done message is to be sent to the client 382 */ 383 public abstract boolean isSendResponse(); 384 385 /** 386 * Specify wether the search result done message has to be sent 387 * to the client, or not. 388 * 389 * @param sendResponse - boolean indicating wether the search result done 390 * message is to send to the client 391 */ 392 public abstract void setSendResponse(boolean sendResponse); 393 394 /** 395 * Returns true if only real attributes should be returned. 396 * 397 * @return true if only real attributes should be returned, false otherwise 398 */ 399 public abstract boolean isRealAttributesOnly(); 400 401 /** 402 * Specify wether to only return real attributes. 403 * 404 * @param realAttributesOnly - boolean setup to true, if only the real 405 * attributes should be returned 406 */ 407 public abstract void setRealAttributesOnly(boolean realAttributesOnly); 408 409 /** 410 * Returns true if only virtual attributes should be returned. 411 * 412 * @return true if only virtual attributes should be returned, false 413 * otherwise 414 */ 415 public abstract boolean isVirtualAttributesOnly(); 416 417 /** 418 * Specify wether to only return virtual attributes. 419 * 420 * @param virtualAttributesOnly - boolean setup to true, if only the virtual 421 * attributes should be returned 422 */ 423 public abstract void setVirtualAttributesOnly(boolean virtualAttributesOnly); 424 425 /** 426 * Sends the provided search result entry to the client. 427 * 428 * @param entry The search result entry to be sent to 429 * the client. 430 * 431 * @throws DirectoryException If a problem occurs while attempting 432 * to send the entry to the client and 433 * the search should be terminated. 434 */ 435 public abstract void sendSearchEntry(SearchResultEntry entry) 436 throws DirectoryException; 437 438 /** 439 * Sends the provided search result reference to the client. 440 * 441 * @param reference The search result reference to be sent 442 * to the client. 443 * 444 * @return <CODE>true</CODE> if the client is able to accept 445 * referrals, or <CODE>false</CODE> if the client cannot 446 * handle referrals and no more attempts should be made to 447 * send them for the associated search operation. 448 * 449 * @throws DirectoryException If a problem occurs while attempting 450 * to send the reference to the client 451 * and the search should be terminated. 452 */ 453 public abstract boolean sendSearchReference(SearchResultReference reference) 454 throws DirectoryException; 455 456 /** 457 * Retrieves the proxied authorization DN for this operation if proxied 458 * authorization has been requested. 459 * 460 * @return The proxied authorization DN for this operation if proxied 461 * authorization has been requested, or {@code null} if proxied 462 * authorization has not been requested. 463 */ 464 public abstract DN getProxiedAuthorizationDN(); 465 466 /** 467 * Set the proxied authorization DN for this operation if proxied 468 * authorization has been requested. 469 * 470 * @param proxiedAuthorizationDN 471 * The proxied authorization DN for this operation if proxied 472 * authorization has been requested, or {@code null} if proxied 473 * authorization has not been requested. 474 */ 475 public abstract void setProxiedAuthorizationDN(DN proxiedAuthorizationDN); 476 477 }