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 legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2006-2009 Sun Microsystems, Inc.
025 *      Portions Copyright 2011-2014 ForgeRock AS
026 */
027package org.opends.server.core;
028
029import java.util.List;
030import java.util.Set;
031
032import org.forgerock.opendj.ldap.ByteString;
033import org.forgerock.opendj.ldap.DereferenceAliasesPolicy;
034import org.forgerock.opendj.ldap.SearchScope;
035import org.opends.server.controls.MatchedValuesControl;
036import org.opends.server.types.Control;
037import org.opends.server.types.DN;
038import org.opends.server.types.DirectoryException;
039import org.opends.server.types.Entry;
040import org.opends.server.types.Operation;
041import org.opends.server.types.RawFilter;
042import org.opends.server.types.SearchFilter;
043import org.opends.server.types.SearchResultEntry;
044import org.opends.server.types.SearchResultReference;
045
046/**
047 * This interface defines an operation used to search for entries
048 * in the Directory Server.
049 */
050public 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  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  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  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  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  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  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  DereferenceAliasesPolicy 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  void setDerefPolicy(DereferenceAliasesPolicy derefPolicy);
120
121  /**
122   * Retrieves the size limit for this search operation.
123   *
124   * @return  The size limit for this search operation.
125   */
126  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  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  int getTimeLimit();
142
143  /**
144   * Get the time after which the search time limit has expired.
145   *
146   * @return the timeLimitExpiration
147   */
148  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  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  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  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  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  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  SearchFilter getFilter();
202
203  /**
204   * Retrieves the set of requested attributes for this search operation.  Its
205   * contents should not be altered.
206   *
207   * @return  The set of requested attributes for this search operation.
208   */
209  Set<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  void setAttributes(Set<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  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  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  boolean returnEntry(Entry entry, List<Control> controls);
254
255  /**
256   * Used as a callback for backends to indicate that the provided entry matches
257   * the search criteria and that additional processing should be performed to
258   * potentially send it back to the client.
259   *
260   * @param  entry        The entry that matches the search criteria and should
261   *                      be sent to the client.
262   * @param  controls     The set of controls to include with the entry (may be
263   *                      <CODE>null</CODE> if none are needed).
264   * @param  evaluateAci  Indicates whether the access rights to the entry
265   *                      should be evaluated.
266   *
267   * @return  <CODE>true</CODE> if the caller should continue processing the
268   *          search request and sending additional entries and references, or
269   *          <CODE>false</CODE> if not for some reason (e.g., the size limit
270   *          has been reached or the search has been abandoned).
271   */
272  boolean returnEntry(Entry entry, List<Control> controls,
273                                      boolean evaluateAci);
274
275  /**
276   * Used as a callback for backends to indicate that the provided search
277   * reference was encountered during processing and that additional processing
278   * should be performed to potentially send it back to the client.
279   *
280   * @param  reference  The search reference to send to the client.
281   * @param  dn         The DN related to the specified search reference.
282   *
283   * @return  <CODE>true</CODE> if the caller should continue processing the
284   *          search request and sending additional entries and references , or
285   *          <CODE>false</CODE> if not for some reason (e.g., the size limit
286   *          has been reached or the search has been abandoned).
287   */
288  boolean returnReference(DN dn,
289                                          SearchResultReference reference);
290
291  /**
292   * Used as a callback for backends to indicate that the provided search
293   * reference was encountered during processing and that additional processing
294   * should be performed to potentially send it back to the client.
295   *
296   * @param  reference    The search reference to send to the client.
297   * @param  dn           The DN related to the specified search reference.
298   * @param  evaluateAci  Indicates whether the access rights to the entry
299   *                      should be evaluated.
300   *
301   * @return  <CODE>true</CODE> if the caller should continue processing the
302   *          search request and sending additional entries and references , or
303   *          <CODE>false</CODE> if not for some reason (e.g., the size limit
304   *          has been reached or the search has been abandoned).
305   */
306  boolean returnReference(DN dn,
307                                          SearchResultReference reference,
308                                          boolean evaluateAci);
309
310  /**
311   * Sends the search result done message to the client.  Note that this method
312   * should only be called from external classes in special cases (e.g.,
313   * persistent search) where they are sure that the result won't be sent by the
314   * core server.  Also note that the result code and optionally the error
315   * message should have been set for this operation before this method is
316   * called.
317   */
318  void sendSearchResultDone();
319
320  /**
321   * Set the time after which the search time limit has expired.
322   *
323   * @param timeLimitExpiration - Time after which the search has expired
324   */
325  void setTimeLimitExpiration(long timeLimitExpiration);
326
327  /**
328   * Indicates whether LDAP subentries should be returned or not.
329   *
330   * @return true if the LDAP subentries should be returned, false otherwise
331   */
332  boolean isReturnSubentriesOnly();
333
334  /**
335   * Set the flag indicating whether the LDAP subentries should be returned.
336   *
337   * @param returnLDAPSubentries - Boolean indicating whether the LDAP
338   *                               subentries should be returned or not
339   */
340  void setReturnSubentriesOnly(boolean returnLDAPSubentries);
341
342  /**
343   * The matched values control associated with this search operation.
344   *
345   * @return the match values control
346   */
347  MatchedValuesControl getMatchedValuesControl();
348
349  /**
350   * Set the match values control.
351   *
352   * @param controls - The matched values control
353   */
354  void setMatchedValuesControl(MatchedValuesControl controls);
355
356  /**
357   * Indicates whether to include the account usable response control with
358   * search result entries or not.
359   *
360   * @return true if the usable control has to be part of the search result
361   *         entry
362   */
363  boolean isIncludeUsableControl();
364
365  /**
366   * Specify whether to include the account usable response control within the
367   * search result entries.
368   *
369   * @param includeUsableControl - True if the account usable response control
370   *                               has to be included within the search result
371   *                               entries, false otherwise
372   */
373  void setIncludeUsableControl(boolean includeUsableControl);
374
375  /**
376   * Indicates whether the client is able to handle referrals.
377   *
378   * @return true, if the client is able to handle referrals
379   */
380  boolean isClientAcceptsReferrals();
381
382  /**
383   * Specify whether the client is able to handle referrals.
384   *
385   * @param clientAcceptReferrals - Boolean set to true if the client
386   *                                can handle referrals
387   */
388  void setClientAcceptsReferrals(boolean clientAcceptReferrals);
389
390  /**
391   * Indicates whether the search result done message has to be sent
392   * to the client, or not.
393   *
394   * @return true if the search result done message is to be sent to the client
395   */
396  boolean isSendResponse();
397
398  /**
399   * Specify whether the search result done message has to be sent
400   * to the client, or not.
401   *
402   * @param sendResponse - boolean indicating whether the search result done
403   *                       message is to send to the client
404   */
405  void setSendResponse(boolean sendResponse);
406
407  /**
408   * Returns true if only real attributes should be returned.
409   *
410   * @return true if only real attributes should be returned, false otherwise
411   */
412  boolean isRealAttributesOnly();
413
414  /**
415   * Specify whether to only return real attributes.
416   *
417   * @param realAttributesOnly - boolean setup to true, if only the real
418   *                             attributes should be returned
419   */
420  void setRealAttributesOnly(boolean realAttributesOnly);
421
422  /**
423   * Returns true if only virtual attributes should be returned.
424   *
425   * @return true if only virtual attributes should be returned, false
426   *         otherwise
427   */
428  boolean isVirtualAttributesOnly();
429
430  /**
431   * Specify whether to only return virtual attributes.
432   *
433   * @param virtualAttributesOnly - boolean setup to true, if only the virtual
434   *                                attributes should be returned
435   */
436  void setVirtualAttributesOnly(boolean virtualAttributesOnly);
437
438  /**
439   * Sends the provided search result entry to the client.
440   *
441   * @param  entry      The search result entry to be sent to
442   *                          the client.
443   *
444   * @throws  DirectoryException  If a problem occurs while attempting
445   *                              to send the entry to the client and
446   *                              the search should be terminated.
447   */
448  void sendSearchEntry(SearchResultEntry entry)
449    throws DirectoryException;
450
451  /**
452   * Sends the provided search result reference to the client.
453   *
454   * @param  reference  The search result reference to be sent
455   *                          to the client.
456   *
457   * @return  <CODE>true</CODE> if the client is able to accept
458   *          referrals, or <CODE>false</CODE> if the client cannot
459   *          handle referrals and no more attempts should be made to
460   *          send them for the associated search operation.
461   *
462   * @throws  DirectoryException  If a problem occurs while attempting
463   *                              to send the reference to the client
464   *                              and the search should be terminated.
465   */
466  boolean sendSearchReference(SearchResultReference reference)
467    throws DirectoryException;
468
469  /**
470   * Retrieves the proxied authorization DN for this operation if proxied
471   * authorization has been requested.
472   *
473   * @return  The proxied authorization DN for this operation if proxied
474   *          authorization has been requested, or {@code null} if proxied
475   *          authorization has not been requested.
476   */
477  DN getProxiedAuthorizationDN();
478
479  /**
480   * Set the proxied authorization DN for this operation if proxied
481   * authorization has been requested.
482   *
483   * @param proxiedAuthorizationDN
484   *          The proxied authorization DN for this operation if proxied
485   *          authorization has been requested, or {@code null} if proxied
486   *          authorization has not been requested.
487   */
488  void setProxiedAuthorizationDN(DN proxiedAuthorizationDN);
489
490}