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