001    /*
002     * Copyright 2007-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2015 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.sdk;
022    
023    
024    
025    import java.util.Collection;
026    import java.util.List;
027    
028    import com.unboundid.ldap.sdk.schema.Schema;
029    import com.unboundid.ldif.LDIFException;
030    import com.unboundid.util.NotExtensible;
031    import com.unboundid.util.ThreadSafety;
032    import com.unboundid.util.ThreadSafetyLevel;
033    
034    
035    
036    /**
037     * This interface defines a set of methods that are available for objects that
038     * may be used to communicate with an LDAP directory server.  This can be used
039     * to facilitate development of methods which can be used for either a single
040     * LDAP connection or an LDAP connection pool.
041     * <BR><BR>
042     * At present, all implementations provided by the LDAP SDK are at least mostly
043     * threadsafe and can be used to process multiple requests concurrently.
044     * However, this is not a hard requirement and it is conceivable that in the
045     * future a new implementation could be added which is not inherently
046     * threadsafe.  It is recommended that code which requires thread safety either
047     * provide their own external synchronization or use one of the subclasses which
048     * explicitly provides thread safety rather than relying on this generic
049     * interface.
050     */
051    @NotExtensible()
052    @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
053    public interface LDAPInterface
054    {
055      /**
056       * Retrieves the directory server root DSE.
057       *
058       * @return  The directory server root DSE, or {@code null} if it is not
059       *          available.
060       *
061       * @throws  LDAPException  If a problem occurs while attempting to retrieve
062       *                         the server root DSE.
063       */
064      RootDSE getRootDSE()
065           throws LDAPException;
066    
067    
068    
069      /**
070       * Retrieves the directory server schema definitions, using the subschema
071       * subentry DN contained in the server's root DSE.  For directory servers
072       * containing a single schema, this should be sufficient for all purposes.
073       * For servers with multiple schemas, it may be necessary to specify the DN
074       * of the target entry for which to obtain the associated schema.
075       *
076       * @return  The directory server schema definitions, or {@code null} if the
077       *          schema information could not be retrieved (e.g, the client does
078       *          not have permission to read the server schema).
079       *
080       * @throws  LDAPException  If a problem occurs while attempting to retrieve
081       *                         the server schema.
082       */
083      Schema getSchema()
084           throws LDAPException;
085    
086    
087    
088      /**
089       * Retrieves the directory server schema definitions that govern the specified
090       * entry.  The subschemaSubentry attribute will be retrieved from the target
091       * entry, and then the appropriate schema definitions will be loaded from the
092       * entry referenced by that attribute.  This may be necessary to ensure
093       * correct behavior in servers that support multiple schemas.
094       *
095       * @param  entryDN  The DN of the entry for which to retrieve the associated
096       *                  schema definitions.  It may be {@code null} or an empty
097       *                  string if the subschemaSubentry attribute should be
098       *                  retrieved from the server's root DSE.
099       *
100       * @return  The directory server schema definitions, or {@code null} if the
101       *          schema information could not be retrieved (e.g, the client does
102       *          not have permission to read the server schema).
103       *
104       * @throws  LDAPException  If a problem occurs while attempting to retrieve
105       *                         the server schema.
106       */
107      Schema getSchema(final String entryDN)
108           throws LDAPException;
109    
110    
111    
112      /**
113       * Retrieves the entry with the specified DN.  All user attributes will be
114       * requested in the entry to return.
115       *
116       * @param  dn  The DN of the entry to retrieve.  It must not be {@code null}.
117       *
118       * @return  The requested entry, or {@code null} if the target entry does not
119       *          exist or no entry was returned (e.g., if the authenticated user
120       *          does not have permission to read the target entry).
121       *
122       * @throws  LDAPException  If a problem occurs while sending the request or
123       *                         reading the response.
124       */
125      SearchResultEntry getEntry(final String dn)
126           throws LDAPException;
127    
128    
129    
130      /**
131       * Retrieves the entry with the specified DN.
132       *
133       * @param  dn          The DN of the entry to retrieve.  It must not be
134       *                     {@code null}.
135       * @param  attributes  The set of attributes to request for the target entry.
136       *                     If it is {@code null}, then all user attributes will be
137       *                     requested.
138       *
139       * @return  The requested entry, or {@code null} if the target entry does not
140       *          exist or no entry was returned (e.g., if the authenticated user
141       *          does not have permission to read the target entry).
142       *
143       * @throws  LDAPException  If a problem occurs while sending the request or
144       *                         reading the response.
145       */
146      SearchResultEntry getEntry(final String dn, final String... attributes)
147           throws LDAPException;
148    
149    
150    
151      /**
152       * Processes an add operation with the provided information.
153       *
154       * @param  dn          The DN of the entry to add.  It must not be
155       *                     {@code null}.
156       * @param  attributes  The set of attributes to include in the entry to add.
157       *                     It must not be {@code null}.
158       *
159       * @return  The result of processing the add operation.
160       *
161       * @throws  LDAPException  If the server rejects the add request, or if a
162       *                         problem is encountered while sending the request or
163       *                         reading the response.
164       */
165      LDAPResult add(final String dn, final Attribute... attributes)
166           throws LDAPException;
167    
168    
169    
170      /**
171       * Processes an add operation with the provided information.
172       *
173       * @param  dn          The DN of the entry to add.  It must not be
174       *                     {@code null}.
175       * @param  attributes  The set of attributes to include in the entry to add.
176       *                     It must not be {@code null}.
177       *
178       * @return  The result of processing the add operation.
179       *
180       * @throws  LDAPException  If the server rejects the add request, or if a
181       *                         problem is encountered while sending the request or
182       *                         reading the response.
183       */
184      LDAPResult add(final String dn, final Collection<Attribute> attributes)
185           throws LDAPException;
186    
187    
188    
189      /**
190       * Processes an add operation with the provided information.
191       *
192       * @param  entry  The entry to add.  It must not be {@code null}.
193       *
194       * @return  The result of processing the add operation.
195       *
196       * @throws  LDAPException  If the server rejects the add request, or if a
197       *                         problem is encountered while sending the request or
198       *                         reading the response.
199       */
200      LDAPResult add(final Entry entry)
201           throws LDAPException;
202    
203    
204    
205      /**
206       * Processes an add operation with the provided information.
207       *
208       * @param  ldifLines  The lines that comprise an LDIF representation of the
209       *                    entry to add.  It must not be empty or {@code null}.
210       *
211       * @return  The result of processing the add operation.
212       *
213       * @throws  LDIFException  If the provided entry lines cannot be decoded as an
214       *                         entry in LDIF form.
215       *
216       * @throws  LDAPException  If the server rejects the add request, or if a
217       *                         problem is encountered while sending the request or
218       *                         reading the response.
219       */
220      LDAPResult add(final String... ldifLines)
221           throws LDIFException, LDAPException;
222    
223    
224    
225      /**
226       * Processes the provided add request.
227       *
228       * @param  addRequest  The add request to be processed.  It must not be
229       *                     {@code null}.
230       *
231       * @return  The result of processing the add operation.
232       *
233       * @throws  LDAPException  If the server rejects the add request, or if a
234       *                         problem is encountered while sending the request or
235       *                         reading the response.
236       */
237      LDAPResult add(final AddRequest addRequest)
238           throws LDAPException;
239    
240    
241    
242      /**
243       * Processes the provided add request.
244       *
245       * @param  addRequest  The add request to be processed.  It must not be
246       *                     {@code null}.
247       *
248       * @return  The result of processing the add operation.
249       *
250       * @throws  LDAPException  If the server rejects the add request, or if a
251       *                         problem is encountered while sending the request or
252       *                         reading the response.
253       */
254      LDAPResult add(final ReadOnlyAddRequest addRequest)
255           throws LDAPException;
256    
257    
258    
259      /**
260       * Processes a compare operation with the provided information.
261       *
262       * @param  dn              The DN of the entry in which to make the
263       *                         comparison.  It must not be {@code null}.
264       * @param  attributeName   The attribute name for which to make the
265       *                         comparison.  It must not be {@code null}.
266       * @param  assertionValue  The assertion value to verify in the target entry.
267       *                         It must not be {@code null}.
268       *
269       * @return  The result of processing the compare operation.
270       *
271       * @throws  LDAPException  If the server rejects the compare request, or if a
272       *                         problem is encountered while sending the request or
273       *                         reading the response.
274       */
275      CompareResult compare(final String dn, final String attributeName,
276                            final String assertionValue)
277           throws LDAPException;
278    
279    
280    
281      /**
282       * Processes the provided compare request.
283       *
284       * @param  compareRequest  The compare request to be processed.  It must not
285       *                         be {@code null}.
286       *
287       * @return  The result of processing the compare operation.
288       *
289       * @throws  LDAPException  If the server rejects the compare request, or if a
290       *                         problem is encountered while sending the request or
291       *                         reading the response.
292       */
293      CompareResult compare(final CompareRequest compareRequest)
294           throws LDAPException;
295    
296    
297    
298      /**
299       * Processes the provided compare request.
300       *
301       * @param  compareRequest  The compare request to be processed.  It must not
302       *                         be {@code null}.
303       *
304       * @return  The result of processing the compare operation.
305       *
306       * @throws  LDAPException  If the server rejects the compare request, or if a
307       *                         problem is encountered while sending the request or
308       *                         reading the response.
309       */
310      CompareResult compare(final ReadOnlyCompareRequest compareRequest)
311           throws LDAPException;
312    
313    
314    
315      /**
316       * Deletes the entry with the specified DN.
317       *
318       * @param  dn  The DN of the entry to delete.  It must not be {@code null}.
319       *
320       * @return  The result of processing the delete operation.
321       *
322       * @throws  LDAPException  If the server rejects the delete request, or if a
323       *                         problem is encountered while sending the request or
324       *                         reading the response.
325       */
326      LDAPResult delete(final String dn)
327           throws LDAPException;
328    
329    
330    
331      /**
332       * Processes the provided delete request.
333       *
334       * @param  deleteRequest  The delete request to be processed.  It must not be
335       *                        {@code null}.
336       *
337       * @return  The result of processing the delete operation.
338       *
339       * @throws  LDAPException  If the server rejects the delete request, or if a
340       *                         problem is encountered while sending the request or
341       *                         reading the response.
342       */
343      LDAPResult delete(final DeleteRequest deleteRequest)
344           throws LDAPException;
345    
346    
347    
348      /**
349       * Processes the provided delete request.
350       *
351       * @param  deleteRequest  The delete request to be processed.  It must not be
352       *                        {@code null}.
353       *
354       * @return  The result of processing the delete operation.
355       *
356       * @throws  LDAPException  If the server rejects the delete request, or if a
357       *                         problem is encountered while sending the request or
358       *                         reading the response.
359       */
360      LDAPResult delete(final ReadOnlyDeleteRequest deleteRequest)
361           throws LDAPException;
362    
363    
364    
365      /**
366       * Applies the provided modification to the specified entry.
367       *
368       * @param  dn   The DN of the entry to modify.  It must not be {@code null}.
369       * @param  mod  The modification to apply to the target entry.  It must not
370       *              be {@code null}.
371       *
372       * @return  The result of processing the modify operation.
373       *
374       * @throws  LDAPException  If the server rejects the modify request, or if a
375       *                         problem is encountered while sending the request or
376       *                         reading the response.
377       */
378      LDAPResult modify(final String dn, final Modification mod)
379           throws LDAPException;
380    
381    
382    
383      /**
384       * Applies the provided set of modifications to the specified entry.
385       *
386       * @param  dn    The DN of the entry to modify.  It must not be {@code null}.
387       * @param  mods  The set of modifications to apply to the target entry.  It
388       *               must not be {@code null} or empty.  *
389       * @return  The result of processing the modify operation.
390       *
391       * @throws  LDAPException  If the server rejects the modify request, or if a
392       *                         problem is encountered while sending the request or
393       *                         reading the response.
394       */
395      LDAPResult modify(final String dn, final Modification... mods)
396           throws LDAPException;
397    
398    
399    
400      /**
401       * Applies the provided set of modifications to the specified entry.
402       *
403       * @param  dn    The DN of the entry to modify.  It must not be {@code null}.
404       * @param  mods  The set of modifications to apply to the target entry.  It
405       *               must not be {@code null} or empty.
406       *
407       * @return  The result of processing the modify operation.
408       *
409       * @throws  LDAPException  If the server rejects the modify request, or if a
410       *                         problem is encountered while sending the request or
411       *                         reading the response.
412       */
413      LDAPResult modify(final String dn, final List<Modification> mods)
414           throws LDAPException;
415    
416    
417    
418      /**
419       * Processes a modify request from the provided LDIF representation of the
420       * changes.
421       *
422       * @param  ldifModificationLines  The lines that comprise an LDIF
423       *                                representation of a modify change record.
424       *                                It must not be {@code null} or empty.
425       *
426       * @return  The result of processing the modify operation.
427       *
428       * @throws  LDIFException  If the provided set of lines cannot be parsed as an
429       *                         LDIF modify change record.
430       *
431       * @throws  LDAPException  If the server rejects the modify request, or if a
432       *                         problem is encountered while sending the request or
433       *                         reading the response.
434       *
435       */
436      LDAPResult modify(final String... ldifModificationLines)
437           throws LDIFException, LDAPException;
438    
439    
440    
441      /**
442       * Processes the provided modify request.
443       *
444       * @param  modifyRequest  The modify request to be processed.  It must not be
445       *                        {@code null}.
446       *
447       * @return  The result of processing the modify operation.
448       *
449       * @throws  LDAPException  If the server rejects the modify request, or if a
450       *                         problem is encountered while sending the request or
451       *                         reading the response.
452       */
453      LDAPResult modify(final ModifyRequest modifyRequest)
454           throws LDAPException;
455    
456    
457    
458      /**
459       * Processes the provided modify request.
460       *
461       * @param  modifyRequest  The modify request to be processed.  It must not be
462       *                        {@code null}.
463       *
464       * @return  The result of processing the modify operation.
465       *
466       * @throws  LDAPException  If the server rejects the modify request, or if a
467       *                         problem is encountered while sending the request or
468       *                         reading the response.
469       */
470      LDAPResult modify(final ReadOnlyModifyRequest modifyRequest)
471           throws LDAPException;
472    
473    
474    
475      /**
476       * Performs a modify DN operation with the provided information.
477       *
478       * @param  dn            The current DN for the entry to rename.  It must not
479       *                       be {@code null}.
480       * @param  newRDN        The new RDN to use for the entry.  It must not be
481       *                       {@code null}.
482       * @param  deleteOldRDN  Indicates whether to delete the current RDN value
483       *                       from the entry.
484       *
485       * @return  The result of processing the modify DN operation.
486       *
487       * @throws  LDAPException  If the server rejects the modify DN request, or if
488       *                         a problem is encountered while sending the request
489       *                         or reading the response.
490       */
491      LDAPResult modifyDN(final String dn, final String newRDN,
492                          final boolean deleteOldRDN)
493           throws LDAPException;
494    
495    
496    
497      /**
498       * Performs a modify DN operation with the provided information.
499       *
500       * @param  dn             The current DN for the entry to rename.  It must not
501       *                        be {@code null}.
502       * @param  newRDN         The new RDN to use for the entry.  It must not be
503       *                        {@code null}.
504       * @param  deleteOldRDN   Indicates whether to delete the current RDN value
505       *                        from the entry.
506       * @param  newSuperiorDN  The new superior DN for the entry.  It may be
507       *                        {@code null} if the entry is not to be moved below a
508       *                        new parent.
509       *
510       * @return  The result of processing the modify DN operation.
511       *
512       * @throws  LDAPException  If the server rejects the modify DN request, or if
513       *                         a problem is encountered while sending the request
514       *                         or reading the response.
515       */
516      LDAPResult modifyDN(final String dn, final String newRDN,
517                          final boolean deleteOldRDN, final String newSuperiorDN)
518           throws LDAPException;
519    
520    
521    
522      /**
523       * Processes the provided modify DN request.
524       *
525       * @param  modifyDNRequest  The modify DN request to be processed.  It must
526       *                          not be {@code null}.
527       *
528       * @return  The result of processing the modify DN operation.
529       *
530       * @throws  LDAPException  If the server rejects the modify DN request, or if
531       *                         a problem is encountered while sending the request
532       *                         or reading the response.
533       */
534      LDAPResult modifyDN(final ModifyDNRequest modifyDNRequest)
535           throws LDAPException;
536    
537    
538    
539      /**
540       * Processes the provided modify DN request.
541       *
542       * @param  modifyDNRequest  The modify DN request to be processed.  It must
543       *                          not be {@code null}.
544       *
545       * @return  The result of processing the modify DN operation.
546       *
547       * @throws  LDAPException  If the server rejects the modify DN request, or if
548       *                         a problem is encountered while sending the request
549       *                         or reading the response.
550       */
551      LDAPResult modifyDN(final ReadOnlyModifyDNRequest modifyDNRequest)
552           throws LDAPException;
553    
554    
555    
556      /**
557       * Processes a search operation with the provided information.  The search
558       * result entries and references will be collected internally and included in
559       * the {@code SearchResult} object that is returned.
560       * <BR><BR>
561       * Note that if the search does not complete successfully, an
562       * {@code LDAPSearchException} will be thrown  In some cases, one or more
563       * search result entries or references may have been returned before the
564       * failure response is received.  In this case, the
565       * {@code LDAPSearchException} methods like {@code getEntryCount},
566       * {@code getSearchEntries}, {@code getReferenceCount}, and
567       * {@code getSearchReferences} may be used to obtain information about those
568       * entries and references.
569       *
570       * @param  baseDN      The base DN for the search request.  It must not be
571       *                     {@code null}.
572       * @param  scope       The scope that specifies the range of entries that
573       *                     should be examined for the search.
574       * @param  filter      The string representation of the filter to use to
575       *                     identify matching entries.  It must not be
576       *                     {@code null}.
577       * @param  attributes  The set of attributes that should be returned in
578       *                     matching entries.  It may be {@code null} or empty if
579       *                     the default attribute set (all user attributes) is to
580       *                     be requested.
581       *
582       * @return  A search result object that provides information about the
583       *          processing of the search, including the set of matching entries
584       *          and search references returned by the server.
585       *
586       * @throws  LDAPSearchException  If the search does not complete successfully,
587       *                               or if a problem is encountered while parsing
588       *                               the provided filter string, sending the
589       *                               request, or reading the response.  If one
590       *                               or more entries or references were returned
591       *                               before the failure was encountered, then the
592       *                               {@code LDAPSearchException} object may be
593       *                               examined to obtain information about those
594       *                               entries and/or references.
595       */
596      SearchResult search(final String baseDN, final SearchScope scope,
597                          final String filter, final String... attributes)
598           throws LDAPSearchException;
599    
600    
601    
602      /**
603       * Processes a search operation with the provided information.  The search
604       * result entries and references will be collected internally and included in
605       * the {@code SearchResult} object that is returned.
606       * <BR><BR>
607       * Note that if the search does not complete successfully, an
608       * {@code LDAPSearchException} will be thrown  In some cases, one or more
609       * search result entries or references may have been returned before the
610       * failure response is received.  In this case, the
611       * {@code LDAPSearchException} methods like {@code getEntryCount},
612       * {@code getSearchEntries}, {@code getReferenceCount}, and
613       * {@code getSearchReferences} may be used to obtain information about those
614       * entries and references.
615       *
616       * @param  baseDN      The base DN for the search request.  It must not be
617       *                     {@code null}.
618       * @param  scope       The scope that specifies the range of entries that
619       *                     should be examined for the search.
620       * @param  filter      The filter to use to identify matching entries.  It
621       *                     must not be {@code null}.
622       * @param  attributes  The set of attributes that should be returned in
623       *                     matching entries.  It may be {@code null} or empty if
624       *                     the default attribute set (all user attributes) is to
625       *                     be requested.
626       *
627       * @return  A search result object that provides information about the
628       *          processing of the search, including the set of matching entries
629       *          and search references returned by the server.
630       *
631       * @throws  LDAPSearchException  If the search does not complete successfully,
632       *                               or if a problem is encountered while sending
633       *                               the request or reading the response.  If one
634       *                               or more entries or references were returned
635       *                               before the failure was encountered, then the
636       *                               {@code LDAPSearchException} object may be
637       *                               examined to obtain information about those
638       *                               entries and/or references.
639       */
640      SearchResult search(final String baseDN, final SearchScope scope,
641                          final Filter filter, final String... attributes)
642           throws LDAPSearchException;
643    
644    
645    
646      /**
647       * Processes a search operation with the provided information.
648       * <BR><BR>
649       * Note that if the search does not complete successfully, an
650       * {@code LDAPSearchException} will be thrown  In some cases, one or more
651       * search result entries or references may have been returned before the
652       * failure response is received.  In this case, the
653       * {@code LDAPSearchException} methods like {@code getEntryCount},
654       * {@code getSearchEntries}, {@code getReferenceCount}, and
655       * {@code getSearchReferences} may be used to obtain information about those
656       * entries and references (although if a search result listener was provided,
657       * then it will have been used to make any entries and references available,
658       * and they will not be available through the {@code getSearchEntries} and
659       * {@code getSearchReferences} methods).
660       *
661       * @param  searchResultListener  The search result listener that should be
662       *                               used to return results to the client.  It may
663       *                               be {@code null} if the search results should
664       *                               be collected internally and returned in the
665       *                               {@code SearchResult} object.
666       * @param  baseDN                The base DN for the search request.  It must
667       *                               not be {@code null}.
668       * @param  scope                 The scope that specifies the range of entries
669       *                               that should be examined for the search.
670       * @param  filter                The string representation of the filter to
671       *                               use to identify matching entries.  It must
672       *                               not be {@code null}.
673       * @param  attributes            The set of attributes that should be returned
674       *                               in matching entries.  It may be {@code null}
675       *                               or empty if the default attribute set (all
676       *                               user attributes) is to be requested.
677       *
678       * @return  A search result object that provides information about the
679       *          processing of the search, potentially including the set of
680       *          matching entries and search references returned by the server.
681       *
682       * @throws  LDAPSearchException  If the search does not complete successfully,
683       *                               or if a problem is encountered while parsing
684       *                               the provided filter string, sending the
685       *                               request, or reading the response.  If one
686       *                               or more entries or references were returned
687       *                               before the failure was encountered, then the
688       *                               {@code LDAPSearchException} object may be
689       *                               examined to obtain information about those
690       *                               entries and/or references.
691       */
692      SearchResult search(final SearchResultListener searchResultListener,
693                          final String baseDN, final SearchScope scope,
694                          final String filter, final String... attributes)
695           throws LDAPSearchException;
696    
697    
698    
699      /**
700       * Processes a search operation with the provided information.
701       * <BR><BR>
702       * Note that if the search does not complete successfully, an
703       * {@code LDAPSearchException} will be thrown  In some cases, one or more
704       * search result entries or references may have been returned before the
705       * failure response is received.  In this case, the
706       * {@code LDAPSearchException} methods like {@code getEntryCount},
707       * {@code getSearchEntries}, {@code getReferenceCount}, and
708       * {@code getSearchReferences} may be used to obtain information about those
709       * entries and references (although if a search result listener was provided,
710       * then it will have been used to make any entries and references available,
711       * and they will not be available through the {@code getSearchEntries} and
712       * {@code getSearchReferences} methods).
713       *
714       * @param  searchResultListener  The search result listener that should be
715       *                               used to return results to the client.  It may
716       *                               be {@code null} if the search results should
717       *                               be collected internally and returned in the
718       *                               {@code SearchResult} object.
719       * @param  baseDN                The base DN for the search request.  It must
720       *                               not be {@code null}.
721       * @param  scope                 The scope that specifies the range of entries
722       *                               that should be examined for the search.
723       * @param  filter                The filter to use to identify matching
724       *                               entries.  It must not be {@code null}.
725       * @param  attributes            The set of attributes that should be returned
726       *                               in matching entries.  It may be {@code null}
727       *                               or empty if the default attribute set (all
728       *                               user attributes) is to be requested.
729       *
730       * @return  A search result object that provides information about the
731       *          processing of the search, potentially including the set of
732       *          matching entries and search references returned by the server.
733       *
734       * @throws  LDAPSearchException  If the search does not complete successfully,
735       *                               or if a problem is encountered while sending
736       *                               the request or reading the response.  If one
737       *                               or more entries or references were returned
738       *                               before the failure was encountered, then the
739       *                               {@code LDAPSearchException} object may be
740       *                               examined to obtain information about those
741       *                               entries and/or references.
742       */
743      SearchResult search(final SearchResultListener searchResultListener,
744                          final String baseDN, final SearchScope scope,
745                          final Filter filter, final String... attributes)
746           throws LDAPSearchException;
747    
748    
749    
750      /**
751       * Processes a search operation with the provided information.  The search
752       * result entries and references will be collected internally and included in
753       * the {@code SearchResult} object that is returned.
754       * <BR><BR>
755       * Note that if the search does not complete successfully, an
756       * {@code LDAPSearchException} will be thrown  In some cases, one or more
757       * search result entries or references may have been returned before the
758       * failure response is received.  In this case, the
759       * {@code LDAPSearchException} methods like {@code getEntryCount},
760       * {@code getSearchEntries}, {@code getReferenceCount}, and
761       * {@code getSearchReferences} may be used to obtain information about those
762       * entries and references.
763       *
764       * @param  baseDN       The base DN for the search request.  It must not be
765       *                      {@code null}.
766       * @param  scope        The scope that specifies the range of entries that
767       *                      should be examined for the search.
768       * @param  derefPolicy  The dereference policy the server should use for any
769       *                      aliases encountered while processing the search.
770       * @param  sizeLimit    The maximum number of entries that the server should
771       *                      return for the search.  A value of zero indicates that
772       *                      there should be no limit.
773       * @param  timeLimit    The maximum length of time in seconds that the server
774       *                      should spend processing this search request.  A value
775       *                      of zero indicates that there should be no limit.
776       * @param  typesOnly    Indicates whether to return only attribute names in
777       *                      matching entries, or both attribute names and values.
778       * @param  filter       The string representation of the filter to use to
779       *                      identify matching entries.  It must not be
780       *                      {@code null}.
781       * @param  attributes   The set of attributes that should be returned in
782       *                      matching entries.  It may be {@code null} or empty if
783       *                      the default attribute set (all user attributes) is to
784       *                      be requested.
785       *
786       * @return  A search result object that provides information about the
787       *          processing of the search, including the set of matching entries
788       *          and search references returned by the server.
789       *
790       * @throws  LDAPSearchException  If the search does not complete successfully,
791       *                               or if a problem is encountered while parsing
792       *                               the provided filter string, sending the
793       *                               request, or reading the response.  If one
794       *                               or more entries or references were returned
795       *                               before the failure was encountered, then the
796       *                               {@code LDAPSearchException} object may be
797       *                               examined to obtain information about those
798       *                               entries and/or references.
799       */
800      SearchResult search(final String baseDN, final SearchScope scope,
801                          final DereferencePolicy derefPolicy, final int sizeLimit,
802                          final int timeLimit, final boolean typesOnly,
803                          final String filter, final String... attributes)
804           throws LDAPSearchException;
805    
806    
807    
808      /**
809       * Processes a search operation with the provided information.  The search
810       * result entries and references will be collected internally and included in
811       * the {@code SearchResult} object that is returned.
812       * <BR><BR>
813       * Note that if the search does not complete successfully, an
814       * {@code LDAPSearchException} will be thrown  In some cases, one or more
815       * search result entries or references may have been returned before the
816       * failure response is received.  In this case, the
817       * {@code LDAPSearchException} methods like {@code getEntryCount},
818       * {@code getSearchEntries}, {@code getReferenceCount}, and
819       * {@code getSearchReferences} may be used to obtain information about those
820       * entries and references.
821       *
822       * @param  baseDN       The base DN for the search request.  It must not be
823       *                      {@code null}.
824       * @param  scope        The scope that specifies the range of entries that
825       *                      should be examined for the search.
826       * @param  derefPolicy  The dereference policy the server should use for any
827       *                      aliases encountered while processing the search.
828       * @param  sizeLimit    The maximum number of entries that the server should
829       *                      return for the search.  A value of zero indicates that
830       *                      there should be no limit.
831       * @param  timeLimit    The maximum length of time in seconds that the server
832       *                      should spend processing this search request.  A value
833       *                      of zero indicates that there should be no limit.
834       * @param  typesOnly    Indicates whether to return only attribute names in
835       *                      matching entries, or both attribute names and values.
836       * @param  filter       The filter to use to identify matching entries.  It
837       *                      must not be {@code null}.
838       * @param  attributes   The set of attributes that should be returned in
839       *                      matching entries.  It may be {@code null} or empty if
840       *                      the default attribute set (all user attributes) is to
841       *                      be requested.
842       *
843       * @return  A search result object that provides information about the
844       *          processing of the search, including the set of matching entries
845       *          and search references returned by the server.
846       *
847       * @throws  LDAPSearchException  If the search does not complete successfully,
848       *                               or if a problem is encountered while sending
849       *                               the request or reading the response.  If one
850       *                               or more entries or references were returned
851       *                               before the failure was encountered, then the
852       *                               {@code LDAPSearchException} object may be
853       *                               examined to obtain information about those
854       *                               entries and/or references.
855       */
856      SearchResult search(final String baseDN, final SearchScope scope,
857                          final DereferencePolicy derefPolicy, final int sizeLimit,
858                          final int timeLimit, final boolean typesOnly,
859                          final Filter filter, final String... attributes)
860           throws LDAPSearchException;
861    
862    
863    
864      /**
865       * Processes a search operation with the provided information.
866       * <BR><BR>
867       * Note that if the search does not complete successfully, an
868       * {@code LDAPSearchException} will be thrown  In some cases, one or more
869       * search result entries or references may have been returned before the
870       * failure response is received.  In this case, the
871       * {@code LDAPSearchException} methods like {@code getEntryCount},
872       * {@code getSearchEntries}, {@code getReferenceCount}, and
873       * {@code getSearchReferences} may be used to obtain information about those
874       * entries and references (although if a search result listener was provided,
875       * then it will have been used to make any entries and references available,
876       * and they will not be available through the {@code getSearchEntries} and
877       * {@code getSearchReferences} methods).
878       *
879       * @param  searchResultListener  The search result listener that should be
880       *                               used to return results to the client.  It may
881       *                               be {@code null} if the search results should
882       *                               be collected internally and returned in the
883       *                               {@code SearchResult} object.
884       * @param  baseDN                The base DN for the search request.  It must
885       *                               not be {@code null}.
886       * @param  scope                 The scope that specifies the range of entries
887       *                               that should be examined for the search.
888       * @param  derefPolicy           The dereference policy the server should use
889       *                               for any aliases encountered while processing
890       *                               the search.
891       * @param  sizeLimit             The maximum number of entries that the server
892       *                               should return for the search.  A value of
893       *                               zero indicates that there should be no limit.
894       * @param  timeLimit             The maximum length of time in seconds that
895       *                               the server should spend processing this
896       *                               search request.  A value of zero indicates
897       *                               that there should be no limit.
898       * @param  typesOnly             Indicates whether to return only attribute
899       *                               names in matching entries, or both attribute
900       *                               names and values.
901       * @param  filter                The string representation of the filter to
902       *                               use to identify matching entries.  It must
903       *                               not be {@code null}.
904       * @param  attributes            The set of attributes that should be returned
905       *                               in matching entries.  It may be {@code null}
906       *                               or empty if the default attribute set (all
907       *                               user attributes) is to be requested.
908       *
909       * @return  A search result object that provides information about the
910       *          processing of the search, potentially including the set of
911       *          matching entries and search references returned by the server.
912       *
913       * @throws  LDAPSearchException  If the search does not complete successfully,
914       *                               or if a problem is encountered while parsing
915       *                               the provided filter string, sending the
916       *                               request, or reading the response.  If one
917       *                               or more entries or references were returned
918       *                               before the failure was encountered, then the
919       *                               {@code LDAPSearchException} object may be
920       *                               examined to obtain information about those
921       *                               entries and/or references.
922       */
923      SearchResult search(final SearchResultListener searchResultListener,
924                          final String baseDN, final SearchScope scope,
925                          final DereferencePolicy derefPolicy, final int sizeLimit,
926                          final int timeLimit, final boolean typesOnly,
927                          final String filter, final String... attributes)
928           throws LDAPSearchException;
929    
930    
931    
932      /**
933       * Processes a search operation with the provided information.
934       * <BR><BR>
935       * Note that if the search does not complete successfully, an
936       * {@code LDAPSearchException} will be thrown  In some cases, one or more
937       * search result entries or references may have been returned before the
938       * failure response is received.  In this case, the
939       * {@code LDAPSearchException} methods like {@code getEntryCount},
940       * {@code getSearchEntries}, {@code getReferenceCount}, and
941       * {@code getSearchReferences} may be used to obtain information about those
942       * entries and references (although if a search result listener was provided,
943       * then it will have been used to make any entries and references available,
944       * and they will not be available through the {@code getSearchEntries} and
945       * {@code getSearchReferences} methods).
946       *
947       * @param  searchResultListener  The search result listener that should be
948       *                               used to return results to the client.  It may
949       *                               be {@code null} if the search results should
950       *                               be collected internally and returned in the
951       *                               {@code SearchResult} object.
952       * @param  baseDN                The base DN for the search request.  It must
953       *                               not be {@code null}.
954       * @param  scope                 The scope that specifies the range of entries
955       *                               that should be examined for the search.
956       * @param  derefPolicy           The dereference policy the server should use
957       *                               for any aliases encountered while processing
958       *                               the search.
959       * @param  sizeLimit             The maximum number of entries that the server
960       *                               should return for the search.  A value of
961       *                               zero indicates that there should be no limit.
962       * @param  timeLimit             The maximum length of time in seconds that
963       *                               the server should spend processing this
964       *                               search request.  A value of zero indicates
965       *                               that there should be no limit.
966       * @param  typesOnly             Indicates whether to return only attribute
967       *                               names in matching entries, or both attribute
968       *                               names and values.
969       * @param  filter                The filter to use to identify matching
970       *                               entries.  It must not be {@code null}.
971       * @param  attributes            The set of attributes that should be returned
972       *                               in matching entries.  It may be {@code null}
973       *                               or empty if the default attribute set (all
974       *                               user attributes) is to be requested.
975       *
976       * @return  A search result object that provides information about the
977       *          processing of the search, potentially including the set of
978       *          matching entries and search references returned by the server.
979       *
980       * @throws  LDAPSearchException  If the search does not complete successfully,
981       *                               or if a problem is encountered while sending
982       *                               the request or reading the response.  If one
983       *                               or more entries or references were returned
984       *                               before the failure was encountered, then the
985       *                               {@code LDAPSearchException} object may be
986       *                               examined to obtain information about those
987       *                               entries and/or references.
988       */
989      SearchResult search(final SearchResultListener searchResultListener,
990                          final String baseDN, final SearchScope scope,
991                          final DereferencePolicy derefPolicy, final int sizeLimit,
992                          final int timeLimit, final boolean typesOnly,
993                          final Filter filter, final String... attributes)
994           throws LDAPSearchException;
995    
996    
997    
998      /**
999       * Processes the provided search request.
1000       * <BR><BR>
1001       * Note that if the search does not complete successfully, an
1002       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1003       * search result entries or references may have been returned before the
1004       * failure response is received.  In this case, the
1005       * {@code LDAPSearchException} methods like {@code getEntryCount},
1006       * {@code getSearchEntries}, {@code getReferenceCount}, and
1007       * {@code getSearchReferences} may be used to obtain information about those
1008       * entries and references (although if a search result listener was provided,
1009       * then it will have been used to make any entries and references available,
1010       * and they will not be available through the {@code getSearchEntries} and
1011       * {@code getSearchReferences} methods).
1012       *
1013       * @param  searchRequest  The search request to be processed.  It must not be
1014       *                        {@code null}.
1015       *
1016       * @return  A search result object that provides information about the
1017       *          processing of the search, potentially including the set of
1018       *          matching entries and search references returned by the server.
1019       *
1020       * @throws  LDAPSearchException  If the search does not complete successfully,
1021       *                               or if a problem is encountered while sending
1022       *                               the request or reading the response.  If one
1023       *                               or more entries or references were returned
1024       *                               before the failure was encountered, then the
1025       *                               {@code LDAPSearchException} object may be
1026       *                               examined to obtain information about those
1027       *                               entries and/or references.
1028       */
1029      SearchResult search(final SearchRequest searchRequest)
1030           throws LDAPSearchException;
1031    
1032    
1033    
1034      /**
1035       * Processes the provided search request.
1036       * <BR><BR>
1037       * Note that if the search does not complete successfully, an
1038       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1039       * search result entries or references may have been returned before the
1040       * failure response is received.  In this case, the
1041       * {@code LDAPSearchException} methods like {@code getEntryCount},
1042       * {@code getSearchEntries}, {@code getReferenceCount}, and
1043       * {@code getSearchReferences} may be used to obtain information about those
1044       * entries and references (although if a search result listener was provided,
1045       * then it will have been used to make any entries and references available,
1046       * and they will not be available through the {@code getSearchEntries} and
1047       * {@code getSearchReferences} methods).
1048       *
1049       * @param  searchRequest  The search request to be processed.  It must not be
1050       *                        {@code null}.
1051       *
1052       * @return  A search result object that provides information about the
1053       *          processing of the search, potentially including the set of
1054       *          matching entries and search references returned by the server.
1055       *
1056       * @throws  LDAPSearchException  If the search does not complete successfully,
1057       *                               or if a problem is encountered while sending
1058       *                               the request or reading the response.  If one
1059       *                               or more entries or references were returned
1060       *                               before the failure was encountered, then the
1061       *                               {@code LDAPSearchException} object may be
1062       *                               examined to obtain information about those
1063       *                               entries and/or references.
1064       */
1065      SearchResult search(final ReadOnlySearchRequest searchRequest)
1066           throws LDAPSearchException;
1067    
1068    
1069    
1070      /**
1071       * Processes a search operation with the provided information.  It is expected
1072       * that at most one entry will be returned from the search, and that no
1073       * additional content from the successful search result (e.g., diagnostic
1074       * message or response controls) are needed.
1075       * <BR><BR>
1076       * Note that if the search does not complete successfully, an
1077       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1078       * search result entries or references may have been returned before the
1079       * failure response is received.  In this case, the
1080       * {@code LDAPSearchException} methods like {@code getEntryCount},
1081       * {@code getSearchEntries}, {@code getReferenceCount}, and
1082       * {@code getSearchReferences} may be used to obtain information about those
1083       * entries and references.
1084       *
1085       * @param  baseDN      The base DN for the search request.  It must not be
1086       *                     {@code null}.
1087       * @param  scope       The scope that specifies the range of entries that
1088       *                     should be examined for the search.
1089       * @param  filter      The string representation of the filter to use to
1090       *                     identify matching entries.  It must not be
1091       *                     {@code null}.
1092       * @param  attributes  The set of attributes that should be returned in
1093       *                     matching entries.  It may be {@code null} or empty if
1094       *                     the default attribute set (all user attributes) is to
1095       *                     be requested.
1096       *
1097       * @return  The entry that was returned from the search, or {@code null} if no
1098       *          entry was returned or the base entry does not exist.
1099       *
1100       * @throws  LDAPSearchException  If the search does not complete successfully,
1101       *                               if more than a single entry is returned, or
1102       *                               if a problem is encountered while parsing the
1103       *                               provided filter string, sending the request,
1104       *                               or reading the response.  If one or more
1105       *                               entries or references were returned before
1106       *                               the failure was encountered, then the
1107       *                               {@code LDAPSearchException} object may be
1108       *                               examined to obtain information about those
1109       *                               entries and/or references.
1110       */
1111      SearchResultEntry searchForEntry(final String baseDN, final SearchScope scope,
1112                                       final String filter,
1113                                       final String... attributes)
1114           throws LDAPSearchException;
1115    
1116    
1117    
1118      /**
1119       * Processes a search operation with the provided information.  It is expected
1120       * that at most one entry will be returned from the search, and that no
1121       * additional content from the successful search result (e.g., diagnostic
1122       * message or response controls) are needed.
1123       * <BR><BR>
1124       * Note that if the search does not complete successfully, an
1125       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1126       * search result entries or references may have been returned before the
1127       * failure response is received.  In this case, the
1128       * {@code LDAPSearchException} methods like {@code getEntryCount},
1129       * {@code getSearchEntries}, {@code getReferenceCount}, and
1130       * {@code getSearchReferences} may be used to obtain information about those
1131       * entries and references.
1132       *
1133       * @param  baseDN      The base DN for the search request.  It must not be
1134       *                     {@code null}.
1135       * @param  scope       The scope that specifies the range of entries that
1136       *                     should be examined for the search.
1137       * @param  filter      The string representation of the filter to use to
1138       *                     identify matching entries.  It must not be
1139       *                     {@code null}.
1140       * @param  attributes  The set of attributes that should be returned in
1141       *                     matching entries.  It may be {@code null} or empty if
1142       *                     the default attribute set (all user attributes) is to
1143       *                     be requested.
1144       *
1145       * @return  The entry that was returned from the search, or {@code null} if no
1146       *          entry was returned or the base entry does not exist.
1147       *
1148       * @throws  LDAPSearchException  If the search does not complete successfully,
1149       *                               if more than a single entry is returned, or
1150       *                               if a problem is encountered while parsing the
1151       *                               provided filter string, sending the request,
1152       *                               or reading the response.  If one or more
1153       *                               entries or references were returned before
1154       *                               the failure was encountered, then the
1155       *                               {@code LDAPSearchException} object may be
1156       *                               examined to obtain information about those
1157       *                               entries and/or references.
1158       */
1159      SearchResultEntry searchForEntry(final String baseDN, final SearchScope scope,
1160                                       final Filter filter,
1161                                       final String... attributes)
1162           throws LDAPSearchException;
1163    
1164    
1165    
1166      /**
1167       * Processes a search operation with the provided information.  It is expected
1168       * that at most one entry will be returned from the search, and that no
1169       * additional content from the successful search result (e.g., diagnostic
1170       * message or response controls) are needed.
1171       * <BR><BR>
1172       * Note that if the search does not complete successfully, an
1173       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1174       * search result entries or references may have been returned before the
1175       * failure response is received.  In this case, the
1176       * {@code LDAPSearchException} methods like {@code getEntryCount},
1177       * {@code getSearchEntries}, {@code getReferenceCount}, and
1178       * {@code getSearchReferences} may be used to obtain information about those
1179       * entries and references.
1180       *
1181       * @param  baseDN       The base DN for the search request.  It must not be
1182       *                      {@code null}.
1183       * @param  scope        The scope that specifies the range of entries that
1184       *                      should be examined for the search.
1185       * @param  derefPolicy  The dereference policy the server should use for any
1186       *                      aliases encountered while processing the search.
1187       * @param  timeLimit    The maximum length of time in seconds that the server
1188       *                      should spend processing this search request.  A value
1189       *                      of zero indicates that there should be no limit.
1190       * @param  typesOnly    Indicates whether to return only attribute names in
1191       *                      matching entries, or both attribute names and values.
1192       * @param  filter       The string representation of the filter to use to
1193       *                      identify matching entries.  It must not be
1194       *                      {@code null}.
1195       * @param  attributes   The set of attributes that should be returned in
1196       *                      matching entries.  It may be {@code null} or empty if
1197       *                      the default attribute set (all user attributes) is to
1198       *                      be requested.
1199       *
1200       * @return  The entry that was returned from the search, or {@code null} if no
1201       *          entry was returned or the base entry does not exist.
1202       *
1203       * @throws  LDAPSearchException  If the search does not complete successfully,
1204       *                               if more than a single entry is returned, or
1205       *                               if a problem is encountered while parsing the
1206       *                               provided filter string, sending the request,
1207       *                               or reading the response.  If one or more
1208       *                               entries or references were returned before
1209       *                               the failure was encountered, then the
1210       *                               {@code LDAPSearchException} object may be
1211       *                               examined to obtain information about those
1212       *                               entries and/or references.
1213       */
1214      SearchResultEntry searchForEntry(final String baseDN, final SearchScope scope,
1215                                       final DereferencePolicy derefPolicy,
1216                                       final int timeLimit, final boolean typesOnly,
1217                                       final String filter,
1218                                       final String... attributes)
1219           throws LDAPSearchException;
1220    
1221    
1222    
1223      /**
1224       * Processes a search operation with the provided information.  It is expected
1225       * that at most one entry will be returned from the search, and that no
1226       * additional content from the successful search result (e.g., diagnostic
1227       * message or response controls) are needed.
1228       * <BR><BR>
1229       * Note that if the search does not complete successfully, an
1230       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1231       * search result entries or references may have been returned before the
1232       * failure response is received.  In this case, the
1233       * {@code LDAPSearchException} methods like {@code getEntryCount},
1234       * {@code getSearchEntries}, {@code getReferenceCount}, and
1235       * {@code getSearchReferences} may be used to obtain information about those
1236       * entries and references.
1237       *
1238       * @param  baseDN       The base DN for the search request.  It must not be
1239       *                      {@code null}.
1240       * @param  scope        The scope that specifies the range of entries that
1241       *                      should be examined for the search.
1242       * @param  derefPolicy  The dereference policy the server should use for any
1243       *                      aliases encountered while processing the search.
1244       * @param  timeLimit    The maximum length of time in seconds that the server
1245       *                      should spend processing this search request.  A value
1246       *                      of zero indicates that there should be no limit.
1247       * @param  typesOnly    Indicates whether to return only attribute names in
1248       *                      matching entries, or both attribute names and values.
1249       * @param  filter       The filter to use to identify matching entries.  It
1250       *                      must not be {@code null}.
1251       * @param  attributes   The set of attributes that should be returned in
1252       *                      matching entries.  It may be {@code null} or empty if
1253       *                      the default attribute set (all user attributes) is to
1254       *                      be requested.
1255       *
1256       * @return  The entry that was returned from the search, or {@code null} if no
1257       *          entry was returned or the base entry does not exist.
1258       *
1259       * @throws  LDAPSearchException  If the search does not complete successfully,
1260       *                               if more than a single entry is returned, or
1261       *                               if a problem is encountered while parsing the
1262       *                               provided filter string, sending the request,
1263       *                               or reading the response.  If one or more
1264       *                               entries or references were returned before
1265       *                               the failure was encountered, then the
1266       *                               {@code LDAPSearchException} object may be
1267       *                               examined to obtain information about those
1268       *                               entries and/or references.
1269       */
1270      SearchResultEntry searchForEntry(final String baseDN, final SearchScope scope,
1271                                       final DereferencePolicy derefPolicy,
1272                                       final int timeLimit, final boolean typesOnly,
1273                                       final Filter filter,
1274                                       final String... attributes)
1275           throws LDAPSearchException;
1276    
1277    
1278    
1279      /**
1280       * Processes the provided search request.  It is expected that at most one
1281       * entry will be returned from the search, and that no additional content from
1282       * the successful search result (e.g., diagnostic message or response
1283       * controls) are needed.
1284       * <BR><BR>
1285       * Note that if the search does not complete successfully, an
1286       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1287       * search result entries or references may have been returned before the
1288       * failure response is received.  In this case, the
1289       * {@code LDAPSearchException} methods like {@code getEntryCount},
1290       * {@code getSearchEntries}, {@code getReferenceCount}, and
1291       * {@code getSearchReferences} may be used to obtain information about those
1292       * entries and references.
1293       *
1294       * @param  searchRequest  The search request to be processed.  If it is
1295       *                        configured with a search result listener or a size
1296       *                        limit other than one, then the provided request will
1297       *                        be duplicated with the appropriate settings.
1298       *
1299       * @return  The entry that was returned from the search, or {@code null} if no
1300       *          entry was returned or the base entry does not exist.
1301       *
1302       * @throws  LDAPSearchException  If the search does not complete successfully,
1303       *                               if more than a single entry is returned, or
1304       *                               if a problem is encountered while parsing the
1305       *                               provided filter string, sending the request,
1306       *                               or reading the response.  If one or more
1307       *                               entries or references were returned before
1308       *                               the failure was encountered, then the
1309       *                               {@code LDAPSearchException} object may be
1310       *                               examined to obtain information about those
1311       *                               entries and/or references.
1312       */
1313      SearchResultEntry searchForEntry(final SearchRequest searchRequest)
1314           throws LDAPSearchException;
1315    
1316    
1317    
1318      /**
1319       * Processes the provided search request.  It is expected that at most one
1320       * entry will be returned from the search, and that no additional content from
1321       * the successful search result (e.g., diagnostic message or response
1322       * controls) are needed.
1323       * <BR><BR>
1324       * Note that if the search does not complete successfully, an
1325       * {@code LDAPSearchException} will be thrown  In some cases, one or more
1326       * search result entries or references may have been returned before the
1327       * failure response is received.  In this case, the
1328       * {@code LDAPSearchException} methods like {@code getEntryCount},
1329       * {@code getSearchEntries}, {@code getReferenceCount}, and
1330       * {@code getSearchReferences} may be used to obtain information about those
1331       * entries and references.
1332       *
1333       * @param  searchRequest  The search request to be processed.  If it is
1334       *                        configured with a search result listener or a size
1335       *                        limit other than one, then the provided request will
1336       *                        be duplicated with the appropriate settings.
1337       *
1338       * @return  The entry that was returned from the search, or {@code null} if no
1339       *          entry was returned or the base entry does not exist.
1340       *
1341       * @throws  LDAPSearchException  If the search does not complete successfully,
1342       *                               if more than a single entry is returned, or
1343       *                               if a problem is encountered while parsing the
1344       *                               provided filter string, sending the request,
1345       *                               or reading the response.  If one or more
1346       *                               entries or references were returned before
1347       *                               the failure was encountered, then the
1348       *                               {@code LDAPSearchException} object may be
1349       *                               examined to obtain information about those
1350       *                               entries and/or references.
1351       */
1352      SearchResultEntry searchForEntry(final ReadOnlySearchRequest searchRequest)
1353           throws LDAPSearchException;
1354    }