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