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