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