001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *  
010 *    https://www.apache.org/licenses/LICENSE-2.0
011 *  
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License. 
018 *  
019 */
020package org.apache.directory.api.ldap.model.message;
021
022
023import java.util.List;
024
025import org.apache.directory.api.ldap.model.exception.LdapException;
026import org.apache.directory.api.ldap.model.filter.ExprNode;
027import org.apache.directory.api.ldap.model.name.Dn;
028import org.apache.directory.api.ldap.model.schema.SchemaManager;
029
030
031/**
032 * Search request protocol message interface.
033 * 
034 * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
035 */
036public interface SearchRequest extends ManyReplyRequest, AbandonableRequest
037{
038    /**
039     * Different response types that a search request may return. A search
040     * request unlike any other request type can generate four different kinds
041     * of responses. It is at most required to return a done response when it is
042     * complete however before then it can return search entry, search
043     * reference, and extended responses to the client.
044     * 
045     * @see #getResponseTypes()
046     */
047    MessageTypeEnum[] RESPONSE_TYPES =
048        {
049            MessageTypeEnum.SEARCH_RESULT_DONE,
050            MessageTypeEnum.SEARCH_RESULT_ENTRY,
051            MessageTypeEnum.SEARCH_RESULT_REFERENCE,
052            MessageTypeEnum.EXTENDED_RESPONSE
053    };
054
055
056    /**
057     * Gets the different response types generated by a search request.
058     * 
059     * @return the RESPONSE_TYPES array
060     * @see #RESPONSE_TYPES
061     */
062    @Override
063    MessageTypeEnum[] getResponseTypes();
064
065
066    /**
067     * Gets the search base as a distinguished name.
068     * 
069     * @return the search base
070     */
071    Dn getBase();
072
073
074    /**
075     * Sets the search base as a distinguished name.
076     * 
077     * @param baseDn the search base
078     * @return The SearchRequest instance
079     */
080    SearchRequest setBase( Dn baseDn );
081
082
083    /**
084     * Gets the search scope parameter enumeration.
085     * 
086     * @return the scope enumeration parameter.
087     */
088    SearchScope getScope();
089
090
091    /**
092     * Sets the search scope parameter enumeration.
093     * 
094     * @param scope the scope enumeration parameter.
095     * @return The SearchRequest instance
096     */
097    SearchRequest setScope( SearchScope scope );
098
099
100    /**
101     * Gets the alias handling parameter.
102     * 
103     * @return the alias handling parameter enumeration.
104     */
105    AliasDerefMode getDerefAliases();
106
107
108    /**
109     * Sets the alias handling parameter.
110     * 
111     * @param aliasDerefAliases the alias handling parameter enumeration.
112     * @return The SearchRequest instance
113     */
114    SearchRequest setDerefAliases( AliasDerefMode aliasDerefAliases );
115
116
117    /**
118     * A sizelimit that restricts the maximum number of entries to be returned
119     * as a result of the search. A value of 0 in this field indicates that no
120     * client-requested sizelimit restrictions are in effect for the search.
121     * Servers may enforce a maximum number of entries to return.
122     * 
123     * @return search size limit.
124     */
125    long getSizeLimit();
126
127
128    /**
129     * Sets sizelimit that restricts the maximum number of entries to be
130     * returned as a result of the search. A value of 0 in this field indicates
131     * that no client-requested sizelimit restrictions are in effect for the
132     * search. Servers may enforce a maximum number of entries to return.
133     * 
134     * @param entriesMax maximum search result entries to return.
135     * @return The SearchRequest instance
136     */
137    SearchRequest setSizeLimit( long entriesMax );
138
139
140    /**
141     * Gets the timelimit that restricts the maximum time (in seconds) allowed
142     * for a search. A value of 0 in this field indicates that no client-
143     * requested timelimit restrictions are in effect for the search.
144     * 
145     * @return the search time limit in seconds.
146     */
147    int getTimeLimit();
148
149
150    /**
151     * Sets the timelimit that restricts the maximum time (in seconds) allowed
152     * for a search. A value of 0 in this field indicates that no client-
153     * requested timelimit restrictions are in effect for the search.
154     * 
155     * @param secondsMax the search time limit in seconds.
156     * @return The SearchRequest instance
157     */
158    SearchRequest setTimeLimit( int secondsMax );
159
160
161    /**
162     * An indicator as to whether search results will contain both attribute
163     * types and values, or just attribute types. Setting this field to TRUE
164     * causes only attribute types (no values) to be returned. Setting this
165     * field to FALSE causes both attribute types and values to be returned.
166     * 
167     * @return true for only types, false for types and values.
168     */
169    boolean getTypesOnly();
170
171
172    /**
173     * An indicator as to whether search results will contain both attribute
174     * types and values, or just attribute types. Setting this field to TRUE
175     * causes only attribute types (no values) to be returned. Setting this
176     * field to FALSE causes both attribute types and values to be returned.
177     * 
178     * @param typesOnly true for only types, false for types and values.
179     * @return The SearchRequest instance
180     */
181    SearchRequest setTypesOnly( boolean typesOnly );
182
183
184    /**
185     * Gets the search filter associated with this search request.
186     * 
187     * @return the expression node for the root of the filter expression tree.
188     */
189    ExprNode getFilter();
190
191
192    /**
193     * Sets the search filter associated with this search request.
194     * 
195     * @param filter the expression node for the root of the filter expression tree.
196     * @return The SearchRequest instance
197     */
198    SearchRequest setFilter( ExprNode filter );
199
200
201    /**
202     * Sets the search filter associated with this search request.
203     * 
204     * @param filter the expression node for the root of the filter expression tree.
205     * @return The SearchRequest instance
206     * @throws LdapException If the filter can't be added
207     */
208    SearchRequest setFilter( String filter ) throws LdapException;
209
210
211    /**
212     * Sets the search filter associated with this search request.
213     * 
214     * @param schemaManager the SchemaManager instance
215     * @param filter the expression node for the root of the filter expression tree.
216     * @return The SearchRequest instance
217     * @throws LdapException If the filter can't be added
218     */
219    SearchRequest setFilter( SchemaManager schemaManager, String filter ) throws LdapException;
220
221
222    /**
223     * Gets a list of the attributes to be returned from each entry which
224     * matches the search filter. There are two special values which may be
225     * used: an empty list with no attributes, and the attribute description
226     * string "*". Both of these signify that all user attributes are to be
227     * returned. (The "*" allows the client to request all user attributes in
228     * addition to specific operational attributes). Attributes MUST be named at
229     * most once in the list, and are returned at most once in an entry. If
230     * there are attribute descriptions in the list which are not recognized,
231     * they are ignored by the server. If the client does not want any
232     * attributes returned, it can specify a list containing only the attribute
233     * with OID "1.1". This OID was chosen arbitrarily and does not correspond
234     * to any attribute in use. Client implementors should note that even if all
235     * user attributes are requested, some attributes of the entry may not be
236     * included in search results due to access control or other restrictions.
237     * Furthermore, servers will not return operational attributes, such as
238     * objectClasses or attributeTypes, unless they are listed by name, since
239     * there may be extremely large number of values for certain operational
240     * attributes.
241     * 
242     * @return the attributes to return for this request
243     */
244    List<String> getAttributes();
245
246
247    /**
248     * Adds some attributes to the set of entry attributes to return.
249     * 
250     * @param attributes the attributes description or identifier.
251     * @return The SearchRequest instance
252     */
253    SearchRequest addAttributes( String... attributes );
254
255
256    /**
257     * Removes an attribute to the set of entry attributes to return.
258     * 
259     * @param attribute the attribute description or identifier.
260     * @return The SearchRequest instance
261     */
262    SearchRequest removeAttribute( String attribute );
263
264
265    /**
266     * {@inheritDoc}
267     */
268    @Override
269    SearchRequest setMessageId( int messageId );
270
271
272    /**
273     * {@inheritDoc}
274     */
275    @Override
276    SearchRequest addControl( Control control );
277
278
279    /**
280     * {@inheritDoc}
281     */
282    @Override
283    SearchRequest addAllControls( Control[] controls );
284
285
286    /**
287     * {@inheritDoc}
288     */
289    @Override
290    SearchRequest removeControl( Control control );
291    
292    
293    /**
294     * Tells the client if it should follow referrals instead of throwing exceptions
295     * @return true if we should follow the referrals
296     */
297    boolean isFollowReferrals();
298    
299    
300    /**
301     * Tells the client to follow referrals instead of throwing exceptions
302     * @return The SearchRequest instance
303     */
304    SearchRequest followReferrals();
305    
306    
307    /**
308     * Tells the client if it should ignore referrals instead of throwing exceptions
309     * @return true if we should ignore the referrals
310     */
311    boolean isIgnoreReferrals();
312    
313    
314    /**
315     * Tells the client to ignore referrals instead of throwing exceptions. The entry
316     * will contain the referral attributeType with the link.
317     * 
318     * @return The SearchRequest instance
319     */
320    SearchRequest ignoreReferrals();
321}