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