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    }