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