1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.api.ldap.model.message;
21
22
23 import java.util.List;
24
25 import org.apache.directory.api.ldap.model.exception.LdapException;
26 import org.apache.directory.api.ldap.model.filter.ExprNode;
27 import org.apache.directory.api.ldap.model.name.Dn;
28
29
30 /**
31 * Search request protocol message interface.
32 *
33 * @author <a href="mailto:dev@directory.apache.org"> Apache Directory Project</a>
34 */
35 public interface SearchRequest extends ManyReplyRequest, AbandonableRequest
36 {
37 /**
38 * Different response types that a search request may return. A search
39 * request unlike any other request type can generate four different kinds
40 * of responses. It is at most required to return a done response when it is
41 * complete however before then it can return search entry, search
42 * reference, and extended responses to the client.
43 *
44 * @see #getResponseTypes()
45 */
46 MessageTypeEnum[] RESPONSE_TYPES =
47 {
48 MessageTypeEnum.SEARCH_RESULT_DONE,
49 MessageTypeEnum.SEARCH_RESULT_ENTRY,
50 MessageTypeEnum.SEARCH_RESULT_REFERENCE,
51 MessageTypeEnum.EXTENDED_RESPONSE
52 };
53
54
55 /**
56 * Gets the different response types generated by a search request.
57 *
58 * @return the RESPONSE_TYPES array
59 * @see #RESPONSE_TYPES
60 */
61 @Override
62 MessageTypeEnum[] getResponseTypes();
63
64
65 /**
66 * Gets the search base as a distinguished name.
67 *
68 * @return the search base
69 */
70 Dn getBase();
71
72
73 /**
74 * Sets the search base as a distinguished name.
75 *
76 * @param baseDn the search base
77 * @return The SearchRequest instance
78 */
79 SearchRequest setBase( Dn baseDn );
80
81
82 /**
83 * Gets the search scope parameter enumeration.
84 *
85 * @return the scope enumeration parameter.
86 */
87 SearchScope getScope();
88
89
90 /**
91 * Sets the search scope parameter enumeration.
92 *
93 * @param scope the scope enumeration parameter.
94 * @return The SearchRequest instance
95 */
96 SearchRequest setScope( SearchScope scope );
97
98
99 /**
100 * Gets the alias handling parameter.
101 *
102 * @return the alias handling parameter enumeration.
103 */
104 AliasDerefMode getDerefAliases();
105
106
107 /**
108 * Sets the alias handling parameter.
109 *
110 * @param aliasDerefAliases the alias handling parameter enumeration.
111 * @return The SearchRequest instance
112 */
113 SearchRequest setDerefAliases( AliasDerefMode aliasDerefAliases );
114
115
116 /**
117 * A sizelimit that restricts the maximum number of entries to be returned
118 * as a result of the search. A value of 0 in this field indicates that no
119 * client-requested sizelimit restrictions are in effect for the search.
120 * Servers may enforce a maximum number of entries to return.
121 *
122 * @return search size limit.
123 */
124 long getSizeLimit();
125
126
127 /**
128 * Sets sizelimit that restricts the maximum number of entries to be
129 * returned as a result of the search. A value of 0 in this field indicates
130 * that no client-requested sizelimit restrictions are in effect for the
131 * search. Servers may enforce a maximum number of entries to return.
132 *
133 * @param entriesMax maximum search result entries to return.
134 * @return The SearchRequest instance
135 */
136 SearchRequest setSizeLimit( long entriesMax );
137
138
139 /**
140 * Gets the timelimit that restricts the maximum time (in seconds) allowed
141 * for a search. A value of 0 in this field indicates that no client-
142 * requested timelimit restrictions are in effect for the search.
143 *
144 * @return the search time limit in seconds.
145 */
146 int getTimeLimit();
147
148
149 /**
150 * Sets the timelimit that restricts the maximum time (in seconds) allowed
151 * for a search. A value of 0 in this field indicates that no client-
152 * requested timelimit restrictions are in effect for the search.
153 *
154 * @param secondsMax the search time limit in seconds.
155 * @return The SearchRequest instance
156 */
157 SearchRequest setTimeLimit( int secondsMax );
158
159
160 /**
161 * An indicator as to whether search results will contain both attribute
162 * types and values, or just attribute types. Setting this field to TRUE
163 * causes only attribute types (no values) to be returned. Setting this
164 * field to FALSE causes both attribute types and values to be returned.
165 *
166 * @return true for only types, false for types and values.
167 */
168 boolean getTypesOnly();
169
170
171 /**
172 * An indicator as to whether search results will contain both attribute
173 * types and values, or just attribute types. Setting this field to TRUE
174 * causes only attribute types (no values) to be returned. Setting this
175 * field to FALSE causes both attribute types and values to be returned.
176 *
177 * @param typesOnly true for only types, false for types and values.
178 * @return The SearchRequest instance
179 */
180 SearchRequest setTypesOnly( boolean typesOnly );
181
182
183 /**
184 * Gets the search filter associated with this search request.
185 *
186 * @return the expression node for the root of the filter expression tree.
187 */
188 ExprNode getFilter();
189
190
191 /**
192 * Sets the search filter associated with this search request.
193 *
194 * @param filter the expression node for the root of the filter expression tree.
195 * @return The SearchRequest instance
196 */
197 SearchRequest setFilter( ExprNode filter );
198
199
200 /**
201 * Sets the search filter associated with this search request.
202 *
203 * @param filter the expression node for the root of the filter expression tree.
204 * @return The SearchRequest instance
205 * @throws LdapException If the filter can't be added
206 */
207 SearchRequest setFilter( String filter ) throws LdapException;
208
209
210 /**
211 * Gets a list of the attributes to be returned from each entry which
212 * matches the search filter. There are two special values which may be
213 * used: an empty list with no attributes, and the attribute description
214 * string "*". Both of these signify that all user attributes are to be
215 * returned. (The "*" allows the client to request all user attributes in
216 * addition to specific operational attributes). Attributes MUST be named at
217 * most once in the list, and are returned at most once in an entry. If
218 * there are attribute descriptions in the list which are not recognized,
219 * they are ignored by the server. If the client does not want any
220 * attributes returned, it can specify a list containing only the attribute
221 * with OID "1.1". This OID was chosen arbitrarily and does not correspond
222 * to any attribute in use. Client implementors should note that even if all
223 * user attributes are requested, some attributes of the entry may not be
224 * included in search results due to access control or other restrictions.
225 * Furthermore, servers will not return operational attributes, such as
226 * objectClasses or attributeTypes, unless they are listed by name, since
227 * there may be extremely large number of values for certain operational
228 * attributes.
229 *
230 * @return the attributes to return for this request
231 */
232 List<String> getAttributes();
233
234
235 /**
236 * Adds some attributes to the set of entry attributes to return.
237 *
238 * @param attributes the attributes description or identifier.
239 * @return The SearchRequest instance
240 */
241 SearchRequest addAttributes( String... attributes );
242
243
244 /**
245 * Removes an attribute to the set of entry attributes to return.
246 *
247 * @param attribute the attribute description or identifier.
248 * @return The SearchRequest instance
249 */
250 SearchRequest removeAttribute( String attribute );
251
252
253 /**
254 * {@inheritDoc}
255 */
256 @Override
257 SearchRequest setMessageId( int messageId );
258
259
260 /**
261 * {@inheritDoc}
262 */
263 @Override
264 SearchRequest addControl( Control control );
265
266
267 /**
268 * {@inheritDoc}
269 */
270 @Override
271 SearchRequest addAllControls( Control[] controls );
272
273
274 /**
275 * {@inheritDoc}
276 */
277 @Override
278 SearchRequest removeControl( Control control );
279
280
281 /**
282 * Tells the client if it should follow referrals instead of throwing exceptions
283 * @return true if we should follow the referrals
284 */
285 boolean isFollowReferrals();
286
287
288 /**
289 * Tells the client to follow referrals instead of throwing exceptions
290 * @return The SearchRequest instance
291 */
292 SearchRequest followReferrals();
293
294
295 /**
296 * Tells the client if it should ignore referrals instead of throwing exceptions
297 * @return true if we should ignore the referrals
298 */
299 boolean isIgnoreReferrals();
300
301
302 /**
303 * Tells the client to ignore referrals instead of throwing exceptions. The entry
304 * will contain the referral attributeType with the link.
305 *
306 * @return The SearchRequest instance
307 */
308 SearchRequest ignoreReferrals();
309 }