001    /*
002     * Copyright 2009-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2009-2015 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     */
021    package com.unboundid.ldap.sdk;
022    
023    
024    
025    import java.util.Collection;
026    import java.util.List;
027    
028    import com.unboundid.ldap.sdk.schema.Schema;
029    import com.unboundid.ldif.LDIFException;
030    import com.unboundid.util.ThreadSafety;
031    import com.unboundid.util.ThreadSafetyLevel;
032    
033    import static com.unboundid.util.Debug.*;
034    import 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)
058    public 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    }