001/* 002 * Copyright 2007-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2014 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 */ 021package com.unboundid.ldap.sdk; 022 023 024 025import java.util.Collection; 026import java.util.List; 027 028import com.unboundid.ldap.sdk.schema.Schema; 029import com.unboundid.ldif.LDIFException; 030import com.unboundid.util.NotExtensible; 031import com.unboundid.util.ThreadSafety; 032import com.unboundid.util.ThreadSafetyLevel; 033 034 035 036/** 037 * This interface defines a set of methods that are available for objects that 038 * may be used to communicate with an LDAP directory server. This can be used 039 * to facilitate development of methods which can be used for either a single 040 * LDAP connection or an LDAP connection pool. 041 * <BR><BR> 042 * At present, all implementations provided by the LDAP SDK are at least mostly 043 * threadsafe and can be used to process multiple requests concurrently. 044 * However, this is not a hard requirement and it is conceivable that in the 045 * future a new implementation could be added which is not inherently 046 * threadsafe. It is recommended that code which requires thread safety either 047 * provide their own external synchronization or use one of the subclasses which 048 * explicitly provides thread safety rather than relying on this generic 049 * interface. 050 */ 051@NotExtensible() 052@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE) 053public interface LDAPInterface 054{ 055 /** 056 * Retrieves the directory server root DSE. 057 * 058 * @return The directory server root DSE, or {@code null} if it is not 059 * available. 060 * 061 * @throws LDAPException If a problem occurs while attempting to retrieve 062 * the server root DSE. 063 */ 064 RootDSE getRootDSE() 065 throws LDAPException; 066 067 068 069 /** 070 * Retrieves the directory server schema definitions, using the subschema 071 * subentry DN contained in the server's root DSE. For directory servers 072 * containing a single schema, this should be sufficient for all purposes. 073 * For servers with multiple schemas, it may be necessary to specify the DN 074 * of the target entry for which to obtain the associated schema. 075 * 076 * @return The directory server schema definitions, or {@code null} if the 077 * schema information could not be retrieved (e.g, the client does 078 * not have permission to read the server schema). 079 * 080 * @throws LDAPException If a problem occurs while attempting to retrieve 081 * the server schema. 082 */ 083 Schema getSchema() 084 throws LDAPException; 085 086 087 088 /** 089 * Retrieves the directory server schema definitions that govern the specified 090 * entry. The subschemaSubentry attribute will be retrieved from the target 091 * entry, and then the appropriate schema definitions will be loaded from the 092 * entry referenced by that attribute. This may be necessary to ensure 093 * correct behavior in servers that support multiple schemas. 094 * 095 * @param entryDN The DN of the entry for which to retrieve the associated 096 * schema definitions. It may be {@code null} or an empty 097 * string if the subschemaSubentry attribute should be 098 * retrieved from the server's root DSE. 099 * 100 * @return The directory server schema definitions, or {@code null} if the 101 * schema information could not be retrieved (e.g, the client does 102 * not have permission to read the server schema). 103 * 104 * @throws LDAPException If a problem occurs while attempting to retrieve 105 * the server schema. 106 */ 107 Schema getSchema(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}