mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
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;
