001/*
002 * Copyright 2007-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2017 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 */
021package com.unboundid.ldap.sdk;
022
023
024
025import java.util.Collection;
026import java.util.List;
027
028import com.unboundid.ldap.sdk.schema.Schema;
029import com.unboundid.ldif.LDIFException;
030import com.unboundid.util.NotExtensible;
031import com.unboundid.util.ThreadSafety;
032import 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)
053public 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}