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