| | |
| | | * (the "License"). You may not use this file except in compliance |
| | | * with the License. |
| | | * |
| | | * You can obtain a copy of the license at |
| | | * trunk/opendj3/legal-notices/CDDLv1_0.txt |
| | | * 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 |
| | | * trunk/opendj3/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: |
| | | * 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 |
| | |
| | | |
| | | package org.forgerock.opendj.ldap.requests; |
| | | |
| | | |
| | | |
| | | import java.util.List; |
| | | |
| | | import org.forgerock.i18n.*; |
| | | import org.forgerock.opendj.ldap.*; |
| | | import org.forgerock.i18n.LocalizedIllegalArgumentException; |
| | | import org.forgerock.opendj.ldap.DN; |
| | | import org.forgerock.opendj.ldap.DecodeException; |
| | | import org.forgerock.opendj.ldap.DecodeOptions; |
| | | import org.forgerock.opendj.ldap.DereferenceAliasesPolicy; |
| | | import org.forgerock.opendj.ldap.Filter; |
| | | import org.forgerock.opendj.ldap.SearchScope; |
| | | import org.forgerock.opendj.ldap.controls.Control; |
| | | import org.forgerock.opendj.ldap.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 |
| | |
| | | * entries immediately subordinate to a particular entry, or from a whole |
| | | * subtree of entries. |
| | | */ |
| | | public interface SearchRequest extends Request |
| | | { |
| | | /** |
| | | * Adds the provided attribute name(s) 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 name(s) 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. |
| | | * @throws NullPointerException |
| | | * If {@code attributeDescriptions} was {@code null}. |
| | | */ |
| | | SearchRequest addAttribute(String... attributeDescriptions); |
| | | public interface SearchRequest extends Request { |
| | | /** |
| | | * Adds the provided attribute name(s) 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 name(s) 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. |
| | | * @throws NullPointerException |
| | | * If {@code attributeDescriptions} was {@code null}. |
| | | */ |
| | | SearchRequest addAttribute(String... attributeDescriptions); |
| | | |
| | | /** |
| | | * {@inheritDoc} |
| | | */ |
| | | SearchRequest addControl(Control control); |
| | | |
| | | /** |
| | | * 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. |
| | | */ |
| | | List<String> getAttributes(); |
| | | |
| | | /** |
| | | * {@inheritDoc} |
| | | */ |
| | | SearchRequest addControl(Control control); |
| | | /** |
| | | * {@inheritDoc} |
| | | */ |
| | | <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) |
| | | throws DecodeException; |
| | | |
| | | /** |
| | | * {@inheritDoc} |
| | | */ |
| | | 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(); |
| | | |
| | | /** |
| | | * 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. |
| | | */ |
| | | List<String> getAttributes(); |
| | | /** |
| | | * 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(); |
| | | |
| | | /** |
| | | * 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(); |
| | | |
| | | /** |
| | | * Returns the scope of the search. |
| | | * |
| | | * @return The search scope. |
| | | */ |
| | | SearchScope getScope(); |
| | | |
| | | /** |
| | | * {@inheritDoc} |
| | | */ |
| | | <C extends Control> C getControl(ControlDecoder<C> decoder, |
| | | DecodeOptions options) throws DecodeException; |
| | | /** |
| | | * 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. |
| | | */ |
| | | int getSizeLimit(); |
| | | |
| | | /** |
| | | * 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. |
| | | */ |
| | | int getTimeLimit(); |
| | | |
| | | /** |
| | | * 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(); |
| | | |
| | | /** |
| | | * {@inheritDoc} |
| | | */ |
| | | List<Control> getControls(); |
| | | /** |
| | | * Sets the alias dereferencing policy to be used during the search. |
| | | * |
| | | * @param policy |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code policy} was {@code null}. |
| | | */ |
| | | SearchRequest setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy); |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * If this search request does not permit the filter to be set. |
| | | * @throws NullPointerException |
| | | * If {@code filter} was {@code null}. |
| | | */ |
| | | SearchRequest setFilter(Filter filter); |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code filter} was {@code null}. |
| | | */ |
| | | SearchRequest setFilter(String filter); |
| | | |
| | | /** |
| | | * Returns an indication as to whether or not alias entries are to be |
| | | * dereferenced during the search. |
| | | * |
| | | * @return The alias dereferencing policy. |
| | | */ |
| | | DereferenceAliasesPolicy getDereferenceAliasesPolicy(); |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * If this search request does not permit the distinguished name |
| | | * to be set. |
| | | * @throws NullPointerException |
| | | * If {@code dn} was {@code null}. |
| | | */ |
| | | SearchRequest setName(DN dn); |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws LocalizedIllegalArgumentException |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code dn} was {@code null}. |
| | | */ |
| | | SearchRequest setName(String dn); |
| | | |
| | | /** |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code scope} was {@code null}. |
| | | */ |
| | | SearchRequest setScope(SearchScope scope); |
| | | |
| | | /** |
| | | * 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(); |
| | | /** |
| | | * 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. |
| | | * |
| | | * @param limit |
| | | * 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. |
| | | * @throws LocalizedIllegalArgumentException |
| | | * If {@code limit} was negative. |
| | | */ |
| | | SearchRequest setSizeLimit(int limit); |
| | | |
| | | /** |
| | | * 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. |
| | | * |
| | | * @param limit |
| | | * 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. |
| | | * @throws LocalizedIllegalArgumentException |
| | | * If {@code limit} was negative. |
| | | */ |
| | | SearchRequest setTimeLimit(int limit); |
| | | |
| | | |
| | | /** |
| | | * 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(); |
| | | |
| | | |
| | | |
| | | /** |
| | | * Returns the scope of the search. |
| | | * |
| | | * @return The search scope. |
| | | */ |
| | | SearchScope getScope(); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | */ |
| | | int getSizeLimit(); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | */ |
| | | int getTimeLimit(); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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(); |
| | | |
| | | |
| | | |
| | | /** |
| | | * Sets the alias dereferencing policy to be used during the search. |
| | | * |
| | | * @param policy |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code policy} was {@code null}. |
| | | */ |
| | | SearchRequest setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * If this search request does not permit the filter to be set. |
| | | * @throws NullPointerException |
| | | * If {@code filter} was {@code null}. |
| | | */ |
| | | SearchRequest setFilter(Filter filter); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code filter} was {@code null}. |
| | | */ |
| | | SearchRequest setFilter(String filter); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * If this search request does not permit the distinguished name to |
| | | * be set. |
| | | * @throws NullPointerException |
| | | * If {@code dn} was {@code null}. |
| | | */ |
| | | SearchRequest setName(DN dn); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws LocalizedIllegalArgumentException |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code dn} was {@code null}. |
| | | */ |
| | | SearchRequest setName(String dn); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * @throws NullPointerException |
| | | * If {@code scope} was {@code null}. |
| | | */ |
| | | SearchRequest setScope(SearchScope scope); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * |
| | | * @param limit |
| | | * 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. |
| | | * @throws LocalizedIllegalArgumentException |
| | | * If {@code limit} was negative. |
| | | */ |
| | | SearchRequest setSizeLimit(int limit); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * |
| | | * @param limit |
| | | * 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. |
| | | * @throws LocalizedIllegalArgumentException |
| | | * If {@code limit} was negative. |
| | | */ |
| | | SearchRequest setTimeLimit(int limit); |
| | | |
| | | |
| | | |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * If this search request does not permit the types-only parameter |
| | | * to be set. |
| | | */ |
| | | SearchRequest setTypesOnly(boolean typesOnly); |
| | | /** |
| | | * 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. |
| | | * @return This search request. |
| | | * @throws UnsupportedOperationException |
| | | * If this search request does not permit the types-only |
| | | * parameter to be set. |
| | | */ |
| | | SearchRequest setTypesOnly(boolean typesOnly); |
| | | |
| | | } |