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