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