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