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