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