mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git

Matthew Swift
25.33.2012 263d085885df024dca9250cc03c807912b0a7662
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/requests/SearchRequest.java
@@ -6,17 +6,16 @@
 * (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
@@ -28,17 +27,18 @@
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
@@ -46,302 +46,263 @@
 * 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);
}