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