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