001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2009-2010 Sun Microsystems, Inc.
015 * Portions copyright 2012-2016 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.i18n.LocalizedIllegalArgumentException;
023import org.forgerock.opendj.ldap.DN;
024import org.forgerock.opendj.ldap.DecodeException;
025import org.forgerock.opendj.ldap.DecodeOptions;
026import org.forgerock.opendj.ldap.DereferenceAliasesPolicy;
027import org.forgerock.opendj.ldap.Filter;
028import org.forgerock.opendj.ldap.SearchScope;
029import org.forgerock.opendj.ldap.controls.Control;
030import org.forgerock.opendj.ldap.controls.ControlDecoder;
031
032/**
033 * The Search operation is used to request a server to return, subject to access
034 * controls and other restrictions, a set of entries matching a complex search
035 * criterion. This can be used to read attributes from a single entry, from
036 * entries immediately subordinate to a particular entry, or from a whole
037 * subtree of entries.
038 * <p>
039 * Use {@link Requests#newSearchRequest(DN, SearchScope, Filter, String...)} or
040 * {@link Requests#newSearchRequest(String, SearchScope, String, String...)} to
041 * create a new search request.
042 *
043 * <pre>
044 * SearchRequest request = Requests.newSearchRequest(&quot;dc=example,dc=com&quot;, SearchScope.WHOLE_SUBTREE,
045 *         &quot;(sn=Jensen)&quot;, &quot;cn&quot;);
046 * </pre>
047 *
048 * Alternatively, use the
049 * {@link org.forgerock.opendj.ldap.Connection#search(String, SearchScope, String, String...)
050 * Connection.search()} method to specify the arguments directly.
051 *
052 * <pre>
053 * Connection connection = ...;
054 * ConnectionEntryReader reader = connection.search(
055 *          "dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn");
056 * </pre>
057 */
058public interface SearchRequest extends Request {
059    /**
060     * Adds the provided attribute name(s) to the list of attributes to be
061     * included with each entry that matches the search criteria. Attributes
062     * that are sub-types of listed attributes are implicitly included.
063     *
064     * @param attributeDescriptions
065     *            The name(s) of the attribute to be included with each entry.
066     * @return This search request.
067     * @throws UnsupportedOperationException
068     *             If this search request does not permit attribute names to be
069     *             added.
070     * @throws NullPointerException
071     *             If {@code attributeDescriptions} was {@code null}.
072     */
073    SearchRequest addAttribute(String... attributeDescriptions);
074
075    @Override
076    SearchRequest addControl(Control control);
077
078    /**
079     * Returns a {@code List} containing the list of attributes to be included
080     * with each entry that matches the search criteria. Attributes that are
081     * sub-types of listed attributes are implicitly included. The returned
082     * {@code List} may be modified if permitted by this search request.
083     *
084     * @return A {@code List} containing the list of attributes.
085     */
086    List<String> getAttributes();
087
088    @Override
089    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
090            throws DecodeException;
091
092    @Override
093    List<Control> getControls();
094
095    /**
096     * Returns an indication as to whether alias entries are to be
097     * dereferenced during the search.
098     *
099     * @return The alias dereferencing policy.
100     */
101    DereferenceAliasesPolicy getDereferenceAliasesPolicy();
102
103    /**
104     * Returns the filter that defines the conditions that must be fulfilled in
105     * order for an entry to be returned.
106     *
107     * @return The search filter.
108     */
109    Filter getFilter();
110
111    /**
112     * Returns the distinguished name of the base entry relative to which the
113     * search is to be performed.
114     *
115     * @return The distinguished name of the base entry.
116     */
117    DN getName();
118
119    /**
120     * Returns the scope of the search.
121     *
122     * @return The search scope.
123     */
124    SearchScope getScope();
125
126    /**
127     * Returns the size limit that should be used in order to restrict the
128     * maximum number of entries returned by the search.
129     * <p>
130     * A value of zero (the default) in this field indicates that no
131     * client-requested size limit restrictions are in effect. Servers may also
132     * enforce a maximum number of entries to return.
133     *
134     * @return The size limit that should be used in order to restrict the
135     *         maximum number of entries returned by the search.
136     */
137    int getSizeLimit();
138
139    /**
140     * Indicates whether search result is expected to be limited to a single entry.
141     * <p>
142     * It is the case if size limit is equal to 1 or if scope is equal to <code>SearchScope.BASE_OBJECT</code>.
143     * <p>
144     * If search results contain more than one entry, the search operation will throw
145     * a <code>MultipleEntriesFoundException</code>.
146     *
147     * @return {@code true} if the search is limited to a single entry result,
148     *         or {@code false} (the default) otherwise.
149     */
150    boolean isSingleEntrySearch();
151
152    /**
153     * Returns the time limit that should be used in order to restrict the
154     * maximum time (in seconds) allowed for the search.
155     * <p>
156     * A value of zero (the default) in this field indicates that no
157     * client-requested time limit restrictions are in effect for the search.
158     * Servers may also enforce a maximum time limit for the search.
159     *
160     * @return The time limit that should be used in order to restrict the
161     *         maximum time (in seconds) allowed for the search.
162     */
163    int getTimeLimit();
164
165    /**
166     * Indicates whether search results are to contain both attribute
167     * descriptions and values, or just attribute descriptions.
168     *
169     * @return {@code true} if only attribute descriptions (and not values) are
170     *         to be returned, or {@code false} (the default) if both attribute
171     *         descriptions and values are to be returned.
172     */
173    boolean isTypesOnly();
174
175    /**
176     * Sets the alias dereferencing policy to be used during the search.
177     *
178     * @param policy
179     *            The alias dereferencing policy to be used during the search.
180     * @return This search request.
181     * @throws UnsupportedOperationException
182     *             If this search request does not permit the alias
183     *             dereferencing policy to be set.
184     * @throws NullPointerException
185     *             If {@code policy} was {@code null}.
186     */
187    SearchRequest setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy);
188
189    /**
190     * Sets the filter that defines the conditions that must be fulfilled in
191     * order for an entry to be returned.
192     *
193     * @param filter
194     *            The filter that defines the conditions that must be fulfilled
195     *            in order for an entry to be returned.
196     * @return This search request.
197     * @throws UnsupportedOperationException
198     *             If this search request does not permit the filter to be set.
199     * @throws NullPointerException
200     *             If {@code filter} was {@code null}.
201     */
202    SearchRequest setFilter(Filter filter);
203
204    /**
205     * Sets the filter that defines the conditions that must be fulfilled in
206     * order for an entry to be returned.
207     *
208     * @param filter
209     *            The filter that defines the conditions that must be fulfilled
210     *            in order for an entry to be returned.
211     * @return This search request.
212     * @throws UnsupportedOperationException
213     *             If this search request does not permit the filter to be set.
214     * @throws LocalizedIllegalArgumentException
215     *             If {@code filter} is not a valid LDAP string representation
216     *             of a filter.
217     * @throws NullPointerException
218     *             If {@code filter} was {@code null}.
219     */
220    SearchRequest setFilter(String filter);
221
222    /**
223     * Sets the distinguished name of the base entry relative to which the
224     * search is to be performed.
225     *
226     * @param dn
227     *            The distinguished name of the base entry relative to which the
228     *            search is to be performed.
229     * @return This search request.
230     * @throws UnsupportedOperationException
231     *             If this search request does not permit the distinguished name
232     *             to be set.
233     * @throws NullPointerException
234     *             If {@code dn} was {@code null}.
235     */
236    SearchRequest setName(DN dn);
237
238    /**
239     * Sets the distinguished name of the base entry relative to which the
240     * search is to be performed.
241     *
242     * @param dn
243     *            The distinguished name of the base entry relative to which the
244     *            search is to be performed.
245     * @return This search request.
246     * @throws LocalizedIllegalArgumentException
247     *             If {@code dn} could not be decoded using the default schema.
248     * @throws UnsupportedOperationException
249     *             If this search request does not permit the distinguished name
250     *             to be set.
251     * @throws NullPointerException
252     *             If {@code dn} was {@code null}.
253     */
254    SearchRequest setName(String dn);
255
256    /**
257     * Sets the scope of the search.
258     *
259     * @param scope
260     *            The scope of the search.
261     * @return This search request.
262     * @throws UnsupportedOperationException
263     *             If this search request does not permit the scope to be set.
264     * @throws NullPointerException
265     *             If {@code scope} was {@code null}.
266     */
267    SearchRequest setScope(SearchScope scope);
268
269    /**
270     * Sets the size limit that should be used in order to restrict the maximum
271     * number of entries returned by the search.
272     * <p>
273     * A value of zero (the default) in this field indicates that no
274     * client-requested size limit restrictions are in effect. Servers may also
275     * enforce a maximum number of entries to return.
276     *
277     * @param limit
278     *            The size limit that should be used in order to restrict the
279     *            maximum number of entries returned by the search.
280     * @return This search request.
281     * @throws UnsupportedOperationException
282     *             If this search request does not permit the size limit to be
283     *             set.
284     * @throws LocalizedIllegalArgumentException
285     *             If {@code limit} was negative.
286     */
287    SearchRequest setSizeLimit(int limit);
288
289    /**
290     * Sets the time limit that should be used in order to restrict the maximum
291     * time (in seconds) allowed for the search.
292     * <p>
293     * A value of zero (the default) in this field indicates that no
294     * client-requested time limit restrictions are in effect for the search.
295     * Servers may also enforce a maximum time limit for the search.
296     *
297     * @param limit
298     *            The time limit that should be used in order to restrict the
299     *            maximum time (in seconds) allowed for the search.
300     * @return This search request.
301     * @throws UnsupportedOperationException
302     *             If this search request does not permit the time limit to be
303     *             set.
304     * @throws LocalizedIllegalArgumentException
305     *             If {@code limit} was negative.
306     */
307    SearchRequest setTimeLimit(int limit);
308
309    /**
310     * Specifies whether search results are to contain both attribute
311     * descriptions and values, or just attribute descriptions.
312     *
313     * @param typesOnly
314     *            {@code true} if only attribute descriptions (and not values)
315     *            are to be returned, or {@code false} (the default) if both
316     *            attribute descriptions and values are to be returned.
317     * @return This search request.
318     * @throws UnsupportedOperationException
319     *             If this search request does not permit the types-only
320     *             parameter to be set.
321     */
322    SearchRequest setTypesOnly(boolean typesOnly);
323
324}