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