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