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