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