/* * 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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE * or https://OpenDS.dev.java.net/OpenDS.LICENSE. * 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/opends/resource/legal-notices/OpenDS.LICENSE. 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 2009-2010 Sun Microsystems, Inc. */ package org.opends.sdk.requests; 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. */ 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) throws UnsupportedOperationException, NullPointerException; /** * {@inheritDoc} */ SearchRequest addControl(Control control) throws UnsupportedOperationException, NullPointerException; /** * 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 getAttributes(); /** * {@inheritDoc} */ C getControl(ControlDecoder decoder, DecodeOptions options) throws NullPointerException, DecodeException; /** * {@inheritDoc} */ List 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 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(); /** * Returns the size limit that should be used in order to restrict the maximum * number of entries returned by the search. *

* 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. *

* 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) throws UnsupportedOperationException, NullPointerException; /** * 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) throws UnsupportedOperationException, NullPointerException; /** * 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) throws UnsupportedOperationException, LocalizedIllegalArgumentException, NullPointerException; /** * 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) throws UnsupportedOperationException, NullPointerException; /** * 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) 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. * @throws NullPointerException * If {@code scope} was {@code null}. */ SearchRequest setScope(SearchScope scope) throws UnsupportedOperationException, NullPointerException; /** * Sets the size limit that should be used in order to restrict the maximum * number of entries returned by the search. *

* 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) throws UnsupportedOperationException, LocalizedIllegalArgumentException; /** * Sets the time limit that should be used in order to restrict the maximum * time (in seconds) allowed for the search. *

* 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) throws UnsupportedOperationException, LocalizedIllegalArgumentException; /** * 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) throws UnsupportedOperationException; }