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