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