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 MessageTypeEnum[] getResponseTypes();
62
63
64 /**
65 * Gets the search base as a distinguished name.
66 *
67 * @return the search base
68 */
69 Dn getBase();
70
71
72 /**
73 * Sets the search base as a distinguished name.
74 *
75 * @param baseDn the search base
76 * @return The SearchRequest instance
77 */
78 SearchRequest setBase( Dn baseDn );
79
80
81 /**
82 * Gets the search scope parameter enumeration.
83 *
84 * @return the scope enumeration parameter.
85 */
86 SearchScope getScope();
87
88
89 /**
90 * Sets the search scope parameter enumeration.
91 *
92 * @param scope the scope enumeration parameter.
93 * @return The SearchRequest instance
94 */
95 SearchRequest setScope( SearchScope scope );
96
97
98 /**
99 * 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 */
205 SearchRequest setFilter( String filter ) throws LdapException;
206
207
208 /**
209 * Gets a list of the attributes to be returned from each entry which
210 * matches the search filter. There are two special values which may be
211 * used: an empty list with no attributes, and the attribute description
212 * string "*". Both of these signify that all user attributes are to be
213 * returned. (The "*" allows the client to request all user attributes in
214 * addition to specific operational attributes). Attributes MUST be named at
215 * most once in the list, and are returned at most once in an entry. If
216 * there are attribute descriptions in the list which are not recognized,
217 * they are ignored by the server. If the client does not want any
218 * attributes returned, it can specify a list containing only the attribute
219 * with OID "1.1". This OID was chosen arbitrarily and does not correspond
220 * to any attribute in use. Client implementors should note that even if all
221 * user attributes are requested, some attributes of the entry may not be
222 * included in search results due to access control or other restrictions.
223 * Furthermore, servers will not return operational attributes, such as
224 * objectClasses or attributeTypes, unless they are listed by name, since
225 * there may be extremely large number of values for certain operational
226 * attributes.
227 *
228 * @return the attributes to return for this request
229 */
230 List<String> getAttributes();
231
232
233 /**
234 * Adds some attributes to the set of entry attributes to return.
235 *
236 * @param attributes the attributes description or identifier.
237 * @return The SearchRequest instance
238 */
239 SearchRequest addAttributes( String... attributes );
240
241
242 /**
243 * Removes an attribute to the set of entry attributes to return.
244 *
245 * @param attribute the attribute description or identifier.
246 * @return The SearchRequest instance
247 */
248 SearchRequest removeAttribute( String attribute );
249
250
251 /**
252 * {@inheritDoc}
253 */
254 SearchRequest setMessageId( int messageId );
255
256
257 /**
258 * {@inheritDoc}
259 */
260 SearchRequest addControl( Control control );
261
262
263 /**
264 * {@inheritDoc}
265 */
266 SearchRequest addAllControls( Control[] controls );
267
268
269 /**
270 * {@inheritDoc}
271 */
272 SearchRequest removeControl( Control control );
273
274
275 /**
276 * Tells the client if it should follow referrals instead of throwing exceptions
277 * @return true if we should follow the referrals
278 */
279 boolean isFollowReferrals();
280
281
282 /**
283 * Tells the client to follow referrals instead of throwing exceptions
284 * @return The SearchRequest instance
285 */
286 SearchRequest followReferrals();
287
288
289 /**
290 * Tells the client if it should ignore referrals instead of throwing exceptions
291 * @return true if we should ignore the referrals
292 */
293 boolean isIgnoreReferrals();
294
295
296 /**
297 * Tells the client to ignore referrals instead of throwing exceptions. The entry
298 * will contain the referral attributeType with the link.
299 *
300 * @return The SearchRequest instance
301 */
302 SearchRequest ignoreReferrals();
303 }