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. 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(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(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(String dn, 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(String dn, 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(String dn, 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(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(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(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(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(String dn, String attributeName, String assertionValue) 276 throws LDAPException; 277 278 279 280 /** 281 * Processes the provided compare request. 282 * 283 * @param compareRequest The compare request to be processed. It must not 284 * be {@code null}. 285 * 286 * @return The result of processing the compare operation. 287 * 288 * @throws LDAPException If the server rejects the compare request, or if a 289 * problem is encountered while sending the request or 290 * reading the response. 291 */ 292 CompareResult compare(CompareRequest compareRequest) 293 throws LDAPException; 294 295 296 297 /** 298 * Processes the provided compare request. 299 * 300 * @param compareRequest The compare request to be processed. It must not 301 * be {@code null}. 302 * 303 * @return The result of processing the compare operation. 304 * 305 * @throws LDAPException If the server rejects the compare request, or if a 306 * problem is encountered while sending the request or 307 * reading the response. 308 */ 309 CompareResult compare(ReadOnlyCompareRequest compareRequest) 310 throws LDAPException; 311 312 313 314 /** 315 * Deletes the entry with the specified DN. 316 * 317 * @param dn The DN of the entry to delete. It must not be {@code null}. 318 * 319 * @return The result of processing the delete operation. 320 * 321 * @throws LDAPException If the server rejects the delete request, or if a 322 * problem is encountered while sending the request or 323 * reading the response. 324 */ 325 LDAPResult delete(String dn) 326 throws LDAPException; 327 328 329 330 /** 331 * Processes the provided delete request. 332 * 333 * @param deleteRequest The delete request to be processed. It must not be 334 * {@code null}. 335 * 336 * @return The result of processing the delete operation. 337 * 338 * @throws LDAPException If the server rejects the delete request, or if a 339 * problem is encountered while sending the request or 340 * reading the response. 341 */ 342 LDAPResult delete(DeleteRequest deleteRequest) 343 throws LDAPException; 344 345 346 347 /** 348 * Processes the provided delete request. 349 * 350 * @param deleteRequest The delete request to be processed. It must not be 351 * {@code null}. 352 * 353 * @return The result of processing the delete operation. 354 * 355 * @throws LDAPException If the server rejects the delete request, or if a 356 * problem is encountered while sending the request or 357 * reading the response. 358 */ 359 LDAPResult delete(ReadOnlyDeleteRequest deleteRequest) 360 throws LDAPException; 361 362 363 364 /** 365 * Applies the provided modification to the specified entry. 366 * 367 * @param dn The DN of the entry to modify. It must not be {@code null}. 368 * @param mod The modification to apply to the target entry. It must not 369 * be {@code null}. 370 * 371 * @return The result of processing the modify operation. 372 * 373 * @throws LDAPException If the server rejects the modify request, or if a 374 * problem is encountered while sending the request or 375 * reading the response. 376 */ 377 LDAPResult modify(String dn, Modification mod) 378 throws LDAPException; 379 380 381 382 /** 383 * Applies the provided set of modifications to the specified entry. 384 * 385 * @param dn The DN of the entry to modify. It must not be {@code null}. 386 * @param mods The set of modifications to apply to the target entry. It 387 * must not be {@code null} or empty. * 388 * @return The result of processing the modify operation. 389 * 390 * @throws LDAPException If the server rejects the modify request, or if a 391 * problem is encountered while sending the request or 392 * reading the response. 393 */ 394 LDAPResult modify(String dn, Modification... mods) 395 throws LDAPException; 396 397 398 399 /** 400 * Applies the provided set of modifications to the specified entry. 401 * 402 * @param dn The DN of the entry to modify. It must not be {@code null}. 403 * @param mods The set of modifications to apply to the target entry. It 404 * must not be {@code null} or empty. 405 * 406 * @return The result of processing the modify operation. 407 * 408 * @throws LDAPException If the server rejects the modify request, or if a 409 * problem is encountered while sending the request or 410 * reading the response. 411 */ 412 LDAPResult modify(String dn, List<Modification> mods) 413 throws LDAPException; 414 415 416 417 /** 418 * Processes a modify request from the provided LDIF representation of the 419 * changes. 420 * 421 * @param ldifModificationLines The lines that comprise an LDIF 422 * representation of a modify change record. 423 * It must not be {@code null} or empty. 424 * 425 * @return The result of processing the modify operation. 426 * 427 * @throws LDIFException If the provided set of lines cannot be parsed as an 428 * LDIF modify change record. 429 * 430 * @throws LDAPException If the server rejects the modify request, or if a 431 * problem is encountered while sending the request or 432 * reading the response. 433 * 434 */ 435 LDAPResult modify(String... ldifModificationLines) 436 throws LDIFException, LDAPException; 437 438 439 440 /** 441 * Processes the provided modify request. 442 * 443 * @param modifyRequest The modify request to be processed. It must not be 444 * {@code null}. 445 * 446 * @return The result of processing the modify operation. 447 * 448 * @throws LDAPException If the server rejects the modify request, or if a 449 * problem is encountered while sending the request or 450 * reading the response. 451 */ 452 LDAPResult modify(ModifyRequest modifyRequest) 453 throws LDAPException; 454 455 456 457 /** 458 * Processes the provided modify request. 459 * 460 * @param modifyRequest The modify request to be processed. It must not be 461 * {@code null}. 462 * 463 * @return The result of processing the modify operation. 464 * 465 * @throws LDAPException If the server rejects the modify request, or if a 466 * problem is encountered while sending the request or 467 * reading the response. 468 */ 469 LDAPResult modify(ReadOnlyModifyRequest modifyRequest) 470 throws LDAPException; 471 472 473 474 /** 475 * Performs a modify DN operation with the provided information. 476 * 477 * @param dn The current DN for the entry to rename. It must not 478 * be {@code null}. 479 * @param newRDN The new RDN to use for the entry. It must not be 480 * {@code null}. 481 * @param deleteOldRDN Indicates whether to delete the current RDN value 482 * from the entry. 483 * 484 * @return The result of processing the modify DN operation. 485 * 486 * @throws LDAPException If the server rejects the modify DN request, or if 487 * a problem is encountered while sending the request 488 * or reading the response. 489 */ 490 LDAPResult modifyDN(String dn, String newRDN, boolean deleteOldRDN) 491 throws LDAPException; 492 493 494 495 /** 496 * Performs a modify DN operation with the provided information. 497 * 498 * @param dn The current DN for the entry to rename. It must not 499 * be {@code null}. 500 * @param newRDN The new RDN to use for the entry. It must not be 501 * {@code null}. 502 * @param deleteOldRDN Indicates whether to delete the current RDN value 503 * from the entry. 504 * @param newSuperiorDN The new superior DN for the entry. It may be 505 * {@code null} if the entry is not to be moved below a 506 * new parent. 507 * 508 * @return The result of processing the modify DN operation. 509 * 510 * @throws LDAPException If the server rejects the modify DN request, or if 511 * a problem is encountered while sending the request 512 * or reading the response. 513 */ 514 LDAPResult modifyDN(String dn, String newRDN, boolean deleteOldRDN, 515 String newSuperiorDN) 516 throws LDAPException; 517 518 519 520 /** 521 * Processes the provided modify DN request. 522 * 523 * @param modifyDNRequest The modify DN request to be processed. It must 524 * not be {@code null}. 525 * 526 * @return The result of processing the modify DN operation. 527 * 528 * @throws LDAPException If the server rejects the modify DN request, or if 529 * a problem is encountered while sending the request 530 * or reading the response. 531 */ 532 LDAPResult modifyDN(ModifyDNRequest modifyDNRequest) 533 throws LDAPException; 534 535 536 537 /** 538 * Processes the provided modify DN request. 539 * 540 * @param modifyDNRequest The modify DN request to be processed. It must 541 * not be {@code null}. 542 * 543 * @return The result of processing the modify DN operation. 544 * 545 * @throws LDAPException If the server rejects the modify DN request, or if 546 * a problem is encountered while sending the request 547 * or reading the response. 548 */ 549 LDAPResult modifyDN(ReadOnlyModifyDNRequest modifyDNRequest) 550 throws LDAPException; 551 552 553 554 /** 555 * Processes a search operation with the provided information. The search 556 * result entries and references will be collected internally and included in 557 * the {@code SearchResult} object that is returned. 558 * <BR><BR> 559 * Note that if the search does not complete successfully, an 560 * {@code LDAPSearchException} will be thrown In some cases, one or more 561 * search result entries or references may have been returned before the 562 * failure response is received. In this case, the 563 * {@code LDAPSearchException} methods like {@code getEntryCount}, 564 * {@code getSearchEntries}, {@code getReferenceCount}, and 565 * {@code getSearchReferences} may be used to obtain information about those 566 * entries and references. 567 * 568 * @param baseDN The base DN for the search request. It must not be 569 * {@code null}. 570 * @param scope The scope that specifies the range of entries that 571 * should be examined for the search. 572 * @param filter The string representation of the filter to use to 573 * identify matching entries. It must not be 574 * {@code null}. 575 * @param attributes The set of attributes that should be returned in 576 * matching entries. It may be {@code null} or empty if 577 * the default attribute set (all user attributes) is to 578 * be requested. 579 * 580 * @return A search result object that provides information about the 581 * processing of the search, including the set of matching entries 582 * and search references returned by the server. 583 * 584 * @throws LDAPSearchException If the search does not complete successfully, 585 * or if a problem is encountered while parsing 586 * the provided filter string, sending the 587 * request, or reading the response. If one 588 * or more entries or references were returned 589 * before the failure was encountered, then the 590 * {@code LDAPSearchException} object may be 591 * examined to obtain information about those 592 * entries and/or references. 593 */ 594 SearchResult search(String baseDN, SearchScope scope, String filter, 595 String... attributes) 596 throws LDAPSearchException; 597 598 599 600 /** 601 * Processes a search operation with the provided information. The search 602 * result entries and references will be collected internally and included in 603 * the {@code SearchResult} object that is returned. 604 * <BR><BR> 605 * Note that if the search does not complete successfully, an 606 * {@code LDAPSearchException} will be thrown In some cases, one or more 607 * search result entries or references may have been returned before the 608 * failure response is received. In this case, the 609 * {@code LDAPSearchException} methods like {@code getEntryCount}, 610 * {@code getSearchEntries}, {@code getReferenceCount}, and 611 * {@code getSearchReferences} may be used to obtain information about those 612 * entries and references. 613 * 614 * @param baseDN The base DN for the search request. It must not be 615 * {@code null}. 616 * @param scope The scope that specifies the range of entries that 617 * should be examined for the search. 618 * @param filter The filter to use to identify matching entries. It 619 * must not be {@code null}. 620 * @param attributes The set of attributes that should be returned in 621 * matching entries. It may be {@code null} or empty if 622 * the default attribute set (all user attributes) is to 623 * be requested. 624 * 625 * @return A search result object that provides information about the 626 * processing of the search, including the set of matching entries 627 * and search references returned by the server. 628 * 629 * @throws LDAPSearchException If the search does not complete successfully, 630 * or if a problem is encountered while sending 631 * the request or reading the response. If one 632 * or more entries or references were returned 633 * before the failure was encountered, then the 634 * {@code LDAPSearchException} object may be 635 * examined to obtain information about those 636 * entries and/or references. 637 */ 638 SearchResult search(String baseDN, SearchScope scope, Filter filter, 639 String... attributes) 640 throws LDAPSearchException; 641 642 643 644 /** 645 * Processes a search operation with the provided information. 646 * <BR><BR> 647 * Note that if the search does not complete successfully, an 648 * {@code LDAPSearchException} will be thrown In some cases, one or more 649 * search result entries or references may have been returned before the 650 * failure response is received. In this case, the 651 * {@code LDAPSearchException} methods like {@code getEntryCount}, 652 * {@code getSearchEntries}, {@code getReferenceCount}, and 653 * {@code getSearchReferences} may be used to obtain information about those 654 * entries and references (although if a search result listener was provided, 655 * then it will have been used to make any entries and references available, 656 * and they will not be available through the {@code getSearchEntries} and 657 * {@code getSearchReferences} methods). 658 * 659 * @param searchResultListener The search result listener that should be 660 * used to return results to the client. It may 661 * be {@code null} if the search results should 662 * be collected internally and returned in the 663 * {@code SearchResult} object. 664 * @param baseDN The base DN for the search request. It must 665 * not be {@code null}. 666 * @param scope The scope that specifies the range of entries 667 * that should be examined for the search. 668 * @param filter The string representation of the filter to 669 * use to identify matching entries. It must 670 * not be {@code null}. 671 * @param attributes The set of attributes that should be returned 672 * in matching entries. It may be {@code null} 673 * or empty if the default attribute set (all 674 * user attributes) is to be requested. 675 * 676 * @return A search result object that provides information about the 677 * processing of the search, potentially including the set of 678 * matching entries and search references returned by the server. 679 * 680 * @throws LDAPSearchException If the search does not complete successfully, 681 * or if a problem is encountered while parsing 682 * the provided filter string, sending the 683 * request, or reading the response. If one 684 * or more entries or references were returned 685 * before the failure was encountered, then the 686 * {@code LDAPSearchException} object may be 687 * examined to obtain information about those 688 * entries and/or references. 689 */ 690 SearchResult search(SearchResultListener searchResultListener, String baseDN, 691 SearchScope scope, String filter, String... attributes) 692 throws LDAPSearchException; 693 694 695 696 /** 697 * Processes a search operation with the provided information. 698 * <BR><BR> 699 * Note that if the search does not complete successfully, an 700 * {@code LDAPSearchException} will be thrown In some cases, one or more 701 * search result entries or references may have been returned before the 702 * failure response is received. In this case, the 703 * {@code LDAPSearchException} methods like {@code getEntryCount}, 704 * {@code getSearchEntries}, {@code getReferenceCount}, and 705 * {@code getSearchReferences} may be used to obtain information about those 706 * entries and references (although if a search result listener was provided, 707 * then it will have been used to make any entries and references available, 708 * and they will not be available through the {@code getSearchEntries} and 709 * {@code getSearchReferences} methods). 710 * 711 * @param searchResultListener The search result listener that should be 712 * used to return results to the client. It may 713 * be {@code null} if the search results should 714 * be collected internally and returned in the 715 * {@code SearchResult} object. 716 * @param baseDN The base DN for the search request. It must 717 * not be {@code null}. 718 * @param scope The scope that specifies the range of entries 719 * that should be examined for the search. 720 * @param filter The filter to use to identify matching 721 * entries. It must not be {@code null}. 722 * @param attributes The set of attributes that should be returned 723 * in matching entries. It may be {@code null} 724 * or empty if the default attribute set (all 725 * user attributes) is to be requested. 726 * 727 * @return A search result object that provides information about the 728 * processing of the search, potentially including the set of 729 * matching entries and search references returned by the server. 730 * 731 * @throws LDAPSearchException If the search does not complete successfully, 732 * or if a problem is encountered while sending 733 * the request or reading the response. If one 734 * or more entries or references were returned 735 * before the failure was encountered, then the 736 * {@code LDAPSearchException} object may be 737 * examined to obtain information about those 738 * entries and/or references. 739 */ 740 SearchResult search(SearchResultListener searchResultListener, String baseDN, 741 SearchScope scope, Filter filter, String... attributes) 742 throws LDAPSearchException; 743 744 745 746 /** 747 * Processes a search operation with the provided information. The search 748 * result entries and references will be collected internally and included in 749 * the {@code SearchResult} object that is returned. 750 * <BR><BR> 751 * Note that if the search does not complete successfully, an 752 * {@code LDAPSearchException} will be thrown In some cases, one or more 753 * search result entries or references may have been returned before the 754 * failure response is received. In this case, the 755 * {@code LDAPSearchException} methods like {@code getEntryCount}, 756 * {@code getSearchEntries}, {@code getReferenceCount}, and 757 * {@code getSearchReferences} may be used to obtain information about those 758 * entries and references. 759 * 760 * @param baseDN The base DN for the search request. It must not be 761 * {@code null}. 762 * @param scope The scope that specifies the range of entries that 763 * should be examined for the search. 764 * @param derefPolicy The dereference policy the server should use for any 765 * aliases encountered while processing the search. 766 * @param sizeLimit The maximum number of entries that the server should 767 * return for the search. A value of zero indicates that 768 * there should be no limit. 769 * @param timeLimit The maximum length of time in seconds that the server 770 * should spend processing this search request. A value 771 * of zero indicates that there should be no limit. 772 * @param typesOnly Indicates whether to return only attribute names in 773 * matching entries, or both attribute names and values. 774 * @param filter The string representation of the filter to use to 775 * identify matching entries. It must not be 776 * {@code null}. 777 * @param attributes The set of attributes that should be returned in 778 * matching entries. It may be {@code null} or empty if 779 * the default attribute set (all user attributes) is to 780 * be requested. 781 * 782 * @return A search result object that provides information about the 783 * processing of the search, including the set of matching entries 784 * and search references returned by the server. 785 * 786 * @throws LDAPSearchException If the search does not complete successfully, 787 * or if a problem is encountered while parsing 788 * the provided filter string, sending the 789 * request, or reading the response. If one 790 * or more entries or references were returned 791 * before the failure was encountered, then the 792 * {@code LDAPSearchException} object may be 793 * examined to obtain information about those 794 * entries and/or references. 795 */ 796 SearchResult search(String baseDN, SearchScope scope, 797 DereferencePolicy derefPolicy, int sizeLimit, 798 int timeLimit, boolean typesOnly, String filter, 799 String... attributes) 800 throws LDAPSearchException; 801 802 803 804 /** 805 * Processes a search operation with the provided information. The search 806 * result entries and references will be collected internally and included in 807 * the {@code SearchResult} object that is returned. 808 * <BR><BR> 809 * Note that if the search does not complete successfully, an 810 * {@code LDAPSearchException} will be thrown In some cases, one or more 811 * search result entries or references may have been returned before the 812 * failure response is received. In this case, the 813 * {@code LDAPSearchException} methods like {@code getEntryCount}, 814 * {@code getSearchEntries}, {@code getReferenceCount}, and 815 * {@code getSearchReferences} may be used to obtain information about those 816 * entries and references. 817 * 818 * @param baseDN The base DN for the search request. It must not be 819 * {@code null}. 820 * @param scope The scope that specifies the range of entries that 821 * should be examined for the search. 822 * @param derefPolicy The dereference policy the server should use for any 823 * aliases encountered while processing the search. 824 * @param sizeLimit The maximum number of entries that the server should 825 * return for the search. A value of zero indicates that 826 * there should be no limit. 827 * @param timeLimit The maximum length of time in seconds that the server 828 * should spend processing this search request. A value 829 * of zero indicates that there should be no limit. 830 * @param typesOnly Indicates whether to return only attribute names in 831 * matching entries, or both attribute names and values. 832 * @param filter The filter to use to identify matching entries. It 833 * must not be {@code null}. 834 * @param attributes The set of attributes that should be returned in 835 * matching entries. It may be {@code null} or empty if 836 * the default attribute set (all user attributes) is to 837 * be requested. 838 * 839 * @return A search result object that provides information about the 840 * processing of the search, including the set of matching entries 841 * and search references returned by the server. 842 * 843 * @throws LDAPSearchException If the search does not complete successfully, 844 * or if a problem is encountered while sending 845 * the request or reading the response. If one 846 * or more entries or references were returned 847 * before the failure was encountered, then the 848 * {@code LDAPSearchException} object may be 849 * examined to obtain information about those 850 * entries and/or references. 851 */ 852 SearchResult search(String baseDN, SearchScope scope, 853 DereferencePolicy derefPolicy, int sizeLimit, 854 int timeLimit, boolean typesOnly, Filter filter, 855 String... attributes) 856 throws LDAPSearchException; 857 858 859 860 /** 861 * Processes a search operation with the provided information. 862 * <BR><BR> 863 * Note that if the search does not complete successfully, an 864 * {@code LDAPSearchException} will be thrown In some cases, one or more 865 * search result entries or references may have been returned before the 866 * failure response is received. In this case, the 867 * {@code LDAPSearchException} methods like {@code getEntryCount}, 868 * {@code getSearchEntries}, {@code getReferenceCount}, and 869 * {@code getSearchReferences} may be used to obtain information about those 870 * entries and references (although if a search result listener was provided, 871 * then it will have been used to make any entries and references available, 872 * and they will not be available through the {@code getSearchEntries} and 873 * {@code getSearchReferences} methods). 874 * 875 * @param searchResultListener The search result listener that should be 876 * used to return results to the client. It may 877 * be {@code null} if the search results should 878 * be collected internally and returned in the 879 * {@code SearchResult} object. 880 * @param baseDN The base DN for the search request. It must 881 * not be {@code null}. 882 * @param scope The scope that specifies the range of entries 883 * that should be examined for the search. 884 * @param derefPolicy The dereference policy the server should use 885 * for any aliases encountered while processing 886 * the search. 887 * @param sizeLimit The maximum number of entries that the server 888 * should return for the search. A value of 889 * zero indicates that there should be no limit. 890 * @param timeLimit The maximum length of time in seconds that 891 * the server should spend processing this 892 * search request. A value of zero indicates 893 * that there should be no limit. 894 * @param typesOnly Indicates whether to return only attribute 895 * names in matching entries, or both attribute 896 * names and values. 897 * @param filter The string representation of the filter to 898 * use to identify matching entries. It must 899 * not be {@code null}. 900 * @param attributes The set of attributes that should be returned 901 * in matching entries. It may be {@code null} 902 * or empty if the default attribute set (all 903 * user attributes) is to be requested. 904 * 905 * @return A search result object that provides information about the 906 * processing of the search, potentially including the set of 907 * matching entries and search references returned by the server. 908 * 909 * @throws LDAPSearchException If the search does not complete successfully, 910 * or if a problem is encountered while parsing 911 * the provided filter string, sending the 912 * request, or reading the response. If one 913 * or more entries or references were returned 914 * before the failure was encountered, then the 915 * {@code LDAPSearchException} object may be 916 * examined to obtain information about those 917 * entries and/or references. 918 */ 919 SearchResult search(SearchResultListener searchResultListener, String baseDN, 920 SearchScope scope, DereferencePolicy derefPolicy, 921 int sizeLimit, int timeLimit, boolean typesOnly, 922 String filter, String... attributes) 923 throws LDAPSearchException; 924 925 926 927 /** 928 * Processes a search operation with the provided information. 929 * <BR><BR> 930 * Note that if the search does not complete successfully, an 931 * {@code LDAPSearchException} will be thrown In some cases, one or more 932 * search result entries or references may have been returned before the 933 * failure response is received. In this case, the 934 * {@code LDAPSearchException} methods like {@code getEntryCount}, 935 * {@code getSearchEntries}, {@code getReferenceCount}, and 936 * {@code getSearchReferences} may be used to obtain information about those 937 * entries and references (although if a search result listener was provided, 938 * then it will have been used to make any entries and references available, 939 * and they will not be available through the {@code getSearchEntries} and 940 * {@code getSearchReferences} methods). 941 * 942 * @param searchResultListener The search result listener that should be 943 * used to return results to the client. It may 944 * be {@code null} if the search results should 945 * be collected internally and returned in the 946 * {@code SearchResult} object. 947 * @param baseDN The base DN for the search request. It must 948 * not be {@code null}. 949 * @param scope The scope that specifies the range of entries 950 * that should be examined for the search. 951 * @param derefPolicy The dereference policy the server should use 952 * for any aliases encountered while processing 953 * the search. 954 * @param sizeLimit The maximum number of entries that the server 955 * should return for the search. A value of 956 * zero indicates that there should be no limit. 957 * @param timeLimit The maximum length of time in seconds that 958 * the server should spend processing this 959 * search request. A value of zero indicates 960 * that there should be no limit. 961 * @param typesOnly Indicates whether to return only attribute 962 * names in matching entries, or both attribute 963 * names and values. 964 * @param filter The filter to use to identify matching 965 * entries. It must not be {@code null}. 966 * @param attributes The set of attributes that should be returned 967 * in matching entries. It may be {@code null} 968 * or empty if the default attribute set (all 969 * user attributes) is to be requested. 970 * 971 * @return A search result object that provides information about the 972 * processing of the search, potentially including the set of 973 * matching entries and search references returned by the server. 974 * 975 * @throws LDAPSearchException If the search does not complete successfully, 976 * or if a problem is encountered while sending 977 * the request or reading the response. If one 978 * or more entries or references were returned 979 * before the failure was encountered, then the 980 * {@code LDAPSearchException} object may be 981 * examined to obtain information about those 982 * entries and/or references. 983 */ 984 SearchResult search(SearchResultListener searchResultListener, String baseDN, 985 SearchScope scope, DereferencePolicy derefPolicy, 986 int sizeLimit, int timeLimit, boolean typesOnly, 987 Filter filter, String... attributes) 988 throws LDAPSearchException; 989 990 991 992 /** 993 * Processes the provided search request. 994 * <BR><BR> 995 * Note that if the search does not complete successfully, an 996 * {@code LDAPSearchException} will be thrown In some cases, one or more 997 * search result entries or references may have been returned before the 998 * failure response is received. In this case, the 999 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1000 * {@code getSearchEntries}, {@code getReferenceCount}, and 1001 * {@code getSearchReferences} may be used to obtain information about those 1002 * entries and references (although if a search result listener was provided, 1003 * then it will have been used to make any entries and references available, 1004 * and they will not be available through the {@code getSearchEntries} and 1005 * {@code getSearchReferences} methods). 1006 * 1007 * @param searchRequest The search request to be processed. It must not be 1008 * {@code null}. 1009 * 1010 * @return A search result object that provides information about the 1011 * processing of the search, potentially including the set of 1012 * matching entries and search references returned by the server. 1013 * 1014 * @throws LDAPSearchException If the search does not complete successfully, 1015 * or if a problem is encountered while sending 1016 * the request or reading the response. If one 1017 * or more entries or references were returned 1018 * before the failure was encountered, then the 1019 * {@code LDAPSearchException} object may be 1020 * examined to obtain information about those 1021 * entries and/or references. 1022 */ 1023 SearchResult search(SearchRequest searchRequest) 1024 throws LDAPSearchException; 1025 1026 1027 1028 /** 1029 * Processes the provided search request. 1030 * <BR><BR> 1031 * Note that if the search does not complete successfully, an 1032 * {@code LDAPSearchException} will be thrown In some cases, one or more 1033 * search result entries or references may have been returned before the 1034 * failure response is received. In this case, the 1035 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1036 * {@code getSearchEntries}, {@code getReferenceCount}, and 1037 * {@code getSearchReferences} may be used to obtain information about those 1038 * entries and references (although if a search result listener was provided, 1039 * then it will have been used to make any entries and references available, 1040 * and they will not be available through the {@code getSearchEntries} and 1041 * {@code getSearchReferences} methods). 1042 * 1043 * @param searchRequest The search request to be processed. It must not be 1044 * {@code null}. 1045 * 1046 * @return A search result object that provides information about the 1047 * processing of the search, potentially including the set of 1048 * matching entries and search references returned by the server. 1049 * 1050 * @throws LDAPSearchException If the search does not complete successfully, 1051 * or if a problem is encountered while sending 1052 * the request or reading the response. If one 1053 * or more entries or references were returned 1054 * before the failure was encountered, then the 1055 * {@code LDAPSearchException} object may be 1056 * examined to obtain information about those 1057 * entries and/or references. 1058 */ 1059 SearchResult search(ReadOnlySearchRequest searchRequest) 1060 throws LDAPSearchException; 1061 1062 1063 1064 /** 1065 * Processes a search operation with the provided information. It is expected 1066 * that at most one entry will be returned from the search, and that no 1067 * additional content from the successful search result (e.g., diagnostic 1068 * message or response controls) are needed. 1069 * <BR><BR> 1070 * Note that if the search does not complete successfully, an 1071 * {@code LDAPSearchException} will be thrown In some cases, one or more 1072 * search result entries or references may have been returned before the 1073 * failure response is received. In this case, the 1074 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1075 * {@code getSearchEntries}, {@code getReferenceCount}, and 1076 * {@code getSearchReferences} may be used to obtain information about those 1077 * entries and references. 1078 * 1079 * @param baseDN The base DN for the search request. It must not be 1080 * {@code null}. 1081 * @param scope The scope that specifies the range of entries that 1082 * should be examined for the search. 1083 * @param filter The string representation of the filter to use to 1084 * identify matching entries. It must not be 1085 * {@code null}. 1086 * @param attributes The set of attributes that should be returned in 1087 * matching entries. It may be {@code null} or empty if 1088 * the default attribute set (all user attributes) is to 1089 * be requested. 1090 * 1091 * @return The entry that was returned from the search, or {@code null} if no 1092 * entry was returned or the base entry does not exist. 1093 * 1094 * @throws LDAPSearchException If the search does not complete successfully, 1095 * if more than a single entry is returned, or 1096 * if a problem is encountered while parsing the 1097 * provided filter string, sending the request, 1098 * or reading the response. If one or more 1099 * entries or references were returned before 1100 * the failure was encountered, then the 1101 * {@code LDAPSearchException} object may be 1102 * examined to obtain information about those 1103 * entries and/or references. 1104 */ 1105 SearchResultEntry searchForEntry(String baseDN, SearchScope scope, 1106 String filter, String... attributes) 1107 throws LDAPSearchException; 1108 1109 1110 1111 /** 1112 * Processes a search operation with the provided information. It is expected 1113 * that at most one entry will be returned from the search, and that no 1114 * additional content from the successful search result (e.g., diagnostic 1115 * message or response controls) are needed. 1116 * <BR><BR> 1117 * Note that if the search does not complete successfully, an 1118 * {@code LDAPSearchException} will be thrown In some cases, one or more 1119 * search result entries or references may have been returned before the 1120 * failure response is received. In this case, the 1121 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1122 * {@code getSearchEntries}, {@code getReferenceCount}, and 1123 * {@code getSearchReferences} may be used to obtain information about those 1124 * entries and references. 1125 * 1126 * @param baseDN The base DN for the search request. It must not be 1127 * {@code null}. 1128 * @param scope The scope that specifies the range of entries that 1129 * should be examined for the search. 1130 * @param filter The string representation of the filter to use to 1131 * identify matching entries. It must not be 1132 * {@code null}. 1133 * @param attributes The set of attributes that should be returned in 1134 * matching entries. It may be {@code null} or empty if 1135 * the default attribute set (all user attributes) is to 1136 * be requested. 1137 * 1138 * @return The entry that was returned from the search, or {@code null} if no 1139 * entry was returned or the base entry does not exist. 1140 * 1141 * @throws LDAPSearchException If the search does not complete successfully, 1142 * if more than a single entry is returned, or 1143 * if a problem is encountered while parsing the 1144 * provided filter string, sending the request, 1145 * or reading the response. If one or more 1146 * entries or references were returned before 1147 * the failure was encountered, then the 1148 * {@code LDAPSearchException} object may be 1149 * examined to obtain information about those 1150 * entries and/or references. 1151 */ 1152 SearchResultEntry searchForEntry(String baseDN, SearchScope scope, 1153 Filter filter, String... attributes) 1154 throws LDAPSearchException; 1155 1156 1157 1158 /** 1159 * Processes a search operation with the provided information. It is expected 1160 * that at most one entry will be returned from the search, and that no 1161 * additional content from the successful search result (e.g., diagnostic 1162 * message or response controls) are needed. 1163 * <BR><BR> 1164 * Note that if the search does not complete successfully, an 1165 * {@code LDAPSearchException} will be thrown In some cases, one or more 1166 * search result entries or references may have been returned before the 1167 * failure response is received. In this case, the 1168 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1169 * {@code getSearchEntries}, {@code getReferenceCount}, and 1170 * {@code getSearchReferences} may be used to obtain information about those 1171 * entries and references. 1172 * 1173 * @param baseDN The base DN for the search request. It must not be 1174 * {@code null}. 1175 * @param scope The scope that specifies the range of entries that 1176 * should be examined for the search. 1177 * @param derefPolicy The dereference policy the server should use for any 1178 * aliases encountered while processing the search. 1179 * @param timeLimit The maximum length of time in seconds that the server 1180 * should spend processing this search request. A value 1181 * of zero indicates that there should be no limit. 1182 * @param typesOnly Indicates whether to return only attribute names in 1183 * matching entries, or both attribute names and values. 1184 * @param filter The string representation of the filter to use to 1185 * identify matching entries. It must not be 1186 * {@code null}. 1187 * @param attributes The set of attributes that should be returned in 1188 * matching entries. It may be {@code null} or empty if 1189 * the default attribute set (all user attributes) is to 1190 * be requested. 1191 * 1192 * @return The entry that was returned from the search, or {@code null} if no 1193 * entry was returned or the base entry does not exist. 1194 * 1195 * @throws LDAPSearchException If the search does not complete successfully, 1196 * if more than a single entry is returned, or 1197 * if a problem is encountered while parsing the 1198 * provided filter string, sending the request, 1199 * or reading the response. If one or more 1200 * entries or references were returned before 1201 * the failure was encountered, then the 1202 * {@code LDAPSearchException} object may be 1203 * examined to obtain information about those 1204 * entries and/or references. 1205 */ 1206 SearchResultEntry searchForEntry(String baseDN, SearchScope scope, 1207 DereferencePolicy derefPolicy, int timeLimit, 1208 boolean typesOnly, String filter, 1209 String... attributes) 1210 throws LDAPSearchException; 1211 1212 1213 1214 /** 1215 * Processes a search operation with the provided information. It is expected 1216 * that at most one entry will be returned from the search, and that no 1217 * additional content from the successful search result (e.g., diagnostic 1218 * message or response controls) are needed. 1219 * <BR><BR> 1220 * Note that if the search does not complete successfully, an 1221 * {@code LDAPSearchException} will be thrown In some cases, one or more 1222 * search result entries or references may have been returned before the 1223 * failure response is received. In this case, the 1224 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1225 * {@code getSearchEntries}, {@code getReferenceCount}, and 1226 * {@code getSearchReferences} may be used to obtain information about those 1227 * entries and references. 1228 * 1229 * @param baseDN The base DN for the search request. It must not be 1230 * {@code null}. 1231 * @param scope The scope that specifies the range of entries that 1232 * should be examined for the search. 1233 * @param derefPolicy The dereference policy the server should use for any 1234 * aliases encountered while processing the search. 1235 * @param timeLimit The maximum length of time in seconds that the server 1236 * should spend processing this search request. A value 1237 * of zero indicates that there should be no limit. 1238 * @param typesOnly Indicates whether to return only attribute names in 1239 * matching entries, or both attribute names and values. 1240 * @param filter The filter to use to identify matching entries. It 1241 * must not be {@code null}. 1242 * @param attributes The set of attributes that should be returned in 1243 * matching entries. It may be {@code null} or empty if 1244 * the default attribute set (all user attributes) is to 1245 * be requested. 1246 * 1247 * @return The entry that was returned from the search, or {@code null} if no 1248 * entry was returned or the base entry does not exist. 1249 * 1250 * @throws LDAPSearchException If the search does not complete successfully, 1251 * if more than a single entry is returned, or 1252 * if a problem is encountered while parsing the 1253 * provided filter string, sending the request, 1254 * or reading the response. If one or more 1255 * entries or references were returned before 1256 * the failure was encountered, then the 1257 * {@code LDAPSearchException} object may be 1258 * examined to obtain information about those 1259 * entries and/or references. 1260 */ 1261 SearchResultEntry searchForEntry(String baseDN, SearchScope scope, 1262 DereferencePolicy derefPolicy, int timeLimit, 1263 boolean typesOnly, Filter filter, 1264 String... attributes) 1265 throws LDAPSearchException; 1266 1267 1268 1269 /** 1270 * Processes the provided search request. It is expected that at most one 1271 * entry will be returned from the search, and that no additional content from 1272 * the successful search result (e.g., diagnostic message or response 1273 * controls) are needed. 1274 * <BR><BR> 1275 * Note that if the search does not complete successfully, an 1276 * {@code LDAPSearchException} will be thrown In some cases, one or more 1277 * search result entries or references may have been returned before the 1278 * failure response is received. In this case, the 1279 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1280 * {@code getSearchEntries}, {@code getReferenceCount}, and 1281 * {@code getSearchReferences} may be used to obtain information about those 1282 * entries and references. 1283 * 1284 * @param searchRequest The search request to be processed. If it is 1285 * configured with a search result listener or a size 1286 * limit other than one, then the provided request will 1287 * be duplicated with the appropriate settings. 1288 * 1289 * @return The entry that was returned from the search, or {@code null} if no 1290 * entry was returned or the base entry does not exist. 1291 * 1292 * @throws LDAPSearchException If the search does not complete successfully, 1293 * if more than a single entry is returned, or 1294 * if a problem is encountered while parsing the 1295 * provided filter string, sending the request, 1296 * or reading the response. If one or more 1297 * entries or references were returned before 1298 * the failure was encountered, then the 1299 * {@code LDAPSearchException} object may be 1300 * examined to obtain information about those 1301 * entries and/or references. 1302 */ 1303 SearchResultEntry searchForEntry(SearchRequest searchRequest) 1304 throws LDAPSearchException; 1305 1306 1307 1308 /** 1309 * Processes the provided search request. It is expected that at most one 1310 * entry will be returned from the search, and that no additional content from 1311 * the successful search result (e.g., diagnostic message or response 1312 * controls) are needed. 1313 * <BR><BR> 1314 * Note that if the search does not complete successfully, an 1315 * {@code LDAPSearchException} will be thrown In some cases, one or more 1316 * search result entries or references may have been returned before the 1317 * failure response is received. In this case, the 1318 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1319 * {@code getSearchEntries}, {@code getReferenceCount}, and 1320 * {@code getSearchReferences} may be used to obtain information about those 1321 * entries and references. 1322 * 1323 * @param searchRequest The search request to be processed. If it is 1324 * configured with a search result listener or a size 1325 * limit other than one, then the provided request will 1326 * be duplicated with the appropriate settings. 1327 * 1328 * @return The entry that was returned from the search, or {@code null} if no 1329 * entry was returned or the base entry does not exist. 1330 * 1331 * @throws LDAPSearchException If the search does not complete successfully, 1332 * if more than a single entry is returned, or 1333 * if a problem is encountered while parsing the 1334 * provided filter string, sending the request, 1335 * or reading the response. If one or more 1336 * entries or references were returned before 1337 * the failure was encountered, then the 1338 * {@code LDAPSearchException} object may be 1339 * examined to obtain information about those 1340 * entries and/or references. 1341 */ 1342 SearchResultEntry searchForEntry(ReadOnlySearchRequest searchRequest) 1343 throws LDAPSearchException; 1344}