mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
sdk/src/org/opends/sdk/requests/SearchRequest.java
@@ -29,57 +29,34 @@ import java.util.Collection; import java.util.List; import org.opends.sdk.*; import org.opends.sdk.controls.Control; import org.opends.sdk.controls.ControlDecoder; /** * The Search operation is used to request a server to return, subject * to access controls and other restrictions, a set of entries matching * a complex search criterion. This can be used to read attributes from * a single entry, from entries immediately subordinate to a particular * entry, or from a whole subtree of entries. * The Search operation is used to request a server to return, subject to access * controls and other restrictions, a set of entries matching a complex search * criterion. This can be used to read attributes from a single entry, from * entries immediately subordinate to a particular entry, or from a whole * subtree of entries. */ public interface SearchRequest extends Request { /** * Adds the provided attribute names to the list of attributes to be * included with each entry that matches the search criteria. * Attributes that are sub-types of listed attributes are implicitly * included. * * @param attributeDescriptions * The names of the attributes to be included with each * entry. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit attribute names to * be added. * @throws NullPointerException * If {@code attributeDescriptions} was {@code null}, or if * it contained a {@code null} element. */ SearchRequest addAttribute(Collection<String> attributeDescriptions) throws UnsupportedOperationException, NullPointerException; /** * Adds the provided attribute name to the list of attributes to be * included with each entry that matches the search criteria. * Attributes that are sub-types of listed attributes are implicitly * included. * * Adds the provided attribute name to the list of attributes to be included * with each entry that matches the search criteria. Attributes that are * sub-types of listed attributes are implicitly included. * * @param attributeDescription * The name of the attribute to be included with each entry. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit attribute names to * be added. * If this search request does not permit attribute names to be * added. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ @@ -89,37 +66,7 @@ /** * Adds the provided attribute names to the list of attributes to be * included with each entry that matches the search criteria. * Attributes that are sub-types of listed attributes are implicitly * included. * * @param attributeDescriptions * The names of the attributes to be included with each * entry. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit attribute names to * be added. * @throws NullPointerException * If {@code attributeDescriptions} was {@code null}, or if * it contained a {@code null} element. */ SearchRequest addAttribute(String... attributeDescriptions) throws UnsupportedOperationException, NullPointerException; /** * Adds the provided control to this request. * * @param control * The control to be added to this request. * @return This request. * @throws UnsupportedOperationException * If this request does not permit controls to be added. * @throws NullPointerException * If {@code control} was {@code null}. * {@inheritDoc} */ SearchRequest addControl(Control control) throws UnsupportedOperationException, NullPointerException; @@ -127,73 +74,36 @@ /** * Clears the list of attributes to be included with each entry that * matches the search criteria. Attributes that are sub-types of * listed attributes are implicitly included. * * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit attributes to be * removed. * Returns a {@code List} containing the list of attributes to be included * with each entry that matches the search criteria. Attributes that are * sub-types of listed attributes are implicitly included. The returned * {@code List} may be modified if permitted by this search request. * * @return A {@code List} containing the list of attributes. */ SearchRequest clearAttributes() throws UnsupportedOperationException; List<String> getAttributes(); /** * Removes all the controls included with this request. * * @return This request. * @throws UnsupportedOperationException * If this request does not permit controls to be removed. * {@inheritDoc} */ SearchRequest clearControls() throws UnsupportedOperationException; <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) throws NullPointerException, DecodeException; /** * Returns an {@code Iterable} containing the list of attributes to be * included with each entry that matches the search criteria. * Attributes that are sub-types of listed attributes are implicitly * included. The returned {@code Iterable} may be used to remove * attribute names if permitted by this search request. * * @return An {@code Iterable} containing the list of attributes. * {@inheritDoc} */ Iterable<String> getAttributes(); /** * Returns the first control contained in this request having the * specified OID. * * @param oid * The OID of the control to be returned. * @return The control, or {@code null} if the control is not included * with this request. * @throws NullPointerException * If {@code oid} was {@code null}. */ Control getControl(String oid) throws NullPointerException; /** * Returns an {@code Iterable} containing the controls included with * this request. The returned {@code Iterable} may be used to remove * controls if permitted by this request. * * @return An {@code Iterable} containing the controls. */ Iterable<Control> getControls(); List<Control> getControls(); /** * Returns an indication as to whether or not alias entries are to be * dereferenced during the search. * * * @return The alias dereferencing policy. */ DereferenceAliasesPolicy getDereferenceAliasesPolicy(); @@ -201,9 +111,9 @@ /** * Returns the filter that defines the conditions that must be * fulfilled in order for an entry to be returned. * * Returns the filter that defines the conditions that must be fulfilled in * order for an entry to be returned. * * @return The search filter. */ Filter getFilter(); @@ -211,9 +121,9 @@ /** * Returns the distinguished name of the base entry relative to which * the search is to be performed. * * Returns the distinguished name of the base entry relative to which the * search is to be performed. * * @return The distinguished name of the base entry. */ DN getName(); @@ -222,7 +132,7 @@ /** * Returns the scope of the search. * * * @return The search scope. */ SearchScope getScope(); @@ -230,183 +140,114 @@ /** * Returns the size limit that should be used in order to restrict the * maximum number of entries returned by the search. * Returns the size limit that should be used in order to restrict the maximum * number of entries returned by the search. * <p> * A value of zero (the default) in this field indicates that no * client-requested size limit restrictions are in effect. Servers may * also enforce a maximum number of entries to return. * * @return The size limit that should be used in order to restrict the * maximum number of entries returned by the search. * client-requested size limit restrictions are in effect. Servers may also * enforce a maximum number of entries to return. * * @return The size limit that should be used in order to restrict the maximum * number of entries returned by the search. */ int getSizeLimit(); /** * Returns the time limit that should be used in order to restrict the * maximum time (in seconds) allowed for the search. * Returns the time limit that should be used in order to restrict the maximum * time (in seconds) allowed for the search. * <p> * A value of zero (the default) in this field indicates that no * client-requested time limit restrictions are in effect for the * search. Servers may also enforce a maximum time limit for the * search. * * @return The time limit that should be used in order to restrict the * maximum time (in seconds) allowed for the search. * client-requested time limit restrictions are in effect for the search. * Servers may also enforce a maximum time limit for the search. * * @return The time limit that should be used in order to restrict the maximum * time (in seconds) allowed for the search. */ int getTimeLimit(); /** * Indicates whether or not this search request has a list of * attributes to be included with each entry that matches the search * criteria. * * @return {@code true} if this search request has a list of * attributes to be included with each entry, otherwise * {@code false}. */ boolean hasAttributes(); /** * Indicates whether or not this request has any controls. * * @return {@code true} if this request has any controls, otherwise * {@code false}. */ boolean hasControls(); /** * Indicates whether search results are to contain both attribute * descriptions and values, or just attribute descriptions. * * @return {@code true} if only attribute descriptions (and not * values) are to be returned, or {@code false} (the default) * if both attribute descriptions and values are to be * returned. * Indicates whether search results are to contain both attribute descriptions * and values, or just attribute descriptions. * * @return {@code true} if only attribute descriptions (and not values) are to * be returned, or {@code false} (the default) if both attribute * descriptions and values are to be returned. */ boolean isTypesOnly(); /** * Removes the provided attribute name from the list of attributes to * be included with each entry that matches the search criteria. * Attributes that are sub-types of listed attributes are implicitly * included. * * @param attributeDescription * The name of the attribute to be removed. * @return {@code true} if the attribute name was found in the list of * attributes. * @throws UnsupportedOperationException * If this search request does not permit attribute names to * be removed. * @throws NullPointerException * If {@code attributeDescription} was {@code null}. */ boolean removeAttribute(String attributeDescription) throws UnsupportedOperationException, NullPointerException; /** * Removes the first control contained in this request having the * specified OID. * * @param oid * The OID of the control to be removed. * @return The removed control, or {@code null} if the control is not * included with this request. * @throws UnsupportedOperationException * If this request does not permit controls to be removed. * @throws NullPointerException * If {@code oid} was {@code null}. */ Control removeControl(String oid) throws UnsupportedOperationException, NullPointerException; /** * Sets the alias dereferencing policy to be used during the search. * * * @param policy * The alias dereferencing policy to be used during the * search. * The alias dereferencing policy to be used during the search. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the alias * dereferencing policy to be set. * If this search request does not permit the alias dereferencing * policy to be set. * @throws NullPointerException * If {@code policy} was {@code null}. */ SearchRequest setDereferenceAliasesPolicy( DereferenceAliasesPolicy policy) SearchRequest setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy) throws UnsupportedOperationException, NullPointerException; /** * Sets the filter that defines the conditions that must be fulfilled * in order for an entry to be returned. * * Sets the filter that defines the conditions that must be fulfilled in order * for an entry to be returned. * * @param filter * The filter that defines the conditions that must be * fulfilled in order for an entry to be returned. * The filter that defines the conditions that must be fulfilled in * order for an entry to be returned. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the filter to be * set. * If this search request does not permit the filter to be set. * @throws NullPointerException * If {@code filter} was {@code null}. */ SearchRequest setFilter(Filter filter) throws UnsupportedOperationException, NullPointerException; SearchRequest setFilter(Filter filter) throws UnsupportedOperationException, NullPointerException; /** * Sets the filter that defines the conditions that must be fulfilled * in order for an entry to be returned. * * Sets the filter that defines the conditions that must be fulfilled in order * for an entry to be returned. * * @param filter * The filter that defines the conditions that must be * fulfilled in order for an entry to be returned. * The filter that defines the conditions that must be fulfilled in * order for an entry to be returned. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the filter to be * set. * If this search request does not permit the filter to be set. * @throws LocalizedIllegalArgumentException * If {@code filter} is not a valid LDAP string * representation of a filter. * If {@code filter} is not a valid LDAP string representation of a * filter. * @throws NullPointerException * If {@code filter} was {@code null}. */ SearchRequest setFilter(String filter) throws UnsupportedOperationException, SearchRequest setFilter(String filter) throws UnsupportedOperationException, LocalizedIllegalArgumentException, NullPointerException; /** * Sets the distinguished name of the base entry relative to which the * search is to be performed. * * Sets the distinguished name of the base entry relative to which the search * is to be performed. * * @param dn * The distinguished name of the base entry relative to which * the search is to be performed. * The distinguished name of the base entry relative to which the * search is to be performed. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the distinguished * name to be set. * If this search request does not permit the distinguished name to * be set. * @throws NullPointerException * If {@code dn} was {@code null}. */ @@ -416,37 +257,34 @@ /** * Sets the distinguished name of the base entry relative to which the * search is to be performed. * * Sets the distinguished name of the base entry relative to which the search * is to be performed. * * @param dn * The distinguished name of the base entry relative to which * the search is to be performed. * The distinguished name of the base entry relative to which the * search is to be performed. * @return This search request. * @throws LocalizedIllegalArgumentException * If {@code dn} could not be decoded using the default * schema. * If {@code dn} could not be decoded using the default schema. * @throws UnsupportedOperationException * If this search request does not permit the distinguished * name to be set. * If this search request does not permit the distinguished name to * be set. * @throws NullPointerException * If {@code dn} was {@code null}. */ SearchRequest setName(String dn) throws LocalizedIllegalArgumentException, SearchRequest setName(String dn) throws LocalizedIllegalArgumentException, UnsupportedOperationException, NullPointerException; /** * Sets the scope of the search. * * * @param scope * The scope of the search. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the scope to be * set. * If this search request does not permit the scope to be set. * @throws NullPointerException * If {@code scope} was {@code null}. */ @@ -456,67 +294,61 @@ /** * Sets the size limit that should be used in order to restrict the * maximum number of entries returned by the search. * Sets the size limit that should be used in order to restrict the maximum * number of entries returned by the search. * <p> * A value of zero (the default) in this field indicates that no * client-requested size limit restrictions are in effect. Servers may * also enforce a maximum number of entries to return. * * client-requested size limit restrictions are in effect. Servers may also * enforce a maximum number of entries to return. * * @param limit * The size limit that should be used in order to restrict * the maximum number of entries returned by the search. * The size limit that should be used in order to restrict the * maximum number of entries returned by the search. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the size limit to * be set. * If this search request does not permit the size limit to be set. * @throws LocalizedIllegalArgumentException * If {@code limit} was negative. */ SearchRequest setSizeLimit(int limit) throws UnsupportedOperationException, SearchRequest setSizeLimit(int limit) throws UnsupportedOperationException, LocalizedIllegalArgumentException; /** * Sets the time limit that should be used in order to restrict the * maximum time (in seconds) allowed for the search. * Sets the time limit that should be used in order to restrict the maximum * time (in seconds) allowed for the search. * <p> * A value of zero (the default) in this field indicates that no * client-requested time limit restrictions are in effect for the * search. Servers may also enforce a maximum time limit for the * search. * * client-requested time limit restrictions are in effect for the search. * Servers may also enforce a maximum time limit for the search. * * @param limit * The time limit that should be used in order to restrict * the maximum time (in seconds) allowed for the search. * The time limit that should be used in order to restrict the * maximum time (in seconds) allowed for the search. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the time limit to * be set. * If this search request does not permit the time limit to be set. * @throws LocalizedIllegalArgumentException * If {@code limit} was negative. */ SearchRequest setTimeLimit(int limit) throws UnsupportedOperationException, SearchRequest setTimeLimit(int limit) throws UnsupportedOperationException, LocalizedIllegalArgumentException; /** * Specifies whether search results are to contain both attribute * descriptions and values, or just attribute descriptions. * * Specifies whether search results are to contain both attribute descriptions * and values, or just attribute descriptions. * * @param typesOnly * {@code true} if only attribute descriptions (and not * values) are to be returned, or {@code false} (the default) * if both attribute descriptions and values are to be * returned. * {@code true} if only attribute descriptions (and not values) are * to be returned, or {@code false} (the default) if both attribute * descriptions and values are to be returned. * @return This search request. * @throws UnsupportedOperationException * If this search request does not permit the types-only * parameter to be set. * If this search request does not permit the types-only parameter * to be set. */ SearchRequest setTypesOnly(boolean typesOnly) throws UnsupportedOperationException;
