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.shared.ldap.model.message;
021
022
023import java.util.List;
024
025import org.apache.directory.shared.ldap.model.exception.LdapException;
026import org.apache.directory.shared.ldap.model.exception.MessageException;
027import org.apache.directory.shared.ldap.model.filter.ExprNode;
028import org.apache.directory.shared.ldap.model.name.Dn;
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<SearchResultDone>, 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        { SearchResultDone.TYPE, SearchResultEntry.TYPE, SearchResultReference.TYPE, ExtendedResponse.TYPE };
049
050
051    /**
052     * Gets the different response types generated by a search request.
053     * 
054     * @return the RESPONSE_TYPES array
055     * @see #RESPONSE_TYPES
056     */
057    MessageTypeEnum[] getResponseTypes();
058
059
060    /**
061     * Gets the search base as a distinguished name.
062     * 
063     * @return the search base
064     */
065    Dn getBase();
066
067
068    /**
069     * Sets the search base as a distinguished name.
070     * 
071     * @param baseDn the search base
072     * @return The SearchRequest instance
073     */
074    SearchRequest setBase( Dn baseDn );
075
076
077    /**
078     * Gets the search scope parameter enumeration.
079     * 
080     * @return the scope enumeration parameter.
081     */
082    SearchScope getScope();
083
084
085    /**
086     * Sets the search scope parameter enumeration.
087     * 
088     * @param scope the scope enumeration parameter.
089     * @return The SearchRequest instance
090     */
091    SearchRequest setScope( SearchScope scope );
092
093
094    /**
095     * Gets the alias handling parameter.
096     * 
097     * @return the alias handling parameter enumeration.
098     */
099    AliasDerefMode getDerefAliases();
100
101
102    /**
103     * Sets the alias handling parameter.
104     * 
105     * @param aliasDerefAliases the alias handling parameter enumeration.
106     * @return The SearchRequest instance
107     */
108    SearchRequest setDerefAliases( AliasDerefMode aliasDerefAliases );
109
110
111    /**
112     * A sizelimit that restricts the maximum number of entries to be returned
113     * as a result of the search. A value of 0 in this field indicates that no
114     * client-requested sizelimit restrictions are in effect for the search.
115     * Servers may enforce a maximum number of entries to return.
116     * 
117     * @return search size limit.
118     */
119    long getSizeLimit();
120
121
122    /**
123     * Sets sizelimit that restricts the maximum number of entries to be
124     * returned as a result of the search. A value of 0 in this field indicates
125     * that no client-requested sizelimit restrictions are in effect for the
126     * search. Servers may enforce a maximum number of entries to return.
127     * 
128     * @param entriesMax maximum search result entries to return.
129     * @return The SearchRequest instance
130     */
131    SearchRequest setSizeLimit( long entriesMax );
132
133
134    /**
135     * Gets the timelimit that restricts the maximum time (in seconds) allowed
136     * for a search. A value of 0 in this field indicates that no client-
137     * requested timelimit restrictions are in effect for the search.
138     * 
139     * @return the search time limit in seconds.
140     */
141    int getTimeLimit();
142
143
144    /**
145     * Sets the timelimit that restricts the maximum time (in seconds) allowed
146     * for a search. A value of 0 in this field indicates that no client-
147     * requested timelimit restrictions are in effect for the search.
148     * 
149     * @param secondsMax the search time limit in seconds.
150     * @return The SearchRequest instance
151     */
152    SearchRequest setTimeLimit( int secondsMax );
153
154
155    /**
156     * An indicator as to whether search results will contain both attribute
157     * types and values, or just attribute types. Setting this field to TRUE
158     * causes only attribute types (no values) to be returned. Setting this
159     * field to FALSE causes both attribute types and values to be returned.
160     * 
161     * @return true for only types, false for types and values.
162     */
163    boolean getTypesOnly();
164
165
166    /**
167     * An indicator as to whether search results will contain both attribute
168     * types and values, or just attribute types. Setting this field to TRUE
169     * causes only attribute types (no values) to be returned. Setting this
170     * field to FALSE causes both attribute types and values to be returned.
171     * 
172     * @param typesOnly true for only types, false for types and values.
173     * @return The SearchRequest instance
174     */
175    SearchRequest setTypesOnly( boolean typesOnly );
176
177
178    /**
179     * Gets the search filter associated with this search request.
180     * 
181     * @return the expression node for the root of the filter expression tree.
182     */
183    ExprNode getFilter();
184
185
186    /**
187     * Sets the search filter associated with this search request.
188     * 
189     * @param filter the expression node for the root of the filter expression tree.
190     * @return The SearchRequest instance
191     */
192    SearchRequest setFilter( ExprNode filter );
193
194
195    /**
196     * Sets the search filter associated with this search request.
197     * 
198     * @param filter the expression node for the root of the filter expression tree.
199     * @return The SearchRequest instance
200     */
201    SearchRequest setFilter( String filter ) throws LdapException;
202
203
204    /**
205     * Gets a list of the attributes to be returned from each entry which
206     * matches the search filter. There are two special values which may be
207     * used: an empty list with no attributes, and the attribute description
208     * string "*". Both of these signify that all user attributes are to be
209     * returned. (The "*" allows the client to request all user attributes in
210     * addition to specific operational attributes). Attributes MUST be named at
211     * most once in the list, and are returned at most once in an entry. If
212     * there are attribute descriptions in the list which are not recognized,
213     * they are ignored by the server. If the client does not want any
214     * attributes returned, it can specify a list containing only the attribute
215     * with OID "1.1". This OID was chosen arbitrarily and does not correspond
216     * to any attribute in use. Client implementors should note that even if all
217     * user attributes are requested, some attributes of the entry may not be
218     * included in search results due to access control or other restrictions.
219     * Furthermore, servers will not return operational attributes, such as
220     * objectClasses or attributeTypes, unless they are listed by name, since
221     * there may be extremely large number of values for certain operational
222     * attributes.
223     * 
224     * @return the attributes to return for this request
225     */
226    List<String> getAttributes();
227
228
229    /**
230     * Adds some attributes to the set of entry attributes to return.
231     * 
232     * @param attributes the attributes description or identifier.
233     * @return The SearchRequest instance
234     */
235    SearchRequest addAttributes( String... attributes );
236
237
238    /**
239     * Removes an attribute to the set of entry attributes to return.
240     * 
241     * @param attribute the attribute description or identifier.
242     * @return The SearchRequest instance
243     */
244    SearchRequest removeAttribute( String attribute );
245
246
247    /**
248     * {@inheritDoc}
249     */
250    SearchRequest setMessageId( int messageId );
251    
252    
253    /**
254     * {@inheritDoc}
255     */
256    SearchRequest addControl( Control control ) throws MessageException;
257    
258    
259    /**
260     * {@inheritDoc}
261     */
262    SearchRequest addAllControls( Control[] controls ) throws MessageException;
263    
264    
265    /**
266     * {@inheritDoc}
267     */
268    SearchRequest removeControl( Control control ) throws MessageException;
269}