/* * CDDL HEADER START * * The contents of this file are subject to the terms of the * Common Development and Distribution License, Version 1.0 only * (the "License"). You may not use this file except in compliance * with the License. * * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt * or http://forgerock.org/license/CDDLv1.0.html. * See the License for the specific language governing permissions * and limitations under the License. * * When distributing Covered Code, include this CDDL HEADER in each * file and include the License file at legal-notices/CDDLv1_0.txt. * If applicable, add the following below this CDDL HEADER, with the * fields enclosed by brackets "[]" replaced with your own identifying * information: * Portions Copyright [yyyy] [name of copyright owner] * * CDDL HEADER END * * * Copyright 2006-2009 Sun Microsystems, Inc. * Portions Copyright 2011-2014 ForgeRock AS */ package org.opends.server.core; import java.util.List; import java.util.Set; import org.opends.server.controls.ExternalChangelogRequestControl; import org.opends.server.controls.MatchedValuesControl; import org.opends.server.types.*; /** * This interface defines an operation used to search for entries * in the Directory Server. */ public interface SearchOperation extends Operation { /** * Retrieves the raw, unprocessed base DN as included in the request from the * client. This may or may not contain a valid DN, as no validation will have * been performed. * * @return The raw, unprocessed base DN as included in the request from the * client. */ public abstract ByteString getRawBaseDN(); /** * Specifies the raw, unprocessed base DN as included in the request from the * client. This method should only be called by pre-parse plugins. * * @param rawBaseDN The raw, unprocessed base DN as included in the request * from the client. */ public abstract void setRawBaseDN(ByteString rawBaseDN); /** * Retrieves the base DN for this search operation. This should not be called * by pre-parse plugins, as the raw base DN will not yet have been processed. * Instead, they should use the getRawBaseDN method. * * @return The base DN for this search operation, or null if the * raw base DN has not yet been processed. */ public abstract DN getBaseDN(); /** * Specifies the base DN for this search operation. This method is only * intended for internal use. * * @param baseDN The base DN for this search operation. */ public abstract void setBaseDN(DN baseDN); /** * Retrieves the scope for this search operation. * * @return The scope for this search operation. */ public abstract SearchScope getScope(); /** * Specifies the scope for this search operation. This should only be called * by pre-parse plugins. * * @param scope The scope for this search operation. */ public abstract void setScope(SearchScope scope); /** * Retrieves the alias dereferencing policy for this search operation. * * @return The alias dereferencing policy for this search operation. */ public abstract DereferencePolicy getDerefPolicy(); /** * Specifies the alias dereferencing policy for this search operation. This * should only be called by pre-parse plugins. * * @param derefPolicy The alias dereferencing policy for this search * operation. */ public abstract void setDerefPolicy(DereferencePolicy derefPolicy); /** * Retrieves the size limit for this search operation. * * @return The size limit for this search operation. */ public abstract int getSizeLimit(); /** * Specifies the size limit for this search operation. This should only be * called by pre-parse plugins. * * @param sizeLimit The size limit for this search operation. */ public abstract void setSizeLimit(int sizeLimit); /** * Retrieves the time limit for this search operation. * * @return The time limit for this search operation. */ public abstract int getTimeLimit(); /** * Get the time after which the search time limit has expired. * * @return the timeLimitExpiration */ public abstract long getTimeLimitExpiration(); /** * Specifies the time limit for this search operation. This should only be * called by pre-parse plugins. * * @param timeLimit The time limit for this search operation. */ public abstract void setTimeLimit(int timeLimit); /** * Retrieves the typesOnly flag for this search operation. * * @return The typesOnly flag for this search operation. */ public abstract boolean getTypesOnly(); /** * Specifies the typesOnly flag for this search operation. This should only * be called by pre-parse plugins. * * @param typesOnly The typesOnly flag for this search operation. */ public abstract void setTypesOnly(boolean typesOnly); /** * Retrieves the raw, unprocessed search filter as included in the request * from the client. It may or may not contain a valid filter (e.g., * unsupported attribute types or values with an invalid syntax) because no * validation will have been performed on it. * * @return The raw, unprocessed search filter as included in the request from * the client. */ public abstract RawFilter getRawFilter(); /** * Specifies the raw, unprocessed search filter as included in the request * from the client. This method should only be called by pre-parse plugins. * * @param rawFilter The raw, unprocessed search filter as included in the * request from the client. */ public abstract void setRawFilter(RawFilter rawFilter); /** * Retrieves the filter for this search operation. This should not be called * by pre-parse plugins, because the raw filter will not yet have been * processed. * * @return The filter for this search operation, or null if the * raw filter has not yet been processed. */ public abstract SearchFilter getFilter(); /** * Retrieves the set of requested attributes for this search operation. Its * contents should not be altered. * * @return The set of requested attributes for this search operation. */ public abstract Set getAttributes(); /** * Specifies the set of requested attributes for this search operation. It * should only be called by pre-parse plugins. * * @param attributes The set of requested attributes for this search * operation. */ public abstract void setAttributes(Set attributes); /** * Retrieves the number of entries sent to the client for this search * operation. * * @return The number of entries sent to the client for this search * operation. */ public abstract int getEntriesSent(); /** * Retrieves the number of search references sent to the client for this * search operation. * * @return The number of search references sent to the client for this search * operation. */ public abstract int getReferencesSent(); /** * Used as a callback for backends to indicate that the provided entry matches * the search criteria and that additional processing should be performed to * potentially send it back to the client. * * @param entry The entry that matches the search criteria and should be * sent to the client. * @param controls The set of controls to include with the entry (may be * null if none are needed). * * @return true if the caller should continue processing the * search request and sending additional entries and references, or * false if not for some reason (e.g., the size limit * has been reached or the search has been abandoned). */ public abstract boolean returnEntry(Entry entry, List controls); /** * Used as a callback for backends to indicate that the provided entry matches * the search criteria and that additional processing should be performed to * potentially send it back to the client. * * @param entry The entry that matches the search criteria and should * be sent to the client. * @param controls The set of controls to include with the entry (may be * null if none are needed). * @param evaluateAci Indicates whether the access rights to the entry * should be evaluated. * * @return true if the caller should continue processing the * search request and sending additional entries and references, or * false if not for some reason (e.g., the size limit * has been reached or the search has been abandoned). */ public abstract boolean returnEntry(Entry entry, List controls, boolean evaluateAci); /** * Used as a callback for backends to indicate that the provided search * reference was encountered during processing and that additional processing * should be performed to potentially send it back to the client. * * @param reference The search reference to send to the client. * @param dn The DN related to the specified search reference. * * @return true if the caller should continue processing the * search request and sending additional entries and references , or * false if not for some reason (e.g., the size limit * has been reached or the search has been abandoned). */ public abstract boolean returnReference(DN dn, SearchResultReference reference); /** * Used as a callback for backends to indicate that the provided search * reference was encountered during processing and that additional processing * should be performed to potentially send it back to the client. * * @param reference The search reference to send to the client. * @param dn The DN related to the specified search reference. * @param evaluateAci Indicates whether the access rights to the entry * should be evaluated. * * @return true if the caller should continue processing the * search request and sending additional entries and references , or * false if not for some reason (e.g., the size limit * has been reached or the search has been abandoned). */ public abstract boolean returnReference(DN dn, SearchResultReference reference, boolean evaluateAci); /** * Sends the search result done message to the client. Note that this method * should only be called from external classes in special cases (e.g., * persistent search) where they are sure that the result won't be sent by the * core server. Also note that the result code and optionally the error * message should have been set for this operation before this method is * called. */ public abstract void sendSearchResultDone(); /** * Set the time after which the search time limit has expired. * * @param timeLimitExpiration - Time after which the search has expired */ public abstract void setTimeLimitExpiration(long timeLimitExpiration); /** * Indicates whether LDAP subentries should be returned or not. * * @return true if the LDAP subentries should be returned, false otherwise */ public abstract boolean isReturnSubentriesOnly(); /** * Set the flag indicating wether the LDAP subentries should be returned. * * @param returnLDAPSubentries - Boolean indicating wether the LDAP * subentries should be returned or not */ public abstract void setReturnSubentriesOnly(boolean returnLDAPSubentries); /** * The matched values control associated with this search operation. * * @return the match values control */ public abstract MatchedValuesControl getMatchedValuesControl(); /** * Set the match values control. * * @param controls - The matched values control */ public abstract void setMatchedValuesControl(MatchedValuesControl controls); /** * Indicates whether to include the account usable response control with * search result entries or not. * * @return true if the usable control has to be part of the search result * entry */ public abstract boolean isIncludeUsableControl(); /** * Specify whether to include the account usable response control within the * search result entries. * * @param includeUsableControl - True if the account usable response control * has to be included within the search result * entries, false otherwise */ public abstract void setIncludeUsableControl(boolean includeUsableControl); /** * Indicates whether the client is able to handle referrals. * * @return true, if the client is able to handle referrals */ public abstract boolean isClientAcceptsReferrals(); /** * Specify whether the client is able to handle referrals. * * @param clientAcceptReferrals - Boolean set to true if the client * can handle referrals */ public abstract void setClientAcceptsReferrals(boolean clientAcceptReferrals); /** * Increments by 1 the number of entries sent to the client for this search * operation. */ public abstract void incrementEntriesSent(); /** * Increments by 1 the number of search references sent to the client for this * search operation. */ public abstract void incrementReferencesSent(); /** * Indicates wether the search result done message has to be sent * to the client, or not. * * @return true if the search result done message is to be sent to the client */ public abstract boolean isSendResponse(); /** * Specify wether the search result done message has to be sent * to the client, or not. * * @param sendResponse - boolean indicating wether the search result done * message is to send to the client */ public abstract void setSendResponse(boolean sendResponse); /** * Returns true if only real attributes should be returned. * * @return true if only real attributes should be returned, false otherwise */ public abstract boolean isRealAttributesOnly(); /** * Specify wether to only return real attributes. * * @param realAttributesOnly - boolean setup to true, if only the real * attributes should be returned */ public abstract void setRealAttributesOnly(boolean realAttributesOnly); /** * Returns true if only virtual attributes should be returned. * * @return true if only virtual attributes should be returned, false * otherwise */ public abstract boolean isVirtualAttributesOnly(); /** * Specify wether to only return virtual attributes. * * @param virtualAttributesOnly - boolean setup to true, if only the virtual * attributes should be returned */ public abstract void setVirtualAttributesOnly(boolean virtualAttributesOnly); /** * Sends the provided search result entry to the client. * * @param entry The search result entry to be sent to * the client. * * @throws DirectoryException If a problem occurs while attempting * to send the entry to the client and * the search should be terminated. */ public abstract void sendSearchEntry(SearchResultEntry entry) throws DirectoryException; /** * Sends the provided search result reference to the client. * * @param reference The search result reference to be sent * to the client. * * @return true if the client is able to accept * referrals, or false if the client cannot * handle referrals and no more attempts should be made to * send them for the associated search operation. * * @throws DirectoryException If a problem occurs while attempting * to send the reference to the client * and the search should be terminated. */ public abstract boolean sendSearchReference(SearchResultReference reference) throws DirectoryException; /** * Retrieves the proxied authorization DN for this operation if proxied * authorization has been requested. * * @return The proxied authorization DN for this operation if proxied * authorization has been requested, or {@code null} if proxied * authorization has not been requested. */ public abstract DN getProxiedAuthorizationDN(); /** * Set the proxied authorization DN for this operation if proxied * authorization has been requested. * * @param proxiedAuthorizationDN * The proxied authorization DN for this operation if proxied * authorization has been requested, or {@code null} if proxied * authorization has not been requested. */ public abstract void setProxiedAuthorizationDN(DN proxiedAuthorizationDN); /** * Retrieves the external changelog request control. * * @return the external changelog request control, or {@code null} * if the control has not been requested. */ public abstract ExternalChangelogRequestControl getECLRequestControl(); /** * Sets the external changelog request control. *

* It should be set only when searching the external changelog. * * @param control * The external changelog request control. */ public abstract void setECLRequestControl(ExternalChangelogRequestControl control); }