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