001 /*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License"). You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2006-2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.core;
028
029 import java.util.LinkedHashSet;
030 import java.util.List;
031
032 import org.opends.server.controls.MatchedValuesControl;
033 import org.opends.server.types.ByteString;
034 import org.opends.server.types.Control;
035 import org.opends.server.types.DN;
036 import org.opends.server.types.DereferencePolicy;
037 import org.opends.server.types.DirectoryException;
038 import org.opends.server.types.Entry;
039 import org.opends.server.types.Operation;
040 import org.opends.server.types.RawFilter;
041 import org.opends.server.types.SearchFilter;
042 import org.opends.server.types.SearchResultEntry;
043 import org.opends.server.types.SearchResultReference;
044 import org.opends.server.types.SearchScope;
045
046 /**
047 * This interface defines an operation used to search for entries
048 * in the Directory Server.
049 */
050 public interface SearchOperation extends Operation
051 {
052
053 /**
054 * Retrieves the raw, unprocessed base DN as included in the request from the
055 * client. This may or may not contain a valid DN, as no validation will have
056 * been performed.
057 *
058 * @return The raw, unprocessed base DN as included in the request from the
059 * client.
060 */
061 public abstract ByteString getRawBaseDN();
062
063 /**
064 * Specifies the raw, unprocessed base DN as included in the request from the
065 * client. This method should only be called by pre-parse plugins.
066 *
067 * @param rawBaseDN The raw, unprocessed base DN as included in the request
068 * from the client.
069 */
070 public abstract void setRawBaseDN(ByteString rawBaseDN);
071
072 /**
073 * Retrieves the base DN for this search operation. This should not be called
074 * by pre-parse plugins, as the raw base DN will not yet have been processed.
075 * Instead, they should use the <CODE>getRawBaseDN</CODE> method.
076 *
077 * @return The base DN for this search operation, or <CODE>null</CODE> if the
078 * raw base DN has not yet been processed.
079 */
080 public abstract DN getBaseDN();
081
082 /**
083 * Specifies the base DN for this search operation. This method is only
084 * intended for internal use.
085 *
086 * @param baseDN The base DN for this search operation.
087 */
088 public abstract void setBaseDN(DN baseDN);
089
090 /**
091 * Retrieves the scope for this search operation.
092 *
093 * @return The scope for this search operation.
094 */
095 public abstract SearchScope getScope();
096
097 /**
098 * Specifies the scope for this search operation. This should only be called
099 * by pre-parse plugins.
100 *
101 * @param scope The scope for this search operation.
102 */
103 public abstract void setScope(SearchScope scope);
104
105 /**
106 * Retrieves the alias dereferencing policy for this search operation.
107 *
108 * @return The alias dereferencing policy for this search operation.
109 */
110 public abstract DereferencePolicy getDerefPolicy();
111
112 /**
113 * Specifies the alias dereferencing policy for this search operation. This
114 * should only be called by pre-parse plugins.
115 *
116 * @param derefPolicy The alias dereferencing policy for this search
117 * operation.
118 */
119 public abstract void setDerefPolicy(DereferencePolicy derefPolicy);
120
121 /**
122 * Retrieves the size limit for this search operation.
123 *
124 * @return The size limit for this search operation.
125 */
126 public abstract int getSizeLimit();
127
128 /**
129 * Specifies the size limit for this search operation. This should only be
130 * called by pre-parse plugins.
131 *
132 * @param sizeLimit The size limit for this search operation.
133 */
134 public abstract void setSizeLimit(int sizeLimit);
135
136 /**
137 * Retrieves the time limit for this search operation.
138 *
139 * @return The time limit for this search operation.
140 */
141 public abstract int getTimeLimit();
142
143 /**
144 * Get the time after which the search time limit has expired.
145 *
146 * @return the timeLimitExpiration
147 */
148 public abstract Long getTimeLimitExpiration();
149
150 /**
151 * Specifies the time limit for this search operation. This should only be
152 * called by pre-parse plugins.
153 *
154 * @param timeLimit The time limit for this search operation.
155 */
156 public abstract void setTimeLimit(int timeLimit);
157
158 /**
159 * Retrieves the typesOnly flag for this search operation.
160 *
161 * @return The typesOnly flag for this search operation.
162 */
163 public abstract boolean getTypesOnly();
164
165 /**
166 * Specifies the typesOnly flag for this search operation. This should only
167 * be called by pre-parse plugins.
168 *
169 * @param typesOnly The typesOnly flag for this search operation.
170 */
171 public abstract void setTypesOnly(boolean typesOnly);
172
173 /**
174 * Retrieves the raw, unprocessed search filter as included in the request
175 * from the client. It may or may not contain a valid filter (e.g.,
176 * unsupported attribute types or values with an invalid syntax) because no
177 * validation will have been performed on it.
178 *
179 * @return The raw, unprocessed search filter as included in the request from
180 * the client.
181 */
182 public abstract RawFilter getRawFilter();
183
184 /**
185 * Specifies the raw, unprocessed search filter as included in the request
186 * from the client. This method should only be called by pre-parse plugins.
187 *
188 * @param rawFilter The raw, unprocessed search filter as included in the
189 * request from the client.
190 */
191 public abstract void setRawFilter(RawFilter rawFilter);
192
193 /**
194 * Retrieves the filter for this search operation. This should not be called
195 * by pre-parse plugins, because the raw filter will not yet have been
196 * processed.
197 *
198 * @return The filter for this search operation, or <CODE>null</CODE> if the
199 * raw filter has not yet been processed.
200 */
201 public abstract SearchFilter getFilter();
202
203 /**
204 * Retrieves the set of requested attributes for this search operation. Its
205 * contents should not be be altered.
206 *
207 * @return The set of requested attributes for this search operation.
208 */
209 public abstract LinkedHashSet<String> getAttributes();
210
211 /**
212 * Specifies the set of requested attributes for this search operation. It
213 * should only be called by pre-parse plugins.
214 *
215 * @param attributes The set of requested attributes for this search
216 * operation.
217 */
218 public abstract void setAttributes(LinkedHashSet<String> attributes);
219
220 /**
221 * Retrieves the number of entries sent to the client for this search
222 * operation.
223 *
224 * @return The number of entries sent to the client for this search
225 * operation.
226 */
227 public abstract int getEntriesSent();
228
229 /**
230 * Retrieves the number of search references sent to the client for this
231 * search operation.
232 *
233 * @return The number of search references sent to the client for this search
234 * operation.
235 */
236 public abstract int getReferencesSent();
237
238 /**
239 * Used as a callback for backends to indicate that the provided entry matches
240 * the search criteria and that additional processing should be performed to
241 * potentially send it back to the client.
242 *
243 * @param entry The entry that matches the search criteria and should be
244 * sent to the client.
245 * @param controls The set of controls to include with the entry (may be
246 * <CODE>null</CODE> if none are needed).
247 *
248 * @return <CODE>true</CODE> if the caller should continue processing the
249 * search request and sending additional entries and references, or
250 * <CODE>false</CODE> if not for some reason (e.g., the size limit
251 * has been reached or the search has been abandoned).
252 */
253 public abstract boolean returnEntry(Entry entry, List<Control> controls);
254
255 /**
256 * Used as a callback for backends to indicate that the provided search
257 * reference was encountered during processing and that additional processing
258 * should be performed to potentially send it back to the client.
259 *
260 * @param reference The search reference to send to the client.
261 * @param dn The DN related to the specified search reference.
262 *
263 * @return <CODE>true</CODE> if the caller should continue processing the
264 * search request and sending additional entries and references , or
265 * <CODE>false</CODE> if not for some reason (e.g., the size limit
266 * has been reached or the search has been abandoned).
267 */
268 public abstract boolean returnReference(DN dn,
269 SearchResultReference reference);
270
271 /**
272 * Sends the search result done message to the client. Note that this method
273 * should only be called from external classes in special cases (e.g.,
274 * persistent search) where they are sure that the result won't be sent by the
275 * core server. Also note that the result code and optionally the error
276 * message should have been set for this operation before this method is
277 * called.
278 */
279 public abstract void sendSearchResultDone();
280
281 /**
282 * Set the time after which the search time limit has expired.
283 *
284 * @param timeLimitExpiration - Time after which the search has expired
285 */
286 public abstract void setTimeLimitExpiration(Long timeLimitExpiration);
287
288 /**
289 * Indicates whether LDAP subentries should be returned or not.
290 *
291 * @return true if the LDAP subentries should be returned, false otherwise
292 */
293 public abstract boolean isReturnLDAPSubentries();
294
295 /**
296 * Set the flag indicating wether the LDAP subentries should be returned.
297 *
298 * @param returnLDAPSubentries - Boolean indicating wether the LDAP
299 * subentries should be returned or not
300 */
301 public abstract void setReturnLDAPSubentries(boolean returnLDAPSubentries);
302
303 /**
304 * The matched values control associated with this search operation.
305 *
306 * @return the match values control
307 */
308 public abstract MatchedValuesControl getMatchedValuesControl();
309
310 /**
311 * Set the match values control.
312 *
313 * @param controls - The matched values control
314 */
315 public abstract void setMatchedValuesControl(MatchedValuesControl controls);
316
317 /**
318 * Indicates whether to include the account usable response control with
319 * search result entries or not.
320 *
321 * @return true if the usable control has to be part of the search result
322 * entry
323 */
324 public abstract boolean isIncludeUsableControl();
325
326 /**
327 * Specify whether to include the account usable response control within the
328 * search result entries.
329 *
330 * @param includeUsableControl - True if the account usable response control
331 * has to be included within the search result
332 * entries, false otherwise
333 */
334 public abstract void setIncludeUsableControl(boolean includeUsableControl);
335
336 /**
337 * Register the psearch in the search operation.
338 *
339 * @param psearch - Persistent search associated to that operation
340 */
341 public abstract void setPersistentSearch(PersistentSearch psearch);
342
343 /**
344 * Get the psearch from the search operation.
345 *
346 * @return the psearch, or null if no psearch was registered
347 */
348 public abstract PersistentSearch getPersistentSearch();
349
350 /**
351 * Indicates whether the client is able to handle referrals.
352 *
353 * @return true, if the client is able to handle referrals
354 */
355 public abstract boolean isClientAcceptsReferrals();
356
357 /**
358 * Specify whether the client is able to handle referrals.
359 *
360 * @param clientAcceptReferrals - Boolean set to true if the client
361 * can handle referrals
362 */
363 public abstract void setClientAcceptsReferrals(boolean clientAcceptReferrals);
364
365 /**
366 * Increments by 1 the number of entries sent to the client for this search
367 * operation.
368 */
369 public abstract void incrementEntriesSent();
370
371 /**
372 * Increments by 1 the number of search references sent to the client for this
373 * search operation.
374 */
375 public abstract void incrementReferencesSent();
376
377 /**
378 * Indicates wether the search result done message has to be sent
379 * to the client, or not.
380 *
381 * @return true if the search result done message is to be sent to the client
382 */
383 public abstract boolean isSendResponse();
384
385 /**
386 * Specify wether the search result done message has to be sent
387 * to the client, or not.
388 *
389 * @param sendResponse - boolean indicating wether the search result done
390 * message is to send to the client
391 */
392 public abstract void setSendResponse(boolean sendResponse);
393
394 /**
395 * Returns true if only real attributes should be returned.
396 *
397 * @return true if only real attributes should be returned, false otherwise
398 */
399 public abstract boolean isRealAttributesOnly();
400
401 /**
402 * Specify wether to only return real attributes.
403 *
404 * @param realAttributesOnly - boolean setup to true, if only the real
405 * attributes should be returned
406 */
407 public abstract void setRealAttributesOnly(boolean realAttributesOnly);
408
409 /**
410 * Returns true if only virtual attributes should be returned.
411 *
412 * @return true if only virtual attributes should be returned, false
413 * otherwise
414 */
415 public abstract boolean isVirtualAttributesOnly();
416
417 /**
418 * Specify wether to only return virtual attributes.
419 *
420 * @param virtualAttributesOnly - boolean setup to true, if only the virtual
421 * attributes should be returned
422 */
423 public abstract void setVirtualAttributesOnly(boolean virtualAttributesOnly);
424
425 /**
426 * Sends the provided search result entry to the client.
427 *
428 * @param entry The search result entry to be sent to
429 * the client.
430 *
431 * @throws DirectoryException If a problem occurs while attempting
432 * to send the entry to the client and
433 * the search should be terminated.
434 */
435 public abstract void sendSearchEntry(SearchResultEntry entry)
436 throws DirectoryException;
437
438 /**
439 * Sends the provided search result reference to the client.
440 *
441 * @param reference The search result reference to be sent
442 * to the client.
443 *
444 * @return <CODE>true</CODE> if the client is able to accept
445 * referrals, or <CODE>false</CODE> if the client cannot
446 * handle referrals and no more attempts should be made to
447 * send them for the associated search operation.
448 *
449 * @throws DirectoryException If a problem occurs while attempting
450 * to send the reference to the client
451 * and the search should be terminated.
452 */
453 public abstract boolean sendSearchReference(SearchResultReference reference)
454 throws DirectoryException;
455
456 /**
457 * Retrieves the proxied authorization DN for this operation if proxied
458 * authorization has been requested.
459 *
460 * @return The proxied authorization DN for this operation if proxied
461 * authorization has been requested, or {@code null} if proxied
462 * authorization has not been requested.
463 */
464 public abstract DN getProxiedAuthorizationDN();
465
466 /**
467 * Set the proxied authorization DN for this operation if proxied
468 * authorization has been requested.
469 *
470 * @param proxiedAuthorizationDN
471 * The proxied authorization DN for this operation if proxied
472 * authorization has been requested, or {@code null} if proxied
473 * authorization has not been requested.
474 */
475 public abstract void setProxiedAuthorizationDN(DN proxiedAuthorizationDN);
476
477 }