001/*
002 * Copyright 2007-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2018 Ping Identity Corporation
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(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(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(String dn, 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(String dn, 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(String dn, 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(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(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(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(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(String dn, String attributeName, String assertionValue)
276       throws LDAPException;
277
278
279
280  /**
281   * Processes the provided compare request.
282   *
283   * @param  compareRequest  The compare request to be processed.  It must not
284   *                         be {@code null}.
285   *
286   * @return  The result of processing the compare operation.
287   *
288   * @throws  LDAPException  If the server rejects the compare request, or if a
289   *                         problem is encountered while sending the request or
290   *                         reading the response.
291   */
292  CompareResult compare(CompareRequest compareRequest)
293       throws LDAPException;
294
295
296
297  /**
298   * Processes the provided compare request.
299   *
300   * @param  compareRequest  The compare request to be processed.  It must not
301   *                         be {@code null}.
302   *
303   * @return  The result of processing the compare operation.
304   *
305   * @throws  LDAPException  If the server rejects the compare request, or if a
306   *                         problem is encountered while sending the request or
307   *                         reading the response.
308   */
309  CompareResult compare(ReadOnlyCompareRequest compareRequest)
310       throws LDAPException;
311
312
313
314  /**
315   * Deletes the entry with the specified DN.
316   *
317   * @param  dn  The DN of the entry to delete.  It must not be {@code null}.
318   *
319   * @return  The result of processing the delete operation.
320   *
321   * @throws  LDAPException  If the server rejects the delete request, or if a
322   *                         problem is encountered while sending the request or
323   *                         reading the response.
324   */
325  LDAPResult delete(String dn)
326       throws LDAPException;
327
328
329
330  /**
331   * Processes the provided delete request.
332   *
333   * @param  deleteRequest  The delete request to be processed.  It must not be
334   *                        {@code null}.
335   *
336   * @return  The result of processing the delete operation.
337   *
338   * @throws  LDAPException  If the server rejects the delete request, or if a
339   *                         problem is encountered while sending the request or
340   *                         reading the response.
341   */
342  LDAPResult delete(DeleteRequest deleteRequest)
343       throws LDAPException;
344
345
346
347  /**
348   * Processes the provided delete request.
349   *
350   * @param  deleteRequest  The delete request to be processed.  It must not be
351   *                        {@code null}.
352   *
353   * @return  The result of processing the delete operation.
354   *
355   * @throws  LDAPException  If the server rejects the delete request, or if a
356   *                         problem is encountered while sending the request or
357   *                         reading the response.
358   */
359  LDAPResult delete(ReadOnlyDeleteRequest deleteRequest)
360       throws LDAPException;
361
362
363
364  /**
365   * Applies the provided modification to the specified entry.
366   *
367   * @param  dn   The DN of the entry to modify.  It must not be {@code null}.
368   * @param  mod  The modification to apply to the target entry.  It must not
369   *              be {@code null}.
370   *
371   * @return  The result of processing the modify operation.
372   *
373   * @throws  LDAPException  If the server rejects the modify request, or if a
374   *                         problem is encountered while sending the request or
375   *                         reading the response.
376   */
377  LDAPResult modify(String dn, Modification mod)
378       throws LDAPException;
379
380
381
382  /**
383   * Applies the provided set of modifications to the specified entry.
384   *
385   * @param  dn    The DN of the entry to modify.  It must not be {@code null}.
386   * @param  mods  The set of modifications to apply to the target entry.  It
387   *               must not be {@code null} or empty.  *
388   * @return  The result of processing the modify operation.
389   *
390   * @throws  LDAPException  If the server rejects the modify request, or if a
391   *                         problem is encountered while sending the request or
392   *                         reading the response.
393   */
394  LDAPResult modify(String dn, Modification... mods)
395       throws LDAPException;
396
397
398
399  /**
400   * Applies the provided set of modifications to the specified entry.
401   *
402   * @param  dn    The DN of the entry to modify.  It must not be {@code null}.
403   * @param  mods  The set of modifications to apply to the target entry.  It
404   *               must not be {@code null} or empty.
405   *
406   * @return  The result of processing the modify operation.
407   *
408   * @throws  LDAPException  If the server rejects the modify request, or if a
409   *                         problem is encountered while sending the request or
410   *                         reading the response.
411   */
412  LDAPResult modify(String dn, List<Modification> mods)
413       throws LDAPException;
414
415
416
417  /**
418   * Processes a modify request from the provided LDIF representation of the
419   * changes.
420   *
421   * @param  ldifModificationLines  The lines that comprise an LDIF
422   *                                representation of a modify change record.
423   *                                It must not be {@code null} or empty.
424   *
425   * @return  The result of processing the modify operation.
426   *
427   * @throws  LDIFException  If the provided set of lines cannot be parsed as an
428   *                         LDIF modify change record.
429   *
430   * @throws  LDAPException  If the server rejects the modify request, or if a
431   *                         problem is encountered while sending the request or
432   *                         reading the response.
433   *
434   */
435  LDAPResult modify(String... ldifModificationLines)
436       throws LDIFException, LDAPException;
437
438
439
440  /**
441   * Processes the provided modify request.
442   *
443   * @param  modifyRequest  The modify request to be processed.  It must not be
444   *                        {@code null}.
445   *
446   * @return  The result of processing the modify operation.
447   *
448   * @throws  LDAPException  If the server rejects the modify request, or if a
449   *                         problem is encountered while sending the request or
450   *                         reading the response.
451   */
452  LDAPResult modify(ModifyRequest modifyRequest)
453       throws LDAPException;
454
455
456
457  /**
458   * Processes the provided modify request.
459   *
460   * @param  modifyRequest  The modify request to be processed.  It must not be
461   *                        {@code null}.
462   *
463   * @return  The result of processing the modify operation.
464   *
465   * @throws  LDAPException  If the server rejects the modify request, or if a
466   *                         problem is encountered while sending the request or
467   *                         reading the response.
468   */
469  LDAPResult modify(ReadOnlyModifyRequest modifyRequest)
470       throws LDAPException;
471
472
473
474  /**
475   * Performs a modify DN operation with the provided information.
476   *
477   * @param  dn            The current DN for the entry to rename.  It must not
478   *                       be {@code null}.
479   * @param  newRDN        The new RDN to use for the entry.  It must not be
480   *                       {@code null}.
481   * @param  deleteOldRDN  Indicates whether to delete the current RDN value
482   *                       from the entry.
483   *
484   * @return  The result of processing the modify DN operation.
485   *
486   * @throws  LDAPException  If the server rejects the modify DN request, or if
487   *                         a problem is encountered while sending the request
488   *                         or reading the response.
489   */
490  LDAPResult modifyDN(String dn, String newRDN, boolean deleteOldRDN)
491       throws LDAPException;
492
493
494
495  /**
496   * Performs a modify DN operation with the provided information.
497   *
498   * @param  dn             The current DN for the entry to rename.  It must not
499   *                        be {@code null}.
500   * @param  newRDN         The new RDN to use for the entry.  It must not be
501   *                        {@code null}.
502   * @param  deleteOldRDN   Indicates whether to delete the current RDN value
503   *                        from the entry.
504   * @param  newSuperiorDN  The new superior DN for the entry.  It may be
505   *                        {@code null} if the entry is not to be moved below a
506   *                        new parent.
507   *
508   * @return  The result of processing the modify DN operation.
509   *
510   * @throws  LDAPException  If the server rejects the modify DN request, or if
511   *                         a problem is encountered while sending the request
512   *                         or reading the response.
513   */
514  LDAPResult modifyDN(String dn, String newRDN, boolean deleteOldRDN,
515                      String newSuperiorDN)
516       throws LDAPException;
517
518
519
520  /**
521   * Processes the provided modify DN request.
522   *
523   * @param  modifyDNRequest  The modify DN request to be processed.  It must
524   *                          not be {@code null}.
525   *
526   * @return  The result of processing the modify DN operation.
527   *
528   * @throws  LDAPException  If the server rejects the modify DN request, or if
529   *                         a problem is encountered while sending the request
530   *                         or reading the response.
531   */
532  LDAPResult modifyDN(ModifyDNRequest modifyDNRequest)
533       throws LDAPException;
534
535
536
537  /**
538   * Processes the provided modify DN request.
539   *
540   * @param  modifyDNRequest  The modify DN request to be processed.  It must
541   *                          not be {@code null}.
542   *
543   * @return  The result of processing the modify DN operation.
544   *
545   * @throws  LDAPException  If the server rejects the modify DN request, or if
546   *                         a problem is encountered while sending the request
547   *                         or reading the response.
548   */
549  LDAPResult modifyDN(ReadOnlyModifyDNRequest modifyDNRequest)
550       throws LDAPException;
551
552
553
554  /**
555   * Processes a search operation with the provided information.  The search
556   * result entries and references will be collected internally and included in
557   * the {@code SearchResult} object that is returned.
558   * <BR><BR>
559   * Note that if the search does not complete successfully, an
560   * {@code LDAPSearchException} will be thrown  In some cases, one or more
561   * search result entries or references may have been returned before the
562   * failure response is received.  In this case, the
563   * {@code LDAPSearchException} methods like {@code getEntryCount},
564   * {@code getSearchEntries}, {@code getReferenceCount}, and
565   * {@code getSearchReferences} may be used to obtain information about those
566   * entries and references.
567   *
568   * @param  baseDN      The base DN for the search request.  It must not be
569   *                     {@code null}.
570   * @param  scope       The scope that specifies the range of entries that
571   *                     should be examined for the search.
572   * @param  filter      The string representation of the filter to use to
573   *                     identify matching entries.  It must not be
574   *                     {@code null}.
575   * @param  attributes  The set of attributes that should be returned in
576   *                     matching entries.  It may be {@code null} or empty if
577   *                     the default attribute set (all user attributes) is to
578   *                     be requested.
579   *
580   * @return  A search result object that provides information about the
581   *          processing of the search, including the set of matching entries
582   *          and search references returned by the server.
583   *
584   * @throws  LDAPSearchException  If the search does not complete successfully,
585   *                               or if a problem is encountered while parsing
586   *                               the provided filter string, sending the
587   *                               request, or reading the response.  If one
588   *                               or more entries or references were returned
589   *                               before the failure was encountered, then the
590   *                               {@code LDAPSearchException} object may be
591   *                               examined to obtain information about those
592   *                               entries and/or references.
593   */
594  SearchResult search(String baseDN, SearchScope scope, String filter,
595                      String... attributes)
596       throws LDAPSearchException;
597
598
599
600  /**
601   * Processes a search operation with the provided information.  The search
602   * result entries and references will be collected internally and included in
603   * the {@code SearchResult} object that is returned.
604   * <BR><BR>
605   * Note that if the search does not complete successfully, an
606   * {@code LDAPSearchException} will be thrown  In some cases, one or more
607   * search result entries or references may have been returned before the
608   * failure response is received.  In this case, the
609   * {@code LDAPSearchException} methods like {@code getEntryCount},
610   * {@code getSearchEntries}, {@code getReferenceCount}, and
611   * {@code getSearchReferences} may be used to obtain information about those
612   * entries and references.
613   *
614   * @param  baseDN      The base DN for the search request.  It must not be
615   *                     {@code null}.
616   * @param  scope       The scope that specifies the range of entries that
617   *                     should be examined for the search.
618   * @param  filter      The filter to use to identify matching entries.  It
619   *                     must not be {@code null}.
620   * @param  attributes  The set of attributes that should be returned in
621   *                     matching entries.  It may be {@code null} or empty if
622   *                     the default attribute set (all user attributes) is to
623   *                     be requested.
624   *
625   * @return  A search result object that provides information about the
626   *          processing of the search, including the set of matching entries
627   *          and search references returned by the server.
628   *
629   * @throws  LDAPSearchException  If the search does not complete successfully,
630   *                               or if a problem is encountered while sending
631   *                               the request or reading the response.  If one
632   *                               or more entries or references were returned
633   *                               before the failure was encountered, then the
634   *                               {@code LDAPSearchException} object may be
635   *                               examined to obtain information about those
636   *                               entries and/or references.
637   */
638  SearchResult search(String baseDN, SearchScope scope, Filter filter,
639                      String... attributes)
640       throws LDAPSearchException;
641
642
643
644  /**
645   * Processes a search operation with the provided information.
646   * <BR><BR>
647   * Note that if the search does not complete successfully, an
648   * {@code LDAPSearchException} will be thrown  In some cases, one or more
649   * search result entries or references may have been returned before the
650   * failure response is received.  In this case, the
651   * {@code LDAPSearchException} methods like {@code getEntryCount},
652   * {@code getSearchEntries}, {@code getReferenceCount}, and
653   * {@code getSearchReferences} may be used to obtain information about those
654   * entries and references (although if a search result listener was provided,
655   * then it will have been used to make any entries and references available,
656   * and they will not be available through the {@code getSearchEntries} and
657   * {@code getSearchReferences} methods).
658   *
659   * @param  searchResultListener  The search result listener that should be
660   *                               used to return results to the client.  It may
661   *                               be {@code null} if the search results should
662   *                               be collected internally and returned in the
663   *                               {@code SearchResult} object.
664   * @param  baseDN                The base DN for the search request.  It must
665   *                               not be {@code null}.
666   * @param  scope                 The scope that specifies the range of entries
667   *                               that should be examined for the search.
668   * @param  filter                The string representation of the filter to
669   *                               use to identify matching entries.  It must
670   *                               not be {@code null}.
671   * @param  attributes            The set of attributes that should be returned
672   *                               in matching entries.  It may be {@code null}
673   *                               or empty if the default attribute set (all
674   *                               user attributes) is to be requested.
675   *
676   * @return  A search result object that provides information about the
677   *          processing of the search, potentially including the set of
678   *          matching entries and search references returned by the server.
679   *
680   * @throws  LDAPSearchException  If the search does not complete successfully,
681   *                               or if a problem is encountered while parsing
682   *                               the provided filter string, sending the
683   *                               request, or reading the response.  If one
684   *                               or more entries or references were returned
685   *                               before the failure was encountered, then the
686   *                               {@code LDAPSearchException} object may be
687   *                               examined to obtain information about those
688   *                               entries and/or references.
689   */
690  SearchResult search(SearchResultListener searchResultListener, String baseDN,
691                      SearchScope scope, String filter, String... attributes)
692       throws LDAPSearchException;
693
694
695
696  /**
697   * Processes a search operation with the provided information.
698   * <BR><BR>
699   * Note that if the search does not complete successfully, an
700   * {@code LDAPSearchException} will be thrown  In some cases, one or more
701   * search result entries or references may have been returned before the
702   * failure response is received.  In this case, the
703   * {@code LDAPSearchException} methods like {@code getEntryCount},
704   * {@code getSearchEntries}, {@code getReferenceCount}, and
705   * {@code getSearchReferences} may be used to obtain information about those
706   * entries and references (although if a search result listener was provided,
707   * then it will have been used to make any entries and references available,
708   * and they will not be available through the {@code getSearchEntries} and
709   * {@code getSearchReferences} methods).
710   *
711   * @param  searchResultListener  The search result listener that should be
712   *                               used to return results to the client.  It may
713   *                               be {@code null} if the search results should
714   *                               be collected internally and returned in the
715   *                               {@code SearchResult} object.
716   * @param  baseDN                The base DN for the search request.  It must
717   *                               not be {@code null}.
718   * @param  scope                 The scope that specifies the range of entries
719   *                               that should be examined for the search.
720   * @param  filter                The filter to use to identify matching
721   *                               entries.  It must not be {@code null}.
722   * @param  attributes            The set of attributes that should be returned
723   *                               in matching entries.  It may be {@code null}
724   *                               or empty if the default attribute set (all
725   *                               user attributes) is to be requested.
726   *
727   * @return  A search result object that provides information about the
728   *          processing of the search, potentially including the set of
729   *          matching entries and search references returned by the server.
730   *
731   * @throws  LDAPSearchException  If the search does not complete successfully,
732   *                               or if a problem is encountered while sending
733   *                               the request or reading the response.  If one
734   *                               or more entries or references were returned
735   *                               before the failure was encountered, then the
736   *                               {@code LDAPSearchException} object may be
737   *                               examined to obtain information about those
738   *                               entries and/or references.
739   */
740  SearchResult search(SearchResultListener searchResultListener, String baseDN,
741                      SearchScope scope, Filter filter, String... attributes)
742       throws LDAPSearchException;
743
744
745
746  /**
747   * Processes a search operation with the provided information.  The search
748   * result entries and references will be collected internally and included in
749   * the {@code SearchResult} object that is returned.
750   * <BR><BR>
751   * Note that if the search does not complete successfully, an
752   * {@code LDAPSearchException} will be thrown  In some cases, one or more
753   * search result entries or references may have been returned before the
754   * failure response is received.  In this case, the
755   * {@code LDAPSearchException} methods like {@code getEntryCount},
756   * {@code getSearchEntries}, {@code getReferenceCount}, and
757   * {@code getSearchReferences} may be used to obtain information about those
758   * entries and references.
759   *
760   * @param  baseDN       The base DN for the search request.  It must not be
761   *                      {@code null}.
762   * @param  scope        The scope that specifies the range of entries that
763   *                      should be examined for the search.
764   * @param  derefPolicy  The dereference policy the server should use for any
765   *                      aliases encountered while processing the search.
766   * @param  sizeLimit    The maximum number of entries that the server should
767   *                      return for the search.  A value of zero indicates that
768   *                      there should be no limit.
769   * @param  timeLimit    The maximum length of time in seconds that the server
770   *                      should spend processing this search request.  A value
771   *                      of zero indicates that there should be no limit.
772   * @param  typesOnly    Indicates whether to return only attribute names in
773   *                      matching entries, or both attribute names and values.
774   * @param  filter       The string representation of the filter to use to
775   *                      identify matching entries.  It must not be
776   *                      {@code null}.
777   * @param  attributes   The set of attributes that should be returned in
778   *                      matching entries.  It may be {@code null} or empty if
779   *                      the default attribute set (all user attributes) is to
780   *                      be requested.
781   *
782   * @return  A search result object that provides information about the
783   *          processing of the search, including the set of matching entries
784   *          and search references returned by the server.
785   *
786   * @throws  LDAPSearchException  If the search does not complete successfully,
787   *                               or if a problem is encountered while parsing
788   *                               the provided filter string, sending the
789   *                               request, or reading the response.  If one
790   *                               or more entries or references were returned
791   *                               before the failure was encountered, then the
792   *                               {@code LDAPSearchException} object may be
793   *                               examined to obtain information about those
794   *                               entries and/or references.
795   */
796  SearchResult search(String baseDN, SearchScope scope,
797                      DereferencePolicy derefPolicy, int sizeLimit,
798                      int timeLimit, boolean typesOnly, String filter,
799                      String... attributes)
800       throws LDAPSearchException;
801
802
803
804  /**
805   * Processes a search operation with the provided information.  The search
806   * result entries and references will be collected internally and included in
807   * the {@code SearchResult} object that is returned.
808   * <BR><BR>
809   * Note that if the search does not complete successfully, an
810   * {@code LDAPSearchException} will be thrown  In some cases, one or more
811   * search result entries or references may have been returned before the
812   * failure response is received.  In this case, the
813   * {@code LDAPSearchException} methods like {@code getEntryCount},
814   * {@code getSearchEntries}, {@code getReferenceCount}, and
815   * {@code getSearchReferences} may be used to obtain information about those
816   * entries and references.
817   *
818   * @param  baseDN       The base DN for the search request.  It must not be
819   *                      {@code null}.
820   * @param  scope        The scope that specifies the range of entries that
821   *                      should be examined for the search.
822   * @param  derefPolicy  The dereference policy the server should use for any
823   *                      aliases encountered while processing the search.
824   * @param  sizeLimit    The maximum number of entries that the server should
825   *                      return for the search.  A value of zero indicates that
826   *                      there should be no limit.
827   * @param  timeLimit    The maximum length of time in seconds that the server
828   *                      should spend processing this search request.  A value
829   *                      of zero indicates that there should be no limit.
830   * @param  typesOnly    Indicates whether to return only attribute names in
831   *                      matching entries, or both attribute names and values.
832   * @param  filter       The filter to use to identify matching entries.  It
833   *                      must not be {@code null}.
834   * @param  attributes   The set of attributes that should be returned in
835   *                      matching entries.  It may be {@code null} or empty if
836   *                      the default attribute set (all user attributes) is to
837   *                      be requested.
838   *
839   * @return  A search result object that provides information about the
840   *          processing of the search, including the set of matching entries
841   *          and search references returned by the server.
842   *
843   * @throws  LDAPSearchException  If the search does not complete successfully,
844   *                               or if a problem is encountered while sending
845   *                               the request or reading the response.  If one
846   *                               or more entries or references were returned
847   *                               before the failure was encountered, then the
848   *                               {@code LDAPSearchException} object may be
849   *                               examined to obtain information about those
850   *                               entries and/or references.
851   */
852  SearchResult search(String baseDN, SearchScope scope,
853                      DereferencePolicy derefPolicy, int sizeLimit,
854                      int timeLimit, boolean typesOnly, Filter filter,
855                      String... attributes)
856       throws LDAPSearchException;
857
858
859
860  /**
861   * Processes a search operation with the provided information.
862   * <BR><BR>
863   * Note that if the search does not complete successfully, an
864   * {@code LDAPSearchException} will be thrown  In some cases, one or more
865   * search result entries or references may have been returned before the
866   * failure response is received.  In this case, the
867   * {@code LDAPSearchException} methods like {@code getEntryCount},
868   * {@code getSearchEntries}, {@code getReferenceCount}, and
869   * {@code getSearchReferences} may be used to obtain information about those
870   * entries and references (although if a search result listener was provided,
871   * then it will have been used to make any entries and references available,
872   * and they will not be available through the {@code getSearchEntries} and
873   * {@code getSearchReferences} methods).
874   *
875   * @param  searchResultListener  The search result listener that should be
876   *                               used to return results to the client.  It may
877   *                               be {@code null} if the search results should
878   *                               be collected internally and returned in the
879   *                               {@code SearchResult} object.
880   * @param  baseDN                The base DN for the search request.  It must
881   *                               not be {@code null}.
882   * @param  scope                 The scope that specifies the range of entries
883   *                               that should be examined for the search.
884   * @param  derefPolicy           The dereference policy the server should use
885   *                               for any aliases encountered while processing
886   *                               the search.
887   * @param  sizeLimit             The maximum number of entries that the server
888   *                               should return for the search.  A value of
889   *                               zero indicates that there should be no limit.
890   * @param  timeLimit             The maximum length of time in seconds that
891   *                               the server should spend processing this
892   *                               search request.  A value of zero indicates
893   *                               that there should be no limit.
894   * @param  typesOnly             Indicates whether to return only attribute
895   *                               names in matching entries, or both attribute
896   *                               names and values.
897   * @param  filter                The string representation of the filter to
898   *                               use to identify matching entries.  It must
899   *                               not be {@code null}.
900   * @param  attributes            The set of attributes that should be returned
901   *                               in matching entries.  It may be {@code null}
902   *                               or empty if the default attribute set (all
903   *                               user attributes) is to be requested.
904   *
905   * @return  A search result object that provides information about the
906   *          processing of the search, potentially including the set of
907   *          matching entries and search references returned by the server.
908   *
909   * @throws  LDAPSearchException  If the search does not complete successfully,
910   *                               or if a problem is encountered while parsing
911   *                               the provided filter string, sending the
912   *                               request, or reading the response.  If one
913   *                               or more entries or references were returned
914   *                               before the failure was encountered, then the
915   *                               {@code LDAPSearchException} object may be
916   *                               examined to obtain information about those
917   *                               entries and/or references.
918   */
919  SearchResult search(SearchResultListener searchResultListener, String baseDN,
920                      SearchScope scope, DereferencePolicy derefPolicy,
921                      int sizeLimit, int timeLimit, boolean typesOnly,
922                      String filter, 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(SearchResultListener searchResultListener, String baseDN,
985                      SearchScope scope, DereferencePolicy derefPolicy,
986                      int sizeLimit, int timeLimit, boolean typesOnly,
987                      Filter filter, String... attributes)
988       throws LDAPSearchException;
989
990
991
992  /**
993   * Processes the provided search request.
994   * <BR><BR>
995   * Note that if the search does not complete successfully, an
996   * {@code LDAPSearchException} will be thrown  In some cases, one or more
997   * search result entries or references may have been returned before the
998   * failure response is received.  In this case, the
999   * {@code LDAPSearchException} methods like {@code getEntryCount},
1000   * {@code getSearchEntries}, {@code getReferenceCount}, and
1001   * {@code getSearchReferences} may be used to obtain information about those
1002   * entries and references (although if a search result listener was provided,
1003   * then it will have been used to make any entries and references available,
1004   * and they will not be available through the {@code getSearchEntries} and
1005   * {@code getSearchReferences} methods).
1006   *
1007   * @param  searchRequest  The search request to be processed.  It must not be
1008   *                        {@code null}.
1009   *
1010   * @return  A search result object that provides information about the
1011   *          processing of the search, potentially including the set of
1012   *          matching entries and search references returned by the server.
1013   *
1014   * @throws  LDAPSearchException  If the search does not complete successfully,
1015   *                               or if a problem is encountered while sending
1016   *                               the request or reading the response.  If one
1017   *                               or more entries or references were returned
1018   *                               before the failure was encountered, then the
1019   *                               {@code LDAPSearchException} object may be
1020   *                               examined to obtain information about those
1021   *                               entries and/or references.
1022   */
1023  SearchResult search(SearchRequest searchRequest)
1024       throws LDAPSearchException;
1025
1026
1027
1028  /**
1029   * Processes the provided search request.
1030   * <BR><BR>
1031   * Note that if the search does not complete successfully, an
1032   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1033   * search result entries or references may have been returned before the
1034   * failure response is received.  In this case, the
1035   * {@code LDAPSearchException} methods like {@code getEntryCount},
1036   * {@code getSearchEntries}, {@code getReferenceCount}, and
1037   * {@code getSearchReferences} may be used to obtain information about those
1038   * entries and references (although if a search result listener was provided,
1039   * then it will have been used to make any entries and references available,
1040   * and they will not be available through the {@code getSearchEntries} and
1041   * {@code getSearchReferences} methods).
1042   *
1043   * @param  searchRequest  The search request to be processed.  It must not be
1044   *                        {@code null}.
1045   *
1046   * @return  A search result object that provides information about the
1047   *          processing of the search, potentially including the set of
1048   *          matching entries and search references returned by the server.
1049   *
1050   * @throws  LDAPSearchException  If the search does not complete successfully,
1051   *                               or if a problem is encountered while sending
1052   *                               the request or reading the response.  If one
1053   *                               or more entries or references were returned
1054   *                               before the failure was encountered, then the
1055   *                               {@code LDAPSearchException} object may be
1056   *                               examined to obtain information about those
1057   *                               entries and/or references.
1058   */
1059  SearchResult search(ReadOnlySearchRequest searchRequest)
1060       throws LDAPSearchException;
1061
1062
1063
1064  /**
1065   * Processes a search operation with the provided information.  It is expected
1066   * that at most one entry will be returned from the search, and that no
1067   * additional content from the successful search result (e.g., diagnostic
1068   * message or response controls) are needed.
1069   * <BR><BR>
1070   * Note that if the search does not complete successfully, an
1071   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1072   * search result entries or references may have been returned before the
1073   * failure response is received.  In this case, the
1074   * {@code LDAPSearchException} methods like {@code getEntryCount},
1075   * {@code getSearchEntries}, {@code getReferenceCount}, and
1076   * {@code getSearchReferences} may be used to obtain information about those
1077   * entries and references.
1078   *
1079   * @param  baseDN      The base DN for the search request.  It must not be
1080   *                     {@code null}.
1081   * @param  scope       The scope that specifies the range of entries that
1082   *                     should be examined for the search.
1083   * @param  filter      The string representation of the filter to use to
1084   *                     identify matching entries.  It must not be
1085   *                     {@code null}.
1086   * @param  attributes  The set of attributes that should be returned in
1087   *                     matching entries.  It may be {@code null} or empty if
1088   *                     the default attribute set (all user attributes) is to
1089   *                     be requested.
1090   *
1091   * @return  The entry that was returned from the search, or {@code null} if no
1092   *          entry was returned or the base entry does not exist.
1093   *
1094   * @throws  LDAPSearchException  If the search does not complete successfully,
1095   *                               if more than a single entry is returned, or
1096   *                               if a problem is encountered while parsing the
1097   *                               provided filter string, sending the request,
1098   *                               or reading the response.  If one or more
1099   *                               entries or references were returned before
1100   *                               the failure was encountered, then the
1101   *                               {@code LDAPSearchException} object may be
1102   *                               examined to obtain information about those
1103   *                               entries and/or references.
1104   */
1105  SearchResultEntry searchForEntry(String baseDN, SearchScope scope,
1106                                   String filter, String... attributes)
1107       throws LDAPSearchException;
1108
1109
1110
1111  /**
1112   * Processes a search operation with the provided information.  It is expected
1113   * that at most one entry will be returned from the search, and that no
1114   * additional content from the successful search result (e.g., diagnostic
1115   * message or response controls) are needed.
1116   * <BR><BR>
1117   * Note that if the search does not complete successfully, an
1118   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1119   * search result entries or references may have been returned before the
1120   * failure response is received.  In this case, the
1121   * {@code LDAPSearchException} methods like {@code getEntryCount},
1122   * {@code getSearchEntries}, {@code getReferenceCount}, and
1123   * {@code getSearchReferences} may be used to obtain information about those
1124   * entries and references.
1125   *
1126   * @param  baseDN      The base DN for the search request.  It must not be
1127   *                     {@code null}.
1128   * @param  scope       The scope that specifies the range of entries that
1129   *                     should be examined for the search.
1130   * @param  filter      The string representation of the filter to use to
1131   *                     identify matching entries.  It must not be
1132   *                     {@code null}.
1133   * @param  attributes  The set of attributes that should be returned in
1134   *                     matching entries.  It may be {@code null} or empty if
1135   *                     the default attribute set (all user attributes) is to
1136   *                     be requested.
1137   *
1138   * @return  The entry that was returned from the search, or {@code null} if no
1139   *          entry was returned or the base entry does not exist.
1140   *
1141   * @throws  LDAPSearchException  If the search does not complete successfully,
1142   *                               if more than a single entry is returned, or
1143   *                               if a problem is encountered while parsing the
1144   *                               provided filter string, sending the request,
1145   *                               or reading the response.  If one or more
1146   *                               entries or references were returned before
1147   *                               the failure was encountered, then the
1148   *                               {@code LDAPSearchException} object may be
1149   *                               examined to obtain information about those
1150   *                               entries and/or references.
1151   */
1152  SearchResultEntry searchForEntry(String baseDN, SearchScope scope,
1153                                   Filter filter, String... attributes)
1154       throws LDAPSearchException;
1155
1156
1157
1158  /**
1159   * Processes a search operation with the provided information.  It is expected
1160   * that at most one entry will be returned from the search, and that no
1161   * additional content from the successful search result (e.g., diagnostic
1162   * message or response controls) are needed.
1163   * <BR><BR>
1164   * Note that if the search does not complete successfully, an
1165   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1166   * search result entries or references may have been returned before the
1167   * failure response is received.  In this case, the
1168   * {@code LDAPSearchException} methods like {@code getEntryCount},
1169   * {@code getSearchEntries}, {@code getReferenceCount}, and
1170   * {@code getSearchReferences} may be used to obtain information about those
1171   * entries and references.
1172   *
1173   * @param  baseDN       The base DN for the search request.  It must not be
1174   *                      {@code null}.
1175   * @param  scope        The scope that specifies the range of entries that
1176   *                      should be examined for the search.
1177   * @param  derefPolicy  The dereference policy the server should use for any
1178   *                      aliases encountered while processing the search.
1179   * @param  timeLimit    The maximum length of time in seconds that the server
1180   *                      should spend processing this search request.  A value
1181   *                      of zero indicates that there should be no limit.
1182   * @param  typesOnly    Indicates whether to return only attribute names in
1183   *                      matching entries, or both attribute names and values.
1184   * @param  filter       The string representation of the filter to use to
1185   *                      identify matching entries.  It must not be
1186   *                      {@code null}.
1187   * @param  attributes   The set of attributes that should be returned in
1188   *                      matching entries.  It may be {@code null} or empty if
1189   *                      the default attribute set (all user attributes) is to
1190   *                      be requested.
1191   *
1192   * @return  The entry that was returned from the search, or {@code null} if no
1193   *          entry was returned or the base entry does not exist.
1194   *
1195   * @throws  LDAPSearchException  If the search does not complete successfully,
1196   *                               if more than a single entry is returned, or
1197   *                               if a problem is encountered while parsing the
1198   *                               provided filter string, sending the request,
1199   *                               or reading the response.  If one or more
1200   *                               entries or references were returned before
1201   *                               the failure was encountered, then the
1202   *                               {@code LDAPSearchException} object may be
1203   *                               examined to obtain information about those
1204   *                               entries and/or references.
1205   */
1206  SearchResultEntry searchForEntry(String baseDN, SearchScope scope,
1207                                   DereferencePolicy derefPolicy, int timeLimit,
1208                                   boolean typesOnly, String filter,
1209                                   String... attributes)
1210       throws LDAPSearchException;
1211
1212
1213
1214  /**
1215   * Processes a search operation with the provided information.  It is expected
1216   * that at most one entry will be returned from the search, and that no
1217   * additional content from the successful search result (e.g., diagnostic
1218   * message or response controls) are needed.
1219   * <BR><BR>
1220   * Note that if the search does not complete successfully, an
1221   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1222   * search result entries or references may have been returned before the
1223   * failure response is received.  In this case, the
1224   * {@code LDAPSearchException} methods like {@code getEntryCount},
1225   * {@code getSearchEntries}, {@code getReferenceCount}, and
1226   * {@code getSearchReferences} may be used to obtain information about those
1227   * entries and references.
1228   *
1229   * @param  baseDN       The base DN for the search request.  It must not be
1230   *                      {@code null}.
1231   * @param  scope        The scope that specifies the range of entries that
1232   *                      should be examined for the search.
1233   * @param  derefPolicy  The dereference policy the server should use for any
1234   *                      aliases encountered while processing the search.
1235   * @param  timeLimit    The maximum length of time in seconds that the server
1236   *                      should spend processing this search request.  A value
1237   *                      of zero indicates that there should be no limit.
1238   * @param  typesOnly    Indicates whether to return only attribute names in
1239   *                      matching entries, or both attribute names and values.
1240   * @param  filter       The filter to use to identify matching entries.  It
1241   *                      must not be {@code null}.
1242   * @param  attributes   The set of attributes that should be returned in
1243   *                      matching entries.  It may be {@code null} or empty if
1244   *                      the default attribute set (all user attributes) is to
1245   *                      be requested.
1246   *
1247   * @return  The entry that was returned from the search, or {@code null} if no
1248   *          entry was returned or the base entry does not exist.
1249   *
1250   * @throws  LDAPSearchException  If the search does not complete successfully,
1251   *                               if more than a single entry is returned, or
1252   *                               if a problem is encountered while parsing the
1253   *                               provided filter string, sending the request,
1254   *                               or reading the response.  If one or more
1255   *                               entries or references were returned before
1256   *                               the failure was encountered, then the
1257   *                               {@code LDAPSearchException} object may be
1258   *                               examined to obtain information about those
1259   *                               entries and/or references.
1260   */
1261  SearchResultEntry searchForEntry(String baseDN, SearchScope scope,
1262                                   DereferencePolicy derefPolicy, int timeLimit,
1263                                   boolean typesOnly, Filter filter,
1264                                   String... attributes)
1265       throws LDAPSearchException;
1266
1267
1268
1269  /**
1270   * Processes the provided search request.  It is expected that at most one
1271   * entry will be returned from the search, and that no additional content from
1272   * the successful search result (e.g., diagnostic message or response
1273   * controls) are needed.
1274   * <BR><BR>
1275   * Note that if the search does not complete successfully, an
1276   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1277   * search result entries or references may have been returned before the
1278   * failure response is received.  In this case, the
1279   * {@code LDAPSearchException} methods like {@code getEntryCount},
1280   * {@code getSearchEntries}, {@code getReferenceCount}, and
1281   * {@code getSearchReferences} may be used to obtain information about those
1282   * entries and references.
1283   *
1284   * @param  searchRequest  The search request to be processed.  If it is
1285   *                        configured with a search result listener or a size
1286   *                        limit other than one, then the provided request will
1287   *                        be duplicated with the appropriate settings.
1288   *
1289   * @return  The entry that was returned from the search, or {@code null} if no
1290   *          entry was returned or the base entry does not exist.
1291   *
1292   * @throws  LDAPSearchException  If the search does not complete successfully,
1293   *                               if more than a single entry is returned, or
1294   *                               if a problem is encountered while parsing the
1295   *                               provided filter string, sending the request,
1296   *                               or reading the response.  If one or more
1297   *                               entries or references were returned before
1298   *                               the failure was encountered, then the
1299   *                               {@code LDAPSearchException} object may be
1300   *                               examined to obtain information about those
1301   *                               entries and/or references.
1302   */
1303  SearchResultEntry searchForEntry(SearchRequest searchRequest)
1304       throws LDAPSearchException;
1305
1306
1307
1308  /**
1309   * Processes the provided search request.  It is expected that at most one
1310   * entry will be returned from the search, and that no additional content from
1311   * the successful search result (e.g., diagnostic message or response
1312   * controls) are needed.
1313   * <BR><BR>
1314   * Note that if the search does not complete successfully, an
1315   * {@code LDAPSearchException} will be thrown  In some cases, one or more
1316   * search result entries or references may have been returned before the
1317   * failure response is received.  In this case, the
1318   * {@code LDAPSearchException} methods like {@code getEntryCount},
1319   * {@code getSearchEntries}, {@code getReferenceCount}, and
1320   * {@code getSearchReferences} may be used to obtain information about those
1321   * entries and references.
1322   *
1323   * @param  searchRequest  The search request to be processed.  If it is
1324   *                        configured with a search result listener or a size
1325   *                        limit other than one, then the provided request will
1326   *                        be duplicated with the appropriate settings.
1327   *
1328   * @return  The entry that was returned from the search, or {@code null} if no
1329   *          entry was returned or the base entry does not exist.
1330   *
1331   * @throws  LDAPSearchException  If the search does not complete successfully,
1332   *                               if more than a single entry is returned, or
1333   *                               if a problem is encountered while parsing the
1334   *                               provided filter string, sending the request,
1335   *                               or reading the response.  If one or more
1336   *                               entries or references were returned before
1337   *                               the failure was encountered, then the
1338   *                               {@code LDAPSearchException} object may be
1339   *                               examined to obtain information about those
1340   *                               entries and/or references.
1341   */
1342  SearchResultEntry searchForEntry(ReadOnlySearchRequest searchRequest)
1343       throws LDAPSearchException;
1344}