From f2160f4bd1c8ac67e5a86a6710d431e8932877f9 Mon Sep 17 00:00:00 2001
From: matthew_swift <matthew_swift@localhost>
Date: Fri, 28 May 2010 11:47:51 +0000
Subject: [PATCH] Synchronize SDK on java.net with internal repository.
---
sdk/src/org/opends/sdk/AsynchronousConnection.java | 670 ++++++++++++++++++++++++++++++++++++-------------------
1 files changed, 438 insertions(+), 232 deletions(-)
diff --git a/sdk/src/org/opends/sdk/AsynchronousConnection.java b/sdk/src/org/opends/sdk/AsynchronousConnection.java
index 8e0fb1e..5651403 100644
--- a/sdk/src/org/opends/sdk/AsynchronousConnection.java
+++ b/sdk/src/org/opends/sdk/AsynchronousConnection.java
@@ -33,31 +33,27 @@
import java.util.Collection;
import org.opends.sdk.requests.*;
-import org.opends.sdk.responses.BindResult;
-import org.opends.sdk.responses.CompareResult;
-import org.opends.sdk.responses.Result;
-import org.opends.sdk.responses.SearchResultEntry;
+import org.opends.sdk.responses.*;
import org.opends.sdk.schema.Schema;
/**
- * An asynchronous connection with a Directory Server over which read
- * and update operations may be performed. See RFC 4511 for the LDAPv3
- * protocol specification and more information about the types of
- * operations defined in LDAP.
+ * An asynchronous connection with a Directory Server over which read and update
+ * operations may be performed. See RFC 4511 for the LDAPv3 protocol
+ * specification and more information about the types of operations defined in
+ * LDAP.
* <p>
* <h3>Operation processing</h3>
* <p>
- * All operations are performed asynchronously and return a
- * {@link FutureResult} or sub-type thereof which can be used for
- * retrieving the result using the {@link FutureResult#get} method.
- * Operation failures, for whatever reason, are signalled by the
- * {@link FutureResult#get()} method throwing an
+ * All operations are performed asynchronously and return a {@link FutureResult}
+ * or sub-type thereof which can be used for retrieving the result using the
+ * {@link FutureResult#get} method. Operation failures, for whatever reason, are
+ * signalled by the {@link FutureResult#get()} method throwing an
* {@link ErrorResultException}.
* <p>
- * Synchronous operations are easily simulated by immediately getting
- * the result:
+ * Synchronous operations are easily simulated by immediately getting the
+ * result:
*
* <pre>
* Connection connection = ...;
@@ -83,8 +79,8 @@
* future2.get();
* </pre>
*
- * More complex client applications can take advantage of a fully
- * asynchronous event driven design using {@link ResultHandler}s:
+ * More complex client applications can take advantage of a fully asynchronous
+ * event driven design using {@link ResultHandler}s:
*
* <pre>
* Connection connection = ...;
@@ -98,90 +94,104 @@
* <h3>Closing connections</h3>
* <p>
* Applications must ensure that a connection is closed by calling
- * {@link #close()} even if a fatal error occurs on the connection. Once
- * a connection has been closed by the client application, any attempts
- * to continue to use the connection will result in an
- * {@link IllegalStateException} being thrown. Note that, if a fatal
- * error is encountered on the connection, then the application can
- * continue to use the connection. In this case all requests subsequent
- * to the failure will fail with an appropriate
- * {@link ErrorResultException} when their result is retrieved.
+ * {@link #close()} even if a fatal error occurs on the connection. Once a
+ * connection has been closed by the client application, any attempts to
+ * continue to use the connection will result in an
+ * {@link IllegalStateException} being thrown. Note that, if a fatal error is
+ * encountered on the connection, then the application can continue to use the
+ * connection. In this case all requests subsequent to the failure will fail
+ * with an appropriate {@link ErrorResultException} when their result is
+ * retrieved.
* <p>
* <h3>Event notification</h3>
* <p>
- * Applications can choose to be notified when a connection is closed by
- * the application, receives an unsolicited notification, or experiences
- * a fatal error by registering a {@link ConnectionEventListener} with
- * the connection using the {@link #addConnectionEventListener} method.
- * <p>
- * <h3>TO DO</h3>
- * <p>
- * <ul>
- * <li>do we need isClosed() and isValid()?
- * <li>do we need connection event notification of client close? JDBC
- * and JCA have this functionality in their pooled (managed) connection
- * APIs. We need some form of event notification at the app level for
- * unsolicited notifications.
- * <li>method for performing update operation (e.g. LDIF change
- * records).
- * <li>should unsupported methods throw UnsupportedOperationException or
- * throw an ErrorResultException using an UnwillingToPerform result code
- * (or something similar)?
- * <li>Implementations should indicate whether or not they are thread
- * safe and support concurrent requests.
- * </ul>
+ * Applications can choose to be notified when a connection is closed by the
+ * application, receives an unsolicited notification, or experiences a fatal
+ * error by registering a {@link ConnectionEventListener} with the connection
+ * using the {@link #addConnectionEventListener} method.
*
- * @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 -
- * Lightweight Directory Access Protocol (LDAP): The Protocol </a>
+ * @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 - Lightweight
+ * Directory Access Protocol (LDAP): The Protocol </a>
*/
public interface AsynchronousConnection extends Closeable
{
/**
- * Abandons the unfinished operation identified in the provided
- * abandon request.
+ * Abandons the unfinished operation identified in the provided abandon
+ * request.
* <p>
- * <b>Note:</b> a more convenient approach to abandoning unfinished
- * operations is provided via the {@link FutureResult#cancel(boolean)}
- * method.
+ * Since abandon requests do not have a response, invoking the method {@code
+ * get()} on the returned future will not block, nor return anything (it is
+ * {@code Void}), but may throw an exception if a problem occurred while
+ * sending the abandon request.
+ * <p>
+ * <b>Note:</b> a more convenient approach to abandoning unfinished operations
+ * is provided via the {@link FutureResult#cancel(boolean)} method.
*
* @param request
* The request identifying the operation to be abandoned.
+ * @return An future whose result is {@code Void}.
* @throws UnsupportedOperationException
* If this connection does not support abandon operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
- void abandon(AbandonRequest request)
+ FutureResult<Void> abandon(AbandonRequest request)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
/**
- * Adds an entry to the Directory Server using the provided add
- * request.
+ * Adds an entry to the Directory Server using the provided add request. Any
+ * intermediate responses will be ignored.
*
* @param request
* The add request.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support add operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<Result> add(AddRequest request, ResultHandler<Result> handler)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
+
+
+
+ /**
+ * Adds an entry to the Directory Server using the provided add request.
+ *
+ * @param request
+ * The add request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support add operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult<Result> add(AddRequest request,
- ResultHandler<Result> handler)
+ ResultHandler<Result> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
@@ -189,15 +199,15 @@
/**
* Registers the provided connection event listener so that it will be
- * notified when this connection is closed by the application,
- * receives an unsolicited notification, or experiences a fatal error.
+ * notified when this connection is closed by the application, receives an
+ * unsolicited notification, or experiences a fatal error.
*
* @param listener
- * The listener which wants to be notified when events occur
- * on this connection.
+ * The listener which wants to be notified when events occur on this
+ * connection.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If the {@code listener} was {@code null}.
*/
@@ -207,21 +217,20 @@
/**
- * Authenticates to the Directory Server using the provided bind
- * request.
+ * Authenticates to the Directory Server using the provided bind request. Any
+ * intermediate responses will be ignored.
*
* @param request
* The bind request.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support bind operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
@@ -233,14 +242,42 @@
/**
- * Releases any resources associated with this connection. For
- * physical connections to a Directory Server this will mean that an
- * unbind request is sent and the underlying socket is closed.
+ * Authenticates to the Directory Server using the provided bind request.
+ *
+ * @param request
+ * The bind request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support bind operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<BindResult> bind(BindRequest request,
+ ResultHandler<? super BindResult> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
+
+
+
+ /**
+ * Releases any resources associated with this connection. For physical
+ * connections to a Directory Server this will mean that an unbind request is
+ * sent and the underlying socket is closed.
* <p>
- * Other connection implementations may behave differently, and may
- * choose not to send an unbind request if its use is inappropriate
- * (for example a pooled connection will be released and returned to
- * its connection pool without ever issuing an unbind request).
+ * Other connection implementations may behave differently, and may choose not
+ * to send an unbind request if its use is inappropriate (for example a pooled
+ * connection will be released and returned to its connection pool without
+ * ever issuing an unbind request).
* <p>
* This method is semantically equivalent to the following code:
*
@@ -249,56 +286,51 @@
* connection.close(request);
* </pre>
*
- * Calling {@code close} on a connection that is already closed has no
- * effect.
+ * Calling {@code close} on a connection that is already closed has no effect.
*/
void close();
/**
- * Releases any resources associated with this connection. For
- * physical connections to a Directory Server this will mean that the
- * provided unbind request is sent and the underlying socket is
- * closed.
+ * Releases any resources associated with this connection. For physical
+ * connections to a Directory Server this will mean that the provided unbind
+ * request is sent and the underlying socket is closed.
* <p>
- * Other connection implementations may behave differently, and may
- * choose to ignore the provided unbind request if its use is
- * inappropriate (for example a pooled connection will be released and
- * returned to its connection pool without ever issuing an unbind
- * request).
+ * Other connection implementations may behave differently, and may choose to
+ * ignore the provided unbind request if its use is inappropriate (for example
+ * a pooled connection will be released and returned to its connection pool
+ * without ever issuing an unbind request).
* <p>
- * Calling {@code close} on a connection that is already closed has no
- * effect.
+ * Calling {@code close} on a connection that is already closed has no effect.
*
* @param request
- * The unbind request to use in the case where a physical
- * connection is closed.
+ * The unbind request to use in the case where a physical connection
+ * is closed.
* @param reason
* A reason describing why the connection was closed.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
- void close(UnbindRequest request, String reason);
+ void close(UnbindRequest request, String reason) throws NullPointerException;
/**
- * Compares an entry in the Directory Server using the provided
- * compare request.
+ * Compares an entry in the Directory Server using the provided compare
+ * request. Any intermediate responses will be ignored.
*
* @param request
* The compare request.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support compare operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
@@ -310,53 +342,108 @@
/**
- * Deletes an entry from the Directory Server using the provided
- * delete request.
+ * Compares an entry in the Directory Server using the provided compare
+ * request.
*
* @param request
- * The delete request.
- * @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * The compare request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
- * If this connection does not support delete operations.
+ * If this connection does not support compare operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
- FutureResult<Result> delete(DeleteRequest request,
- ResultHandler<Result> handler)
+ FutureResult<CompareResult> compare(CompareRequest request,
+ ResultHandler<? super CompareResult> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
/**
- * Requests that the Directory Server performs the provided extended
+ * Deletes an entry from the Directory Server using the provided delete
+ * request. Any intermediate responses will be ignored.
+ *
+ * @param request
+ * The delete request.
+ * @param handler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support delete operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<Result> delete(DeleteRequest request,
+ ResultHandler<Result> handler) throws UnsupportedOperationException,
+ IllegalStateException, NullPointerException;
+
+
+
+ /**
+ * Deletes an entry from the Directory Server using the provided delete
* request.
*
+ * @param request
+ * The delete request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support delete operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<Result> delete(DeleteRequest request,
+ ResultHandler<Result> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
+
+
+
+ /**
+ * Requests that the Directory Server performs the provided extended request.
+ * Any intermediate responses will be ignored.
+ *
* @param <R>
* The type of result returned by the extended request.
* @param request
* The extended request.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support extended operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
- <R extends Result> FutureResult<R> extendedRequest(
+ <R extends ExtendedResult> FutureResult<R> extendedRequest(
ExtendedRequest<R> request, ResultHandler<? super R> handler)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
@@ -364,20 +451,63 @@
/**
- * Indicates whether or not this connection has been explicitly closed
- * by calling {@code close}. This method will not return {@code true}
- * if a fatal error has occurred on the connection unless {@code
- * close} has been called.
+ * Requests that the Directory Server performs the provided extended request.
*
- * @return {@code true} if this connection has been explicitly closed
- * by calling {@code close}, or {@code false} otherwise.
+ * @param <R>
+ * The type of result returned by the extended request.
+ * @param request
+ * The extended request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support extended operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ <R extends ExtendedResult> FutureResult<R> extendedRequest(
+ ExtendedRequest<R> request, ResultHandler<? super R> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
+
+
+
+ /**
+ * Returns a synchronous connection sharing the same underlying network
+ * connection as this asynchronous connection.
+ *
+ * @return A synchronous connection sharing the same underlying network
+ * connection as this asynchronous connection.
+ */
+ Connection getSynchronousConnection();
+
+
+
+ /**
+ * Indicates whether or not this connection has been explicitly closed by
+ * calling {@code close}. This method will not return {@code true} if a fatal
+ * error has occurred on the connection unless {@code close} has been called.
+ *
+ * @return {@code true} if this connection has been explicitly closed by
+ * calling {@code close}, or {@code false} otherwise.
*/
boolean isClosed();
/**
- * Returns true if the connection has not been closed and is still valid.
+ * Returns {@code true} if this connection has not been closed and no fatal
+ * errors have been detected. This method is guaranteed to return {@code
+ * false} only when it is called after the method {@code close} has been
+ * called.
*
* @return {@code true} if the connection is valid, {@code false} otherwise.
*/
@@ -387,51 +517,105 @@
/**
* Modifies an entry in the Directory Server using the provided modify
- * request.
+ * request. Any intermediate responses will be ignored.
*
* @param request
* The modify request.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support modify operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult<Result> modify(ModifyRequest request,
- ResultHandler<Result> handler)
+ ResultHandler<Result> handler) throws UnsupportedOperationException,
+ IllegalStateException, NullPointerException;
+
+
+
+ /**
+ * Modifies an entry in the Directory Server using the provided modify
+ * request.
+ *
+ * @param request
+ * The modify request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support modify operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<Result> modify(ModifyRequest request,
+ ResultHandler<Result> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
/**
- * Renames an entry in the Directory Server using the provided modify
- * DN request.
+ * Renames an entry in the Directory Server using the provided modify DN
+ * request. Any intermediate responses will be ignored.
*
* @param request
* The modify DN request.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support modify DN operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult<Result> modifyDN(ModifyDNRequest request,
- ResultHandler<Result> handler)
+ ResultHandler<Result> handler) throws UnsupportedOperationException,
+ IllegalStateException, NullPointerException;
+
+
+
+ /**
+ * Renames an entry in the Directory Server using the provided modify DN
+ * request.
+ *
+ * @param request
+ * The modify DN request.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support modify DN operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<Result> modifyDN(ModifyDNRequest request,
+ ResultHandler<Result> resultHandler,
+ IntermediateResponseHandler intermediateResponseHandler)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
@@ -440,34 +624,33 @@
/**
* Reads the named entry from the Directory Server.
* <p>
- * If the requested entry is not returned by the Directory Server then
- * the request will fail with an {@link EntryNotFoundException}. More
+ * If the requested entry is not returned by the Directory Server then the
+ * request will fail with an {@link EntryNotFoundException}. More
* specifically, the returned future will never return {@code null}.
* <p>
* This method is equivalent to the following code:
*
* <pre>
- * SearchRequest request = new SearchRequest(name,
- * SearchScope.BASE_OBJECT, "(objectClass=*)", attributeDescriptions);
+ * SearchRequest request = new SearchRequest(name, SearchScope.BASE_OBJECT,
+ * "(objectClass=*)", attributeDescriptions);
* connection.searchSingleEntry(request, resultHandler, p);
* </pre>
*
* @param name
* The distinguished name of the entry to be read.
* @param attributeDescriptions
- * The names of the attributes to be included with the entry,
- * which may be {@code null} or empty indicating that all
- * user attributes should be returned.
+ * The names of the attributes to be included with the entry, which
+ * may be {@code null} or empty indicating that all user attributes
+ * should be returned.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If the {@code name} was {@code null}.
*/
@@ -482,20 +665,19 @@
/**
* Reads the Root DSE from the Directory Server.
* <p>
- * If the Root DSE is not returned by the Directory Server then the
- * request will fail with an {@link EntryNotFoundException}. More
- * specifically, the returned future will never return {@code null}.
+ * If the Root DSE is not returned by the Directory Server then the request
+ * will fail with an {@link EntryNotFoundException}. More specifically, the
+ * returned future will never return {@code null}.
*
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
*/
FutureResult<RootDSE> readRootDSE(ResultHandler<RootDSE> handler)
throws UnsupportedOperationException, IllegalStateException;
@@ -503,29 +685,26 @@
/**
- * Reads the schema from the Directory Server contained in the named
- * subschema sub-entry.
+ * Reads the schema from the Directory Server contained in the named subschema
+ * sub-entry.
* <p>
- * If the requested schema is not returned by the Directory Server
- * then the request will fail with an {@link EntryNotFoundException}.
- * More specifically, the returned future will never return {@code
- * null}.
+ * If the requested schema is not returned by the Directory Server then the
+ * request will fail with an {@link EntryNotFoundException}. More
+ * specifically, the returned future will never return {@code null}.
* <p>
- * Implementations may choose to perform optimizations such as
- * caching.
+ * Implementations may choose to perform optimizations such as caching.
*
* @param name
* The distinguished name of the subschema sub-entry.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
*/
FutureResult<Schema> readSchema(DN name, ResultHandler<Schema> handler)
throws UnsupportedOperationException, IllegalStateException;
@@ -533,48 +712,45 @@
/**
- * Reads the schema from the Directory Server which applies to the
- * named entry.
+ * Reads the schema from the Directory Server which applies to the named
+ * entry.
* <p>
- * If the requested entry or its associated schema are not returned by
- * the Directory Server then the request will fail with an
- * {@link EntryNotFoundException}. More specifically, the returned
- * future will never return {@code null}.
+ * If the requested entry or its associated schema are not returned by the
+ * Directory Server then the request will fail with an
+ * {@link EntryNotFoundException}. More specifically, the returned future will
+ * never return {@code null}.
* <p>
- * A typical implementation will first read the {@code
- * subschemaSubentry} attribute of the entry in order to locate the
- * schema. However, implementations may choose to perform other
- * optimizations, such as caching.
+ * A typical implementation will first read the {@code subschemaSubentry}
+ * attribute of the entry in order to locate the schema. However,
+ * implementations may choose to perform other optimizations, such as caching.
*
* @param name
- * The distinguished name of the entry whose schema is to be
- * located.
+ * The distinguished name of the entry whose schema is to be located.
* @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}. Optional additional handler parameter.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * Optional additional handler parameter.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
*/
- FutureResult<Schema> readSchemaForEntry(DN name,
- ResultHandler<Schema> handler)
+ FutureResult<Schema> readSchemaForEntry(DN name, ResultHandler<Schema> handler)
throws UnsupportedOperationException, IllegalStateException;
/**
- * Removes the provided connection event listener from this connection
- * so that it will no longer be notified when this connection is
- * closed by the application, receives an unsolicited notification, or
- * experiences a fatal error.
+ * Removes the provided connection event listener from this connection so that
+ * it will no longer be notified when this connection is closed by the
+ * application, receives an unsolicited notification, or experiences a fatal
+ * error.
*
* @param listener
- * The listener which no longer wants to be notified when
- * events occur on this connection.
+ * The listener which no longer wants to be notified when events
+ * occur on this connection.
* @throws NullPointerException
* If the {@code listener} was {@code null}.
*/
@@ -584,24 +760,24 @@
/**
- * Searches the Directory Server using the provided search request.
+ * Searches the Directory Server using the provided search request. Any
+ * intermediate responses will be ignored.
*
* @param request
* The search request.
* @param resultHandler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
* @param searchResulthandler
- * A search result handler which can be used to
- * asynchronously process the search result entries and
- * references as they are received, may be {@code null}.
+ * A search result handler which can be used to asynchronously
+ * process the search result entries and references as they are
+ * received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
@@ -614,33 +790,63 @@
/**
- * Searches the Directory Server for a single entry using the provided
- * search request.
- * <p>
- * If the requested entry is not returned by the Directory Server then
- * the request will fail with an {@link EntryNotFoundException}. More
- * specifically, the returned future will never return {@code null}.
- * If multiple matching entries are returned by the Directory Server
- * then the request will fail with an
- * {@link MultipleEntriesFoundException}.
+ * Searches the Directory Server using the provided search request.
*
* @param request
* The search request.
- * @param handler
- * A result handler which can be used to asynchronously
- * process the operation result when it is received, may be
- * {@code null}.
+ * @param resultHandler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @param searchResulthandler
+ * A search result handler which can be used to asynchronously
+ * process the search result entries and references as they are
+ * received, may be {@code null}.
+ * @param intermediateResponseHandler
+ * An intermediate response handler which can be used to process any
+ * intermediate responses as they are received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
- * If this connection has already been closed, i.e. if
- * {@code isClosed() == true}.
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
+ * @throws NullPointerException
+ * If {@code request} was {@code null}.
+ */
+ FutureResult<Result> search(SearchRequest request,
+ ResultHandler<Result> resultHandler,
+ SearchResultHandler searchResulthandler,
+ IntermediateResponseHandler intermediateResponseHandler)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
+
+
+
+ /**
+ * Searches the Directory Server for a single entry using the provided search
+ * request.
+ * <p>
+ * If the requested entry is not returned by the Directory Server then the
+ * request will fail with an {@link EntryNotFoundException}. More
+ * specifically, the returned future will never return {@code null}. If
+ * multiple matching entries are returned by the Directory Server then the
+ * request will fail with an {@link MultipleEntriesFoundException}.
+ *
+ * @param request
+ * The search request.
+ * @param handler
+ * A result handler which can be used to asynchronously process the
+ * operation result when it is received, may be {@code null}.
+ * @return A future representing the result of the operation.
+ * @throws UnsupportedOperationException
+ * If this connection does not support search operations.
+ * @throws IllegalStateException
+ * If this connection has already been closed, i.e. if {@code
+ * isClosed() == true}.
* @throws NullPointerException
* If the {@code request} was {@code null}.
*/
- FutureResult<SearchResultEntry> searchSingleEntry(
- SearchRequest request,
+ FutureResult<SearchResultEntry> searchSingleEntry(SearchRequest request,
ResultHandler<? super SearchResultEntry> handler)
throws UnsupportedOperationException, IllegalStateException,
NullPointerException;
--
Gitblit v1.10.0