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