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