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