001/* 002 * Copyright 2009-2017 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2009-2017 UnboundID Corp. 007 * 008 * This program is free software; you can redistribute it and/or modify 009 * it under the terms of the GNU General Public License (GPLv2 only) 010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 011 * as published by the Free Software Foundation. 012 * 013 * This program is distributed in the hope that it will be useful, 014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 016 * GNU General Public License for more details. 017 * 018 * You should have received a copy of the GNU General Public License 019 * along with this program; if not, see <http://www.gnu.org/licenses>. 020 */ 021package com.unboundid.ldap.sdk; 022 023 024 025import java.io.Closeable; 026import java.util.Collection; 027import java.util.List; 028 029import com.unboundid.ldap.sdk.schema.Schema; 030import com.unboundid.ldif.LDIFException; 031import com.unboundid.util.ThreadSafety; 032import com.unboundid.util.ThreadSafetyLevel; 033 034import static com.unboundid.util.Debug.*; 035import static com.unboundid.util.Validator.*; 036 037 038 039/** 040 * This class provides an implementation of a special type of LDAP connection 041 * pool which maintains two separate sets of connections: one for read 042 * operations and the other for write operations. The "write" connections will 043 * be used for add, delete, modify, and modify DN operations, and the "read" 044 * connections will be used for all other processing including bind, compare, 045 * and search operations, as well as methods like {@link #getEntry}, 046 * {@link #getRootDSE}, and {@link #getSchema}. If the target directory 047 * environment does not require separate servers for read and write operations, 048 * then it is recommended that the simpler {@link LDAPConnectionPool} class be 049 * used instead. 050 * <BR><BR> 051 * This class is very similar to the {@code LDAPConnectionPool} class with the 052 * exception that it is possible to explicitly check out and release connections 053 * from either the read or write pools, and there is no convenience method for 054 * processing multiple requests over the same connection. See the documentation 055 * for the {@link LDAPConnectionPool} class for additional documentation and 056 * for examples demonstrating the use of both connection pool implementations. 057 */ 058@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 059public final class LDAPReadWriteConnectionPool 060 implements LDAPInterface, Closeable 061{ 062 // The connection pool used for read operations. 063 private final LDAPConnectionPool readPool; 064 065 // The connection pool used for write operations. 066 private final LDAPConnectionPool writePool; 067 068 069 070 /** 071 * Creates a new LDAP read-write connection pool with the provided 072 * connections. 073 * 074 * @param readConnection The connection to use to provide the 075 * template for other connections to be 076 * created for performing read operations. 077 * This connection will be included in the 078 * pool. It must not be {@code null}, and it 079 * must be established to the target server. 080 * It does not necessarily need to be 081 * authenticated if all read connections are 082 * to be unauthenticated. 083 * @param initialReadConnections The number of connections to initially 084 * establish in the pool that is created for 085 * read operations. It must be greater than 086 * or equal to one. 087 * @param maxReadConnections The maximum number of connections that 088 * should be maintained in the read pool. 089 * It must be greater than or equal to the 090 * initial number of write connections. 091 * @param writeConnection The connection to use to provide the 092 * template for other connections to be 093 * created for performing write operations. 094 * This connection will be included in the 095 * pool. It must not be {@code null}, and it 096 * must be established to the target server. 097 * It does not necessarily need to be 098 * authenticated if all write connections are 099 * to be unauthenticated. 100 * @param initialWriteConnections The number of connections to initially 101 * establish in the pool that is created for 102 * write operations. It must be greater than 103 * or equal to one. 104 * @param maxWriteConnections The maximum number of connections that 105 * should be maintained in the write pool. 106 * It must be greater than or equal to the 107 * initial number of write connections. 108 * 109 * @throws LDAPException If either of the provided connections cannot be 110 * used to initialize the pool, or if a problem occurs 111 * while attempting to establish any of the 112 * connections. If this is thrown, then all 113 * connections associated with this pool (including 114 * the read and write connections provided as 115 * arguments) will be closed. 116 */ 117 public LDAPReadWriteConnectionPool(final LDAPConnection readConnection, 118 final int initialReadConnections, final int maxReadConnections, 119 final LDAPConnection writeConnection, 120 final int initialWriteConnections, final int maxWriteConnections) 121 throws LDAPException 122 { 123 ensureNotNull(readConnection, writeConnection); 124 ensureTrue(initialReadConnections >= 1, 125 "LDAPReadWriteConnectionPool.initialReadConnections must be " + 126 "at least 1."); 127 ensureTrue(maxReadConnections >= initialReadConnections, 128 "LDAPReadWriteConnectionPool.initialReadConnections must not " + 129 "be greater than maxReadConnections."); 130 ensureTrue(initialWriteConnections >= 1, 131 "LDAPReadWriteConnectionPool.initialWriteConnections must be " + 132 "at least 1."); 133 ensureTrue(maxWriteConnections >= initialWriteConnections, 134 "LDAPReadWriteConnectionPool.initialWriteConnections must not " + 135 "be greater than maxWriteConnections."); 136 137 readPool = new LDAPConnectionPool(readConnection, initialReadConnections, 138 maxReadConnections); 139 140 try 141 { 142 writePool = new LDAPConnectionPool(writeConnection, 143 initialWriteConnections, maxWriteConnections); 144 } 145 catch (LDAPException le) 146 { 147 debugException(le); 148 readPool.close(); 149 throw le; 150 } 151 } 152 153 154 155 /** 156 * Creates a new LDAP read-write connection pool with the provided pools for 157 * read and write operations, respectively. 158 * 159 * @param readPool The connection pool to be used for read operations. It 160 * must not be {@code null}. 161 * @param writePool The connection pool to be used for write operations. It 162 * must not be {@code null}. 163 */ 164 public LDAPReadWriteConnectionPool(final LDAPConnectionPool readPool, 165 final LDAPConnectionPool writePool) 166 { 167 ensureNotNull(readPool, writePool); 168 169 this.readPool = readPool; 170 this.writePool = writePool; 171 } 172 173 174 175 /** 176 * Closes this connection pool. All read and write connections currently held 177 * in the pool that are not in use will be closed, and any outstanding 178 * connections will be automatically closed when they are released back to the 179 * pool. 180 */ 181 public void close() 182 { 183 readPool.close(); 184 writePool.close(); 185 } 186 187 188 189 /** 190 * Indicates whether this connection pool has been closed. 191 * 192 * @return {@code true} if this connection pool has been closed, or 193 * {@code false} if not. 194 */ 195 public boolean isClosed() 196 { 197 return readPool.isClosed() || writePool.isClosed(); 198 } 199 200 201 202 /** 203 * Retrieves an LDAP connection from the read pool. 204 * 205 * @return The LDAP connection taken from the read pool. 206 * 207 * @throws LDAPException If no read connection is available, or a problem 208 * occurs while creating a new connection to return. 209 */ 210 public LDAPConnection getReadConnection() 211 throws LDAPException 212 { 213 return readPool.getConnection(); 214 } 215 216 217 218 /** 219 * Releases the provided connection back to the read pool. 220 * 221 * @param connection The connection to be released back to the read pool. 222 */ 223 public void releaseReadConnection(final LDAPConnection connection) 224 { 225 readPool.releaseConnection(connection); 226 } 227 228 229 230 /** 231 * Indicates that the provided read connection is no longer in use, but is 232 * also no longer fit for use. The provided connection will be terminated and 233 * a new connection will be created and added to the read pool in its place. 234 * 235 * @param connection The defunct read connection being released. 236 */ 237 public void releaseDefunctReadConnection(final LDAPConnection connection) 238 { 239 readPool.releaseDefunctConnection(connection); 240 } 241 242 243 244 /** 245 * Retrieves an LDAP connection from the write pool. 246 * 247 * @return The LDAP connection taken from the write pool. 248 * 249 * @throws LDAPException If no write connection is available, or a problem 250 * occurs while creating a new connection to return. 251 */ 252 public LDAPConnection getWriteConnection() 253 throws LDAPException 254 { 255 return writePool.getConnection(); 256 } 257 258 259 260 /** 261 * Releases the provided connection back to the write pool. 262 * 263 * @param connection The connection to be released back to the write pool. 264 */ 265 public void releaseWriteConnection(final LDAPConnection connection) 266 { 267 writePool.releaseConnection(connection); 268 } 269 270 271 272 /** 273 * Indicates that the provided write connection is no longer in use, but is 274 * also no longer fit for use. The provided connection will be terminated and 275 * a new connection will be created and added to the write pool in its place. 276 * 277 * @param connection The defunct write connection being released. 278 */ 279 public void releaseDefunctWriteConnection(final LDAPConnection connection) 280 { 281 writePool.releaseDefunctConnection(connection); 282 } 283 284 285 286 /** 287 * Retrieves the set of statistics maintained for the read pool. 288 * 289 * @return The set of statistics maintained for the read pool. 290 */ 291 public LDAPConnectionPoolStatistics getReadPoolStatistics() 292 { 293 return readPool.getConnectionPoolStatistics(); 294 } 295 296 297 298 /** 299 * Retrieves the set of statistics maintained for the write pool. 300 * 301 * @return The set of statistics maintained for the write pool. 302 */ 303 public LDAPConnectionPoolStatistics getWritePoolStatistics() 304 { 305 return writePool.getConnectionPoolStatistics(); 306 } 307 308 309 310 /** 311 * Retrieves the connection pool that should be used for read operations. 312 * 313 * @return The connection pool that should be used for read operations. 314 */ 315 public LDAPConnectionPool getReadPool() 316 { 317 return readPool; 318 } 319 320 321 322 /** 323 * Retrieves the connection pool that should be used for write operations. 324 * 325 * @return The connection pool that should be used for write operations. 326 */ 327 public LDAPConnectionPool getWritePool() 328 { 329 return writePool; 330 } 331 332 333 334 /** 335 * Retrieves the directory server root DSE using a read connection from this 336 * connection pool. 337 * 338 * @return The directory server root DSE, or {@code null} if it is not 339 * available. 340 * 341 * @throws LDAPException If a problem occurs while attempting to retrieve 342 * the server root DSE. 343 */ 344 public RootDSE getRootDSE() 345 throws LDAPException 346 { 347 return readPool.getRootDSE(); 348 } 349 350 351 352 /** 353 * Retrieves the directory server schema definitions using a read connection 354 * from this connection pool, using the subschema subentry DN contained in the 355 * server's root DSE. For directory servers containing a single schema, this 356 * should be sufficient for all purposes. For servers with multiple schemas, 357 * it may be necessary to specify the DN of the target entry for which to 358 * obtain the associated schema. 359 * 360 * @return The directory server schema definitions, or {@code null} if the 361 * schema information could not be retrieved (e.g, the client does 362 * not have permission to read the server schema). 363 * 364 * @throws LDAPException If a problem occurs while attempting to retrieve 365 * the server schema. 366 */ 367 public Schema getSchema() 368 throws LDAPException 369 { 370 return readPool.getSchema(); 371 } 372 373 374 375 /** 376 * Retrieves the directory server schema definitions that govern the specified 377 * entry using a read connection from this connection pool. The 378 * subschemaSubentry attribute will be retrieved from the target entry, and 379 * then the appropriate schema definitions will be loaded from the entry 380 * referenced by that attribute. This may be necessary to ensure correct 381 * behavior in servers that support multiple schemas. 382 * 383 * @param entryDN The DN of the entry for which to retrieve the associated 384 * schema definitions. It may be {@code null} or an empty 385 * string if the subschemaSubentry attribute should be 386 * retrieved from the server's root DSE. 387 * 388 * @return The directory server schema definitions, or {@code null} if the 389 * schema information could not be retrieved (e.g, the client does 390 * not have permission to read the server schema). 391 * 392 * @throws LDAPException If a problem occurs while attempting to retrieve 393 * the server schema. 394 */ 395 public Schema getSchema(final String entryDN) 396 throws LDAPException 397 { 398 return readPool.getSchema(entryDN); 399 } 400 401 402 403 /** 404 * Retrieves the entry with the specified DN using a read connection from this 405 * connection pool. All user attributes will be requested in the entry to 406 * return. 407 * 408 * @param dn The DN of the entry to retrieve. It must not be {@code null}. 409 * 410 * @return The requested entry, or {@code null} if the target entry does not 411 * exist or no entry was returned (e.g., if the authenticated user 412 * does not have permission to read the target entry). 413 * 414 * @throws LDAPException If a problem occurs while sending the request or 415 * reading the response. 416 */ 417 public SearchResultEntry getEntry(final String dn) 418 throws LDAPException 419 { 420 return readPool.getEntry(dn); 421 } 422 423 424 425 /** 426 * Retrieves the entry with the specified DN using a read connection from this 427 * connection pool. 428 * 429 * @param dn The DN of the entry to retrieve. It must not be 430 * {@code null}. 431 * @param attributes The set of attributes to request for the target entry. 432 * If it is {@code null}, then all user attributes will be 433 * requested. 434 * 435 * @return The requested entry, or {@code null} if the target entry does not 436 * exist or no entry was returned (e.g., if the authenticated user 437 * does not have permission to read the target entry). 438 * 439 * @throws LDAPException If a problem occurs while sending the request or 440 * reading the response. 441 */ 442 public SearchResultEntry getEntry(final String dn, final String... attributes) 443 throws LDAPException 444 { 445 return readPool.getEntry(dn, attributes); 446 } 447 448 449 450 /** 451 * Processes an add operation with the provided information using a write 452 * connection from this connection pool. 453 * 454 * @param dn The DN of the entry to add. It must not be 455 * {@code null}. 456 * @param attributes The set of attributes to include in the entry to add. 457 * It must not be {@code null}. 458 * 459 * @return The result of processing the add operation. 460 * 461 * @throws LDAPException If the server rejects the add request, or if a 462 * problem is encountered while sending the request or 463 * reading the response. 464 */ 465 public LDAPResult add(final String dn, final Attribute... attributes) 466 throws LDAPException 467 { 468 return writePool.add(dn, attributes); 469 } 470 471 472 473 /** 474 * Processes an add operation with the provided information using a write 475 * connection from this connection pool. 476 * 477 * @param dn The DN of the entry to add. It must not be 478 * {@code null}. 479 * @param attributes The set of attributes to include in the entry to add. 480 * It must not be {@code null}. 481 * 482 * @return The result of processing the add operation. 483 * 484 * @throws LDAPException If the server rejects the add request, or if a 485 * problem is encountered while sending the request or 486 * reading the response. 487 */ 488 public LDAPResult add(final String dn, final Collection<Attribute> attributes) 489 throws LDAPException 490 { 491 return writePool.add(dn, attributes); 492 } 493 494 495 496 /** 497 * Processes an add operation with the provided information using a write 498 * connection from this connection pool. 499 * 500 * @param entry The entry to add. It must not be {@code null}. 501 * 502 * @return The result of processing the add operation. 503 * 504 * @throws LDAPException If the server rejects the add request, or if a 505 * problem is encountered while sending the request or 506 * reading the response. 507 */ 508 public LDAPResult add(final Entry entry) 509 throws LDAPException 510 { 511 return writePool.add(entry); 512 } 513 514 515 516 /** 517 * Processes an add operation with the provided information using a write 518 * connection from this connection pool. 519 * 520 * @param ldifLines The lines that comprise an LDIF representation of the 521 * entry to add. It must not be empty or {@code null}. 522 * 523 * @return The result of processing the add operation. 524 * 525 * @throws LDIFException If the provided entry lines cannot be decoded as an 526 * entry in LDIF form. 527 * 528 * @throws LDAPException If the server rejects the add request, or if a 529 * problem is encountered while sending the request or 530 * reading the response. 531 */ 532 public LDAPResult add(final String... ldifLines) 533 throws LDIFException, LDAPException 534 { 535 return writePool.add(ldifLines); 536 } 537 538 539 540 /** 541 * Processes the provided add request using a write connection from this 542 * connection pool. 543 * 544 * @param addRequest The add request to be processed. It must not be 545 * {@code null}. 546 * 547 * @return The result of processing the add operation. 548 * 549 * @throws LDAPException If the server rejects the add request, or if a 550 * problem is encountered while sending the request or 551 * reading the response. 552 */ 553 public LDAPResult add(final AddRequest addRequest) 554 throws LDAPException 555 { 556 return writePool.add(addRequest); 557 } 558 559 560 561 /** 562 * Processes the provided add request using a write connection from this 563 * connection pool. 564 * 565 * @param addRequest The add request to be processed. It must not be 566 * {@code null}. 567 * 568 * @return The result of processing the add operation. 569 * 570 * @throws LDAPException If the server rejects the add request, or if a 571 * problem is encountered while sending the request or 572 * reading the response. 573 */ 574 public LDAPResult add(final ReadOnlyAddRequest addRequest) 575 throws LDAPException 576 { 577 return writePool.add((AddRequest) addRequest); 578 } 579 580 581 582 /** 583 * Processes a simple bind request with the provided DN and password using a 584 * read connection from this connection pool. Note that this will impact the 585 * state of the connection in the pool, and therefore this method should only 586 * be used if this connection pool is used exclusively for processing bind 587 * operations, or if the retain identity request control (only available in 588 * the Commercial Edition of the LDAP SDK for use with the Ping Identity, 589 * UnboundID, or Alcatel-Lucent 8661 Directory Server) is included in the bind 590 * request to ensure that the authentication state is not impacted. 591 * 592 * @param bindDN The bind DN for the bind operation. 593 * @param password The password for the simple bind operation. 594 * 595 * @return The result of processing the bind operation. 596 * 597 * @throws LDAPException If the server rejects the bind request, or if a 598 * problem occurs while sending the request or reading 599 * the response. 600 */ 601 public BindResult bind(final String bindDN, final String password) 602 throws LDAPException 603 { 604 return readPool.bind(bindDN, password); 605 } 606 607 608 609 /** 610 * Processes the provided bind request using a read connection from this 611 * connection pool. Note that this will impact the state of the connection in 612 * the pool, and therefore this method should only be used if this connection 613 * pool is used exclusively for processing bind operations, or if the retain 614 * identity request control (only available in the Commercial Edition of the 615 * LDAP SDK for use with the Ping Identity, UnboundID, or Alcatel-Lucent 8661 616 * Directory Server) is included in the bind request to ensure that the 617 * authentication state is not impacted. 618 * 619 * @param bindRequest The bind request to be processed. It must not be 620 * {@code null}. 621 * 622 * @return The result of processing the bind operation. 623 * 624 * @throws LDAPException If the server rejects the bind request, or if a 625 * problem occurs while sending the request or reading 626 * the response. 627 */ 628 public BindResult bind(final BindRequest bindRequest) 629 throws LDAPException 630 { 631 return readPool.bind(bindRequest); 632 } 633 634 635 636 /** 637 * Processes a compare operation with the provided information using a read 638 * connection from this connection pool. 639 * 640 * @param dn The DN of the entry in which to make the 641 * comparison. It must not be {@code null}. 642 * @param attributeName The attribute name for which to make the 643 * comparison. It must not be {@code null}. 644 * @param assertionValue The assertion value to verify in the target entry. 645 * It must not be {@code null}. 646 * 647 * @return The result of processing the compare operation. 648 * 649 * @throws LDAPException If the server rejects the compare request, or if a 650 * problem is encountered while sending the request or 651 * reading the response. 652 */ 653 public CompareResult compare(final String dn, final String attributeName, 654 final String assertionValue) 655 throws LDAPException 656 { 657 return readPool.compare(dn, attributeName, assertionValue); 658 } 659 660 661 662 /** 663 * Processes the provided compare request using a read connection from this 664 * connection pool. 665 * 666 * @param compareRequest The compare request to be processed. It must not 667 * be {@code null}. 668 * 669 * @return The result of processing the compare operation. 670 * 671 * @throws LDAPException If the server rejects the compare request, or if a 672 * problem is encountered while sending the request or 673 * reading the response. 674 */ 675 public CompareResult compare(final CompareRequest compareRequest) 676 throws LDAPException 677 { 678 return readPool.compare(compareRequest); 679 } 680 681 682 683 /** 684 * Processes the provided compare request using a read connection from this 685 * connection pool. 686 * 687 * @param compareRequest The compare request to be processed. It must not 688 * be {@code null}. 689 * 690 * @return The result of processing the compare operation. 691 * 692 * @throws LDAPException If the server rejects the compare request, or if a 693 * problem is encountered while sending the request or 694 * reading the response. 695 */ 696 public CompareResult compare(final ReadOnlyCompareRequest compareRequest) 697 throws LDAPException 698 { 699 return readPool.compare(compareRequest); 700 } 701 702 703 704 /** 705 * Deletes the entry with the specified DN using a write connection from this 706 * connection pool. 707 * 708 * @param dn The DN of the entry to delete. It must not be {@code null}. 709 * 710 * @return The result of processing the delete operation. 711 * 712 * @throws LDAPException If the server rejects the delete request, or if a 713 * problem is encountered while sending the request or 714 * reading the response. 715 */ 716 public LDAPResult delete(final String dn) 717 throws LDAPException 718 { 719 return writePool.delete(dn); 720 } 721 722 723 724 /** 725 * Processes the provided delete request using a write connection from this 726 * connection pool. 727 * 728 * @param deleteRequest The delete request to be processed. It must not be 729 * {@code null}. 730 * 731 * @return The result of processing the delete operation. 732 * 733 * @throws LDAPException If the server rejects the delete request, or if a 734 * problem is encountered while sending the request or 735 * reading the response. 736 */ 737 public LDAPResult delete(final DeleteRequest deleteRequest) 738 throws LDAPException 739 { 740 return writePool.delete(deleteRequest); 741 } 742 743 744 745 /** 746 * Processes the provided delete request using a write connection from this 747 * connection pool. 748 * 749 * @param deleteRequest The delete request to be processed. It must not be 750 * {@code null}. 751 * 752 * @return The result of processing the delete operation. 753 * 754 * @throws LDAPException If the server rejects the delete request, or if a 755 * problem is encountered while sending the request or 756 * reading the response. 757 */ 758 public LDAPResult delete(final ReadOnlyDeleteRequest deleteRequest) 759 throws LDAPException 760 { 761 return writePool.delete(deleteRequest); 762 } 763 764 765 766 /** 767 * Applies the provided modification to the specified entry using a write 768 * connection from this connection pool. 769 * 770 * @param dn The DN of the entry to modify. It must not be {@code null}. 771 * @param mod The modification to apply to the target entry. It must not 772 * be {@code null}. 773 * 774 * @return The result of processing the modify operation. 775 * 776 * @throws LDAPException If the server rejects the modify request, or if a 777 * problem is encountered while sending the request or 778 * reading the response. 779 */ 780 public LDAPResult modify(final String dn, final Modification mod) 781 throws LDAPException 782 { 783 return writePool.modify(dn, mod); 784 } 785 786 787 788 /** 789 * Applies the provided set of modifications to the specified entry using a 790 * write connection from this connection pool. 791 * 792 * @param dn The DN of the entry to modify. It must not be {@code null}. 793 * @param mods The set of modifications to apply to the target entry. It 794 * must not be {@code null} or empty. * 795 * @return The result of processing the modify operation. 796 * 797 * @throws LDAPException If the server rejects the modify request, or if a 798 * problem is encountered while sending the request or 799 * reading the response. 800 */ 801 public LDAPResult modify(final String dn, final Modification... mods) 802 throws LDAPException 803 { 804 return writePool.modify(dn, mods); 805 } 806 807 808 809 /** 810 * Applies the provided set of modifications to the specified entry using a 811 * write connection from this connection pool. 812 * 813 * @param dn The DN of the entry to modify. It must not be {@code null}. 814 * @param mods The set of modifications to apply to the target entry. It 815 * must not be {@code null} or empty. 816 * 817 * @return The result of processing the modify operation. 818 * 819 * @throws LDAPException If the server rejects the modify request, or if a 820 * problem is encountered while sending the request or 821 * reading the response. 822 */ 823 public LDAPResult modify(final String dn, final List<Modification> mods) 824 throws LDAPException 825 { 826 return writePool.modify(dn, mods); 827 } 828 829 830 831 /** 832 * Processes a modify request from the provided LDIF representation of the 833 * changes using a write connection from this connection pool. 834 * 835 * @param ldifModificationLines The lines that comprise an LDIF 836 * representation of a modify change record. 837 * It must not be {@code null} or empty. 838 * 839 * @return The result of processing the modify operation. 840 * 841 * @throws LDIFException If the provided set of lines cannot be parsed as an 842 * LDIF modify change record. 843 * 844 * @throws LDAPException If the server rejects the modify request, or if a 845 * problem is encountered while sending the request or 846 * reading the response. 847 * 848 */ 849 public LDAPResult modify(final String... ldifModificationLines) 850 throws LDIFException, LDAPException 851 { 852 return writePool.modify(ldifModificationLines); 853 } 854 855 856 857 /** 858 * Processes the provided modify request using a write connection from this 859 * connection pool. 860 * 861 * @param modifyRequest The modify request to be processed. It must not be 862 * {@code null}. 863 * 864 * @return The result of processing the modify operation. 865 * 866 * @throws LDAPException If the server rejects the modify request, or if a 867 * problem is encountered while sending the request or 868 * reading the response. 869 */ 870 public LDAPResult modify(final ModifyRequest modifyRequest) 871 throws LDAPException 872 { 873 return writePool.modify(modifyRequest); 874 } 875 876 877 878 /** 879 * Processes the provided modify request using a write connection from this 880 * connection pool. 881 * 882 * @param modifyRequest The modify request to be processed. It must not be 883 * {@code null}. 884 * 885 * @return The result of processing the modify operation. 886 * 887 * @throws LDAPException If the server rejects the modify request, or if a 888 * problem is encountered while sending the request or 889 * reading the response. 890 */ 891 public LDAPResult modify(final ReadOnlyModifyRequest modifyRequest) 892 throws LDAPException 893 { 894 return writePool.modify(modifyRequest); 895 } 896 897 898 899 /** 900 * Performs a modify DN operation with the provided information using a write 901 * connection from this connection pool. 902 * 903 * @param dn The current DN for the entry to rename. It must not 904 * be {@code null}. 905 * @param newRDN The new RDN to use for the entry. It must not be 906 * {@code null}. 907 * @param deleteOldRDN Indicates whether to delete the current RDN value 908 * from the entry. 909 * 910 * @return The result of processing the modify DN operation. 911 * 912 * @throws LDAPException If the server rejects the modify DN request, or if 913 * a problem is encountered while sending the request 914 * or reading the response. 915 */ 916 public LDAPResult modifyDN(final String dn, final String newRDN, 917 final boolean deleteOldRDN) 918 throws LDAPException 919 { 920 return writePool.modifyDN(dn, newRDN, deleteOldRDN); 921 } 922 923 924 925 /** 926 * Performs a modify DN operation with the provided information using a write 927 * connection from this connection pool. 928 * 929 * @param dn The current DN for the entry to rename. It must not 930 * be {@code null}. 931 * @param newRDN The new RDN to use for the entry. It must not be 932 * {@code null}. 933 * @param deleteOldRDN Indicates whether to delete the current RDN value 934 * from the entry. 935 * @param newSuperiorDN The new superior DN for the entry. It may be 936 * {@code null} if the entry is not to be moved below a 937 * new parent. 938 * 939 * @return The result of processing the modify DN operation. 940 * 941 * @throws LDAPException If the server rejects the modify DN request, or if 942 * a problem is encountered while sending the request 943 * or reading the response. 944 */ 945 public LDAPResult modifyDN(final String dn, final String newRDN, 946 final boolean deleteOldRDN, 947 final String newSuperiorDN) 948 throws LDAPException 949 { 950 return writePool.modifyDN(dn, newRDN, deleteOldRDN, newSuperiorDN); 951 } 952 953 954 955 /** 956 * Processes the provided modify DN request using a write connection from this 957 * connection pool. 958 * 959 * @param modifyDNRequest The modify DN request to be processed. It must 960 * not be {@code null}. 961 * 962 * @return The result of processing the modify DN operation. 963 * 964 * @throws LDAPException If the server rejects the modify DN request, or if 965 * a problem is encountered while sending the request 966 * or reading the response. 967 */ 968 public LDAPResult modifyDN(final ModifyDNRequest modifyDNRequest) 969 throws LDAPException 970 { 971 return writePool.modifyDN(modifyDNRequest); 972 } 973 974 975 976 /** 977 * Processes the provided modify DN request using a write connection from this 978 * connection pool. 979 * 980 * @param modifyDNRequest The modify DN request to be processed. It must 981 * not be {@code null}. 982 * 983 * @return The result of processing the modify DN operation. 984 * 985 * @throws LDAPException If the server rejects the modify DN request, or if 986 * a problem is encountered while sending the request 987 * or reading the response. 988 */ 989 public LDAPResult modifyDN(final ReadOnlyModifyDNRequest modifyDNRequest) 990 throws LDAPException 991 { 992 return writePool.modifyDN(modifyDNRequest); 993 } 994 995 996 997 /** 998 * Processes a search operation with the provided information using a read 999 * connection from this connection pool. The search result entries and 1000 * references will be collected internally and included in the 1001 * {@code SearchResult} object that is returned. 1002 * <BR><BR> 1003 * Note that if the search does not complete successfully, an 1004 * {@code LDAPSearchException} will be thrown In some cases, one or more 1005 * search result entries or references may have been returned before the 1006 * failure response is received. In this case, the 1007 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1008 * {@code getSearchEntries}, {@code getReferenceCount}, and 1009 * {@code getSearchReferences} may be used to obtain information about those 1010 * entries and references. 1011 * 1012 * @param baseDN The base DN for the search request. It must not be 1013 * {@code null}. 1014 * @param scope The scope that specifies the range of entries that 1015 * should be examined for the search. 1016 * @param filter The string representation of the filter to use to 1017 * identify matching entries. It must not be 1018 * {@code null}. 1019 * @param attributes The set of attributes that should be returned in 1020 * matching entries. It may be {@code null} or empty if 1021 * the default attribute set (all user attributes) is to 1022 * be requested. 1023 * 1024 * @return A search result object that provides information about the 1025 * processing of the search, including the set of matching entries 1026 * and search references returned by the server. 1027 * 1028 * @throws LDAPSearchException If the search does not complete successfully, 1029 * or if a problem is encountered while parsing 1030 * the provided filter string, sending the 1031 * request, or reading the response. If one 1032 * or more entries or references were returned 1033 * before the failure was encountered, then the 1034 * {@code LDAPSearchException} object may be 1035 * examined to obtain information about those 1036 * entries and/or references. 1037 */ 1038 public SearchResult search(final String baseDN, final SearchScope scope, 1039 final String filter, final String... attributes) 1040 throws LDAPSearchException 1041 { 1042 return readPool.search(baseDN, scope, filter, attributes); 1043 } 1044 1045 1046 1047 /** 1048 * Processes a search operation with the provided information using a read 1049 * connection from this connection pool. The search result entries and 1050 * references will be collected internally and included in the 1051 * {@code SearchResult} object that is returned. 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. 1061 * 1062 * @param baseDN The base DN for the search request. It must not be 1063 * {@code null}. 1064 * @param scope The scope that specifies the range of entries that 1065 * should be examined for the search. 1066 * @param filter The filter to use to identify matching entries. It 1067 * must not be {@code null}. 1068 * @param attributes The set of attributes that should be returned in 1069 * matching entries. It may be {@code null} or empty if 1070 * the default attribute set (all user attributes) is to 1071 * be requested. 1072 * 1073 * @return A search result object that provides information about the 1074 * processing of the search, including the set of matching entries 1075 * and search references returned by the server. 1076 * 1077 * @throws LDAPSearchException If the search does not complete successfully, 1078 * or if a problem is encountered while sending 1079 * the request or reading the response. If one 1080 * or more entries or references were returned 1081 * before the failure was encountered, then the 1082 * {@code LDAPSearchException} object may be 1083 * examined to obtain information about those 1084 * entries and/or references. 1085 */ 1086 public SearchResult search(final String baseDN, final SearchScope scope, 1087 final Filter filter, final String... attributes) 1088 throws LDAPSearchException 1089 { 1090 return readPool.search(baseDN, scope, filter, attributes); 1091 } 1092 1093 1094 1095 /** 1096 * Processes a search operation with the provided information using a read 1097 * connection from this connection pool. 1098 * <BR><BR> 1099 * Note that if the search does not complete successfully, an 1100 * {@code LDAPSearchException} will be thrown In some cases, one or more 1101 * search result entries or references may have been returned before the 1102 * failure response is received. In this case, the 1103 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1104 * {@code getSearchEntries}, {@code getReferenceCount}, and 1105 * {@code getSearchReferences} may be used to obtain information about those 1106 * entries and references (although if a search result listener was provided, 1107 * then it will have been used to make any entries and references available, 1108 * and they will not be available through the {@code getSearchEntries} and 1109 * {@code getSearchReferences} methods). 1110 * 1111 * @param searchResultListener The search result listener that should be 1112 * used to return results to the client. It may 1113 * be {@code null} if the search results should 1114 * be collected internally and returned in the 1115 * {@code SearchResult} object. 1116 * @param baseDN The base DN for the search request. It must 1117 * not be {@code null}. 1118 * @param scope The scope that specifies the range of entries 1119 * that should be examined for the search. 1120 * @param filter The string representation of the filter to 1121 * use to identify matching entries. It must 1122 * not be {@code null}. 1123 * @param attributes The set of attributes that should be returned 1124 * in matching entries. It may be {@code null} 1125 * or empty if the default attribute set (all 1126 * user attributes) is to be requested. 1127 * 1128 * @return A search result object that provides information about the 1129 * processing of the search, potentially including the set of 1130 * matching entries and search references returned by the server. 1131 * 1132 * @throws LDAPSearchException If the search does not complete successfully, 1133 * or if a problem is encountered while parsing 1134 * the provided filter string, sending the 1135 * request, or reading the response. If one 1136 * or more entries or references were returned 1137 * before the failure was encountered, then the 1138 * {@code LDAPSearchException} object may be 1139 * examined to obtain information about those 1140 * entries and/or references. 1141 */ 1142 public SearchResult search(final SearchResultListener searchResultListener, 1143 final String baseDN, final SearchScope scope, 1144 final String filter, final String... attributes) 1145 throws LDAPSearchException 1146 { 1147 return readPool.search(searchResultListener, baseDN, scope, filter, 1148 attributes); 1149 } 1150 1151 1152 1153 /** 1154 * Processes a search operation with the provided information using a read 1155 * connection from this connection pool. 1156 * <BR><BR> 1157 * Note that if the search does not complete successfully, an 1158 * {@code LDAPSearchException} will be thrown In some cases, one or more 1159 * search result entries or references may have been returned before the 1160 * failure response is received. In this case, the 1161 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1162 * {@code getSearchEntries}, {@code getReferenceCount}, and 1163 * {@code getSearchReferences} may be used to obtain information about those 1164 * entries and references (although if a search result listener was provided, 1165 * then it will have been used to make any entries and references available, 1166 * and they will not be available through the {@code getSearchEntries} and 1167 * {@code getSearchReferences} methods). 1168 * 1169 * @param searchResultListener The search result listener that should be 1170 * used to return results to the client. It may 1171 * be {@code null} if the search results should 1172 * be collected internally and returned in the 1173 * {@code SearchResult} object. 1174 * @param baseDN The base DN for the search request. It must 1175 * not be {@code null}. 1176 * @param scope The scope that specifies the range of entries 1177 * that should be examined for the search. 1178 * @param filter The filter to use to identify matching 1179 * entries. It must not be {@code null}. 1180 * @param attributes The set of attributes that should be returned 1181 * in matching entries. It may be {@code null} 1182 * or empty if the default attribute set (all 1183 * user attributes) is to be requested. 1184 * 1185 * @return A search result object that provides information about the 1186 * processing of the search, potentially including the set of 1187 * matching entries and search references returned by the server. 1188 * 1189 * @throws LDAPSearchException If the search does not complete successfully, 1190 * or if a problem is encountered while sending 1191 * the request or reading the response. If one 1192 * or more entries or references were returned 1193 * before the failure was encountered, then the 1194 * {@code LDAPSearchException} object may be 1195 * examined to obtain information about those 1196 * entries and/or references. 1197 */ 1198 public SearchResult search(final SearchResultListener searchResultListener, 1199 final String baseDN, final SearchScope scope, 1200 final Filter filter, final String... attributes) 1201 throws LDAPSearchException 1202 { 1203 return readPool.search(searchResultListener, baseDN, scope, filter, 1204 attributes); 1205 } 1206 1207 1208 1209 /** 1210 * Processes a search operation with the provided information using a read 1211 * connection from this connection pool. The search result entries and 1212 * references will be collected internally and included in the 1213 * {@code SearchResult} object that is returned. 1214 * <BR><BR> 1215 * Note that if the search does not complete successfully, an 1216 * {@code LDAPSearchException} will be thrown In some cases, one or more 1217 * search result entries or references may have been returned before the 1218 * failure response is received. In this case, the 1219 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1220 * {@code getSearchEntries}, {@code getReferenceCount}, and 1221 * {@code getSearchReferences} may be used to obtain information about those 1222 * entries and references. 1223 * 1224 * @param baseDN The base DN for the search request. It must not be 1225 * {@code null}. 1226 * @param scope The scope that specifies the range of entries that 1227 * should be examined for the search. 1228 * @param derefPolicy The dereference policy the server should use for any 1229 * aliases encountered while processing the search. 1230 * @param sizeLimit The maximum number of entries that the server should 1231 * return for the search. A value of zero indicates that 1232 * there should be no limit. 1233 * @param timeLimit The maximum length of time in seconds that the server 1234 * should spend processing this search request. A value 1235 * of zero indicates that there should be no limit. 1236 * @param typesOnly Indicates whether to return only attribute names in 1237 * matching entries, or both attribute names and values. 1238 * @param filter The string representation of the filter to use to 1239 * identify matching entries. It must not be 1240 * {@code null}. 1241 * @param attributes The set of attributes that should be returned in 1242 * matching entries. It may be {@code null} or empty if 1243 * the default attribute set (all user attributes) is to 1244 * be requested. 1245 * 1246 * @return A search result object that provides information about the 1247 * processing of the search, including the set of matching entries 1248 * and search references returned by the server. 1249 * 1250 * @throws LDAPSearchException If the search does not complete successfully, 1251 * or if a problem is encountered while parsing 1252 * the provided filter string, sending the 1253 * request, or reading the response. If one 1254 * or more entries or references were returned 1255 * before the failure was encountered, then the 1256 * {@code LDAPSearchException} object may be 1257 * examined to obtain information about those 1258 * entries and/or references. 1259 */ 1260 public SearchResult search(final String baseDN, final SearchScope scope, 1261 final DereferencePolicy derefPolicy, 1262 final int sizeLimit, final int timeLimit, 1263 final boolean typesOnly, final String filter, 1264 final String... attributes) 1265 throws LDAPSearchException 1266 { 1267 return readPool.search(baseDN, scope, derefPolicy, sizeLimit, timeLimit, 1268 typesOnly, filter, attributes); 1269 } 1270 1271 1272 1273 /** 1274 * Processes a search operation with the provided information using a read 1275 * connection from this connection pool. The search result entries and 1276 * references will be collected internally and included in the 1277 * {@code SearchResult} object that is returned. 1278 * <BR><BR> 1279 * Note that if the search does not complete successfully, an 1280 * {@code LDAPSearchException} will be thrown In some cases, one or more 1281 * search result entries or references may have been returned before the 1282 * failure response is received. In this case, the 1283 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1284 * {@code getSearchEntries}, {@code getReferenceCount}, and 1285 * {@code getSearchReferences} may be used to obtain information about those 1286 * entries and references. 1287 * 1288 * @param baseDN The base DN for the search request. It must not be 1289 * {@code null}. 1290 * @param scope The scope that specifies the range of entries that 1291 * should be examined for the search. 1292 * @param derefPolicy The dereference policy the server should use for any 1293 * aliases encountered while processing the search. 1294 * @param sizeLimit The maximum number of entries that the server should 1295 * return for the search. A value of zero indicates that 1296 * there should be no limit. 1297 * @param timeLimit The maximum length of time in seconds that the server 1298 * should spend processing this search request. A value 1299 * of zero indicates that there should be no limit. 1300 * @param typesOnly Indicates whether to return only attribute names in 1301 * matching entries, or both attribute names and values. 1302 * @param filter The filter to use to identify matching entries. It 1303 * must not be {@code null}. 1304 * @param attributes The set of attributes that should be returned in 1305 * matching entries. It may be {@code null} or empty if 1306 * the default attribute set (all user attributes) is to 1307 * be requested. 1308 * 1309 * @return A search result object that provides information about the 1310 * processing of the search, including the set of matching entries 1311 * and search references returned by the server. 1312 * 1313 * @throws LDAPSearchException If the search does not complete successfully, 1314 * or if a problem is encountered while sending 1315 * the request or reading the response. If one 1316 * or more entries or references were returned 1317 * before the failure was encountered, then the 1318 * {@code LDAPSearchException} object may be 1319 * examined to obtain information about those 1320 * entries and/or references. 1321 */ 1322 public SearchResult search(final String baseDN, final SearchScope scope, 1323 final DereferencePolicy derefPolicy, 1324 final int sizeLimit, final int timeLimit, 1325 final boolean typesOnly, final Filter filter, 1326 final String... attributes) 1327 throws LDAPSearchException 1328 { 1329 return readPool.search(baseDN, scope, derefPolicy, sizeLimit, timeLimit, 1330 typesOnly, filter, attributes); 1331 } 1332 1333 1334 1335 /** 1336 * Processes a search operation with the provided information using a read 1337 * connection from this connection pool. 1338 * <BR><BR> 1339 * Note that if the search does not complete successfully, an 1340 * {@code LDAPSearchException} will be thrown In some cases, one or more 1341 * search result entries or references may have been returned before the 1342 * failure response is received. In this case, the 1343 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1344 * {@code getSearchEntries}, {@code getReferenceCount}, and 1345 * {@code getSearchReferences} may be used to obtain information about those 1346 * entries and references (although if a search result listener was provided, 1347 * then it will have been used to make any entries and references available, 1348 * and they will not be available through the {@code getSearchEntries} and 1349 * {@code getSearchReferences} methods). 1350 * 1351 * @param searchResultListener The search result listener that should be 1352 * used to return results to the client. It may 1353 * be {@code null} if the search results should 1354 * be collected internally and returned in the 1355 * {@code SearchResult} object. 1356 * @param baseDN The base DN for the search request. It must 1357 * not be {@code null}. 1358 * @param scope The scope that specifies the range of entries 1359 * that should be examined for the search. 1360 * @param derefPolicy The dereference policy the server should use 1361 * for any aliases encountered while processing 1362 * the search. 1363 * @param sizeLimit The maximum number of entries that the server 1364 * should return for the search. A value of 1365 * zero indicates that there should be no limit. 1366 * @param timeLimit The maximum length of time in seconds that 1367 * the server should spend processing this 1368 * search request. A value of zero indicates 1369 * that there should be no limit. 1370 * @param typesOnly Indicates whether to return only attribute 1371 * names in matching entries, or both attribute 1372 * names and values. 1373 * @param filter The string representation of the filter to 1374 * use to identify matching entries. It must 1375 * not be {@code null}. 1376 * @param attributes The set of attributes that should be returned 1377 * in matching entries. It may be {@code null} 1378 * or empty if the default attribute set (all 1379 * user attributes) is to be requested. 1380 * 1381 * @return A search result object that provides information about the 1382 * processing of the search, potentially including the set of 1383 * matching entries and search references returned by the server. 1384 * 1385 * @throws LDAPSearchException If the search does not complete successfully, 1386 * or if a problem is encountered while parsing 1387 * the provided filter string, sending the 1388 * request, or reading the response. If one 1389 * or more entries or references were returned 1390 * before the failure was encountered, then the 1391 * {@code LDAPSearchException} object may be 1392 * examined to obtain information about those 1393 * entries and/or references. 1394 */ 1395 public SearchResult search(final SearchResultListener searchResultListener, 1396 final String baseDN, final SearchScope scope, 1397 final DereferencePolicy derefPolicy, 1398 final int sizeLimit, final int timeLimit, 1399 final boolean typesOnly, final String filter, 1400 final String... attributes) 1401 throws LDAPSearchException 1402 { 1403 return readPool.search(searchResultListener, baseDN, scope, derefPolicy, 1404 sizeLimit, timeLimit, typesOnly, filter, attributes); 1405 } 1406 1407 1408 1409 /** 1410 * Processes a search operation with the provided information using a read 1411 * connection from this connection pool. 1412 * <BR><BR> 1413 * Note that if the search does not complete successfully, an 1414 * {@code LDAPSearchException} will be thrown In some cases, one or more 1415 * search result entries or references may have been returned before the 1416 * failure response is received. In this case, the 1417 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1418 * {@code getSearchEntries}, {@code getReferenceCount}, and 1419 * {@code getSearchReferences} may be used to obtain information about those 1420 * entries and references (although if a search result listener was provided, 1421 * then it will have been used to make any entries and references available, 1422 * and they will not be available through the {@code getSearchEntries} and 1423 * {@code getSearchReferences} methods). 1424 * 1425 * @param searchResultListener The search result listener that should be 1426 * used to return results to the client. It may 1427 * be {@code null} if the search results should 1428 * be collected internally and returned in the 1429 * {@code SearchResult} object. 1430 * @param baseDN The base DN for the search request. It must 1431 * not be {@code null}. 1432 * @param scope The scope that specifies the range of entries 1433 * that should be examined for the search. 1434 * @param derefPolicy The dereference policy the server should use 1435 * for any aliases encountered while processing 1436 * the search. 1437 * @param sizeLimit The maximum number of entries that the server 1438 * should return for the search. A value of 1439 * zero indicates that there should be no limit. 1440 * @param timeLimit The maximum length of time in seconds that 1441 * the server should spend processing this 1442 * search request. A value of zero indicates 1443 * that there should be no limit. 1444 * @param typesOnly Indicates whether to return only attribute 1445 * names in matching entries, or both attribute 1446 * names and values. 1447 * @param filter The filter to use to identify matching 1448 * entries. It must not be {@code null}. 1449 * @param attributes The set of attributes that should be returned 1450 * in matching entries. It may be {@code null} 1451 * or empty if the default attribute set (all 1452 * user attributes) is to be requested. 1453 * 1454 * @return A search result object that provides information about the 1455 * processing of the search, potentially including the set of 1456 * matching entries and search references returned by the server. 1457 * 1458 * @throws LDAPSearchException If the search does not complete successfully, 1459 * or if a problem is encountered while sending 1460 * the request or reading the response. If one 1461 * or more entries or references were returned 1462 * before the failure was encountered, then the 1463 * {@code LDAPSearchException} object may be 1464 * examined to obtain information about those 1465 * entries and/or references. 1466 */ 1467 public SearchResult search(final SearchResultListener searchResultListener, 1468 final String baseDN, final SearchScope scope, 1469 final DereferencePolicy derefPolicy, 1470 final int sizeLimit, final int timeLimit, 1471 final boolean typesOnly, final Filter filter, 1472 final String... attributes) 1473 throws LDAPSearchException 1474 { 1475 return readPool.search(searchResultListener, baseDN, scope, derefPolicy, 1476 sizeLimit, timeLimit, typesOnly, filter, attributes); 1477 } 1478 1479 1480 1481 /** 1482 * Processes the provided search request using a read connection from this 1483 * connection pool. 1484 * <BR><BR> 1485 * Note that if the search does not complete successfully, an 1486 * {@code LDAPSearchException} will be thrown In some cases, one or more 1487 * search result entries or references may have been returned before the 1488 * failure response is received. In this case, the 1489 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1490 * {@code getSearchEntries}, {@code getReferenceCount}, and 1491 * {@code getSearchReferences} may be used to obtain information about those 1492 * entries and references (although if a search result listener was provided, 1493 * then it will have been used to make any entries and references available, 1494 * and they will not be available through the {@code getSearchEntries} and 1495 * {@code getSearchReferences} methods). 1496 * 1497 * @param searchRequest The search request to be processed. It must not be 1498 * {@code null}. 1499 * 1500 * @return A search result object that provides information about the 1501 * processing of the search, potentially including the set of 1502 * matching entries and search references returned by the server. 1503 * 1504 * @throws LDAPSearchException If the search does not complete successfully, 1505 * or if a problem is encountered while sending 1506 * the request or reading the response. If one 1507 * or more entries or references were returned 1508 * before the failure was encountered, then the 1509 * {@code LDAPSearchException} object may be 1510 * examined to obtain information about those 1511 * entries and/or references. 1512 */ 1513 public SearchResult search(final SearchRequest searchRequest) 1514 throws LDAPSearchException 1515 { 1516 return readPool.search(searchRequest); 1517 } 1518 1519 1520 1521 /** 1522 * Processes the provided search request using a read connection from this 1523 * connection pool. 1524 * <BR><BR> 1525 * Note that if the search does not complete successfully, an 1526 * {@code LDAPSearchException} will be thrown In some cases, one or more 1527 * search result entries or references may have been returned before the 1528 * failure response is received. In this case, the 1529 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1530 * {@code getSearchEntries}, {@code getReferenceCount}, and 1531 * {@code getSearchReferences} may be used to obtain information about those 1532 * entries and references (although if a search result listener was provided, 1533 * then it will have been used to make any entries and references available, 1534 * and they will not be available through the {@code getSearchEntries} and 1535 * {@code getSearchReferences} methods). 1536 * 1537 * @param searchRequest The search request to be processed. It must not be 1538 * {@code null}. 1539 * 1540 * @return A search result object that provides information about the 1541 * processing of the search, potentially including the set of 1542 * matching entries and search references returned by the server. 1543 * 1544 * @throws LDAPSearchException If the search does not complete successfully, 1545 * or if a problem is encountered while sending 1546 * the request or reading the response. If one 1547 * or more entries or references were returned 1548 * before the failure was encountered, then the 1549 * {@code LDAPSearchException} object may be 1550 * examined to obtain information about those 1551 * entries and/or references. 1552 */ 1553 public SearchResult search(final ReadOnlySearchRequest searchRequest) 1554 throws LDAPSearchException 1555 { 1556 return readPool.search(searchRequest); 1557 } 1558 1559 1560 1561 /** 1562 * Processes a search operation with the provided information using a read 1563 * connection from this connection pool. It is expected that at most one 1564 * entry will be returned from the search, and that no additional content from 1565 * the successful search result (e.g., diagnostic message or response 1566 * controls) are needed. 1567 * <BR><BR> 1568 * Note that if the search does not complete successfully, an 1569 * {@code LDAPSearchException} will be thrown In some cases, one or more 1570 * search result entries or references may have been returned before the 1571 * failure response is received. In this case, the 1572 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1573 * {@code getSearchEntries}, {@code getReferenceCount}, and 1574 * {@code getSearchReferences} may be used to obtain information about those 1575 * entries and references. 1576 * 1577 * @param baseDN The base DN for the search request. It must not be 1578 * {@code null}. 1579 * @param scope The scope that specifies the range of entries that 1580 * should be examined for the search. 1581 * @param filter The string representation of the filter to use to 1582 * identify matching entries. It must not be 1583 * {@code null}. 1584 * @param attributes The set of attributes that should be returned in 1585 * matching entries. It may be {@code null} or empty if 1586 * the default attribute set (all user attributes) is to 1587 * be requested. 1588 * 1589 * @return The entry that was returned from the search, or {@code null} if no 1590 * entry was returned or the base entry does not exist. 1591 * 1592 * @throws LDAPSearchException If the search does not complete successfully, 1593 * if more than a single entry is returned, or 1594 * if a problem is encountered while parsing the 1595 * provided filter string, sending the request, 1596 * or reading the response. If one or more 1597 * entries or references were returned before 1598 * the failure was encountered, then the 1599 * {@code LDAPSearchException} object may be 1600 * examined to obtain information about those 1601 * entries and/or references. 1602 */ 1603 public SearchResultEntry searchForEntry(final String baseDN, 1604 final SearchScope scope, 1605 final String filter, 1606 final String... attributes) 1607 throws LDAPSearchException 1608 { 1609 return readPool.searchForEntry(baseDN, scope, filter, attributes); 1610 } 1611 1612 1613 1614 /** 1615 * Processes a search operation with the provided information using a read 1616 * connection from this connection pool. It is expected that at most one 1617 * entry will be returned from the search, and that no additional content from 1618 * the successful search result (e.g., diagnostic message or response 1619 * controls) are needed. 1620 * <BR><BR> 1621 * Note that if the search does not complete successfully, an 1622 * {@code LDAPSearchException} will be thrown In some cases, one or more 1623 * search result entries or references may have been returned before the 1624 * failure response is received. In this case, the 1625 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1626 * {@code getSearchEntries}, {@code getReferenceCount}, and 1627 * {@code getSearchReferences} may be used to obtain information about those 1628 * entries and references. 1629 * 1630 * @param baseDN The base DN for the search request. It must not be 1631 * {@code null}. 1632 * @param scope The scope that specifies the range of entries that 1633 * should be examined for the search. 1634 * @param filter The string representation of the filter to use to 1635 * identify matching entries. It must not be 1636 * {@code null}. 1637 * @param attributes The set of attributes that should be returned in 1638 * matching entries. It may be {@code null} or empty if 1639 * the default attribute set (all user attributes) is to 1640 * be requested. 1641 * 1642 * @return The entry that was returned from the search, or {@code null} if no 1643 * entry was returned or the base entry does not exist. 1644 * 1645 * @throws LDAPSearchException If the search does not complete successfully, 1646 * if more than a single entry is returned, or 1647 * if a problem is encountered while parsing the 1648 * provided filter string, sending the request, 1649 * or reading the response. If one or more 1650 * entries or references were returned before 1651 * the failure was encountered, then the 1652 * {@code LDAPSearchException} object may be 1653 * examined to obtain information about those 1654 * entries and/or references. 1655 */ 1656 public SearchResultEntry searchForEntry(final String baseDN, 1657 final SearchScope scope, 1658 final Filter filter, 1659 final String... attributes) 1660 throws LDAPSearchException 1661 { 1662 return readPool.searchForEntry(baseDN, scope, filter, attributes); 1663 } 1664 1665 1666 1667 /** 1668 * Processes a search operation with the provided information using a read 1669 * connection from this connection pool. It is expected that at most one 1670 * entry will be returned from the search, and that no additional content from 1671 * the successful search result (e.g., diagnostic message or response 1672 * controls) are needed. 1673 * <BR><BR> 1674 * Note that if the search does not complete successfully, an 1675 * {@code LDAPSearchException} will be thrown In some cases, one or more 1676 * search result entries or references may have been returned before the 1677 * failure response is received. In this case, the 1678 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1679 * {@code getSearchEntries}, {@code getReferenceCount}, and 1680 * {@code getSearchReferences} may be used to obtain information about those 1681 * entries and references. 1682 * 1683 * @param baseDN The base DN for the search request. It must not be 1684 * {@code null}. 1685 * @param scope The scope that specifies the range of entries that 1686 * should be examined for the search. 1687 * @param derefPolicy The dereference policy the server should use for any 1688 * aliases encountered while processing the search. 1689 * @param timeLimit The maximum length of time in seconds that the server 1690 * should spend processing this search request. A value 1691 * of zero indicates that there should be no limit. 1692 * @param typesOnly Indicates whether to return only attribute names in 1693 * matching entries, or both attribute names and values. 1694 * @param filter The string representation of the filter to use to 1695 * identify matching entries. It must not be 1696 * {@code null}. 1697 * @param attributes The set of attributes that should be returned in 1698 * matching entries. It may be {@code null} or empty if 1699 * the default attribute set (all user attributes) is to 1700 * be requested. 1701 * 1702 * @return The entry that was returned from the search, or {@code null} if no 1703 * entry was returned or the base entry does not exist. 1704 * 1705 * @throws LDAPSearchException If the search does not complete successfully, 1706 * if more than a single entry is returned, or 1707 * if a problem is encountered while parsing the 1708 * provided filter string, sending the request, 1709 * or reading the response. If one or more 1710 * entries or references were returned before 1711 * the failure was encountered, then the 1712 * {@code LDAPSearchException} object may be 1713 * examined to obtain information about those 1714 * entries and/or references. 1715 */ 1716 public SearchResultEntry searchForEntry(final String baseDN, 1717 final SearchScope scope, 1718 final DereferencePolicy derefPolicy, 1719 final int timeLimit, 1720 final boolean typesOnly, 1721 final String filter, 1722 final String... attributes) 1723 throws LDAPSearchException 1724 { 1725 return readPool.searchForEntry(baseDN, scope, derefPolicy, timeLimit, 1726 typesOnly, filter, attributes); 1727 } 1728 1729 1730 1731 /** 1732 * Processes a search operation with the provided information using a read 1733 * connection from this connection pool. It is expected that at most one 1734 * entry will be returned from the search, and that no additional content from 1735 * the successful search result (e.g., diagnostic message or response 1736 * controls) are needed. 1737 * <BR><BR> 1738 * Note that if the search does not complete successfully, an 1739 * {@code LDAPSearchException} will be thrown In some cases, one or more 1740 * search result entries or references may have been returned before the 1741 * failure response is received. In this case, the 1742 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1743 * {@code getSearchEntries}, {@code getReferenceCount}, and 1744 * {@code getSearchReferences} may be used to obtain information about those 1745 * entries and references. 1746 * 1747 * @param baseDN The base DN for the search request. It must not be 1748 * {@code null}. 1749 * @param scope The scope that specifies the range of entries that 1750 * should be examined for the search. 1751 * @param derefPolicy The dereference policy the server should use for any 1752 * aliases encountered while processing the search. 1753 * @param timeLimit The maximum length of time in seconds that the server 1754 * should spend processing this search request. A value 1755 * of zero indicates that there should be no limit. 1756 * @param typesOnly Indicates whether to return only attribute names in 1757 * matching entries, or both attribute names and values. 1758 * @param filter The filter to use to identify matching entries. It 1759 * must not be {@code null}. 1760 * @param attributes The set of attributes that should be returned in 1761 * matching entries. It may be {@code null} or empty if 1762 * the default attribute set (all user attributes) is to 1763 * be requested. 1764 * 1765 * @return The entry that was returned from the search, or {@code null} if no 1766 * entry was returned or the base entry does not exist. 1767 * 1768 * @throws LDAPSearchException If the search does not complete successfully, 1769 * if more than a single entry is returned, or 1770 * if a problem is encountered while parsing the 1771 * provided filter string, sending the request, 1772 * or reading the response. If one or more 1773 * entries or references were returned before 1774 * the failure was encountered, then the 1775 * {@code LDAPSearchException} object may be 1776 * examined to obtain information about those 1777 * entries and/or references. 1778 */ 1779 public SearchResultEntry searchForEntry(final String baseDN, 1780 final SearchScope scope, 1781 final DereferencePolicy derefPolicy, 1782 final int timeLimit, 1783 final boolean typesOnly, 1784 final Filter filter, 1785 final String... attributes) 1786 throws LDAPSearchException 1787 { 1788 return readPool.searchForEntry(baseDN, scope, derefPolicy, timeLimit, 1789 typesOnly, filter, attributes); 1790 } 1791 1792 1793 1794 /** 1795 * Processes a search operation with the provided information using a read 1796 * connection from this connection pool. It is expected that at most one 1797 * entry will be returned from the search, and that no additional content from 1798 * the successful search result (e.g., diagnostic message or response 1799 * controls) are needed. 1800 * <BR><BR> 1801 * Note that if the search does not complete successfully, an 1802 * {@code LDAPSearchException} will be thrown In some cases, one or more 1803 * search result entries or references may have been returned before the 1804 * failure response is received. In this case, the 1805 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1806 * {@code getSearchEntries}, {@code getReferenceCount}, and 1807 * {@code getSearchReferences} may be used to obtain information about those 1808 * entries and references. 1809 * 1810 * @param searchRequest The search request to be processed. If it is 1811 * configured with a search result listener or a size 1812 * limit other than one, then the provided request will 1813 * be duplicated with the appropriate settings. 1814 * 1815 * @return The entry that was returned from the search, or {@code null} if no 1816 * entry was returned or the base entry does not exist. 1817 * 1818 * @throws LDAPSearchException If the search does not complete successfully, 1819 * if more than a single entry is returned, or 1820 * if a problem is encountered while parsing the 1821 * provided filter string, sending the request, 1822 * or reading the response. If one or more 1823 * entries or references were returned before 1824 * the failure was encountered, then the 1825 * {@code LDAPSearchException} object may be 1826 * examined to obtain information about those 1827 * entries and/or references. 1828 */ 1829 public SearchResultEntry searchForEntry(final SearchRequest searchRequest) 1830 throws LDAPSearchException 1831 { 1832 return readPool.searchForEntry(searchRequest); 1833 } 1834 1835 1836 1837 /** 1838 * Processes a search operation with the provided information using a read 1839 * connection from this connection pool. It is expected that at most one 1840 * entry will be returned from the search, and that no additional content from 1841 * the successful search result (e.g., diagnostic message or response 1842 * controls) are needed. 1843 * <BR><BR> 1844 * Note that if the search does not complete successfully, an 1845 * {@code LDAPSearchException} will be thrown In some cases, one or more 1846 * search result entries or references may have been returned before the 1847 * failure response is received. In this case, the 1848 * {@code LDAPSearchException} methods like {@code getEntryCount}, 1849 * {@code getSearchEntries}, {@code getReferenceCount}, and 1850 * {@code getSearchReferences} may be used to obtain information about those 1851 * entries and references. 1852 * 1853 * @param searchRequest The search request to be processed. If it is 1854 * configured with a search result listener or a size 1855 * limit other than one, then the provided request will 1856 * be duplicated with the appropriate settings. 1857 * 1858 * @return The entry that was returned from the search, or {@code null} if no 1859 * entry was returned or the base entry does not exist. 1860 * 1861 * @throws LDAPSearchException If the search does not complete successfully, 1862 * if more than a single entry is returned, or 1863 * if a problem is encountered while parsing the 1864 * provided filter string, sending the request, 1865 * or reading the response. If one or more 1866 * entries or references were returned before 1867 * the failure was encountered, then the 1868 * {@code LDAPSearchException} object may be 1869 * examined to obtain information about those 1870 * entries and/or references. 1871 */ 1872 public SearchResultEntry searchForEntry( 1873 final ReadOnlySearchRequest searchRequest) 1874 throws LDAPSearchException 1875 { 1876 return readPool.searchForEntry(searchRequest); 1877 } 1878 1879 1880 1881 /** 1882 * Closes this connection pool in the event that it becomes unreferenced. 1883 * 1884 * @throws Throwable If an unexpected problem occurs. 1885 */ 1886 @Override() 1887 protected void finalize() 1888 throws Throwable 1889 { 1890 super.finalize(); 1891 1892 close(); 1893 } 1894}