From 2bc8d15a28fafab97cefafede06d6b7e738ae0fe Mon Sep 17 00:00:00 2001
From: matthew_swift <matthew_swift@localhost>
Date: Fri, 11 Dec 2009 18:45:45 +0000
Subject: [PATCH] Various incremental improvements.
---
sdk/src/org/opends/sdk/AsynchronousConnection.java | 271 ++++++++++++++++++++++++++++++++++++++++++++++-------
1 files changed, 232 insertions(+), 39 deletions(-)
diff --git a/sdk/src/org/opends/sdk/AsynchronousConnection.java b/sdk/src/org/opends/sdk/AsynchronousConnection.java
index b0d8041..1091574 100644
--- a/sdk/src/org/opends/sdk/AsynchronousConnection.java
+++ b/sdk/src/org/opends/sdk/AsynchronousConnection.java
@@ -30,11 +30,14 @@
import java.io.Closeable;
+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.schema.Schema;
@@ -190,6 +193,25 @@
/**
+ * 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.
+ *
+ * @param listener
+ * 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}.
+ * @throws NullPointerException
+ * If the {@code listener} was {@code null}.
+ */
+ void addConnectionEventListener(ConnectionEventListener listener)
+ throws IllegalStateException, NullPointerException;
+
+
+
+ /**
* Authenticates to the Directory Server using the provided bind
* request.
*
@@ -367,6 +389,19 @@
/**
+ * 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();
+
+
+
+ /**
* Modifies an entry in the Directory Server using the provided modify
* request.
*
@@ -429,6 +464,174 @@
/**
+ * 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
+ * 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);
+ * connection.searchSingleEntry(request, resultHandler, p);
+ * </pre>
+ *
+ * @param <P>
+ * The type of the additional parameter to the handler's
+ * methods.
+ * @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.
+ * @param handler
+ * A result handler which can be used to asynchronously
+ * process the operation result when it is received, may be
+ * {@code null}.
+ * @param p
+ * 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}.
+ * @throws NullPointerException
+ * If the {@code name} was {@code null}.
+ */
+ <P> ResultFuture<SearchResultEntry> readEntry(DN name,
+ Collection<String> attributeDescriptions,
+ ResultHandler<? super SearchResultEntry, P> handler, P p)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
+
+
+
+ /**
+ * 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}.
+ *
+ * @param <P>
+ * The type of the additional parameter to the handler's
+ * methods.
+ * @param handler
+ * A result handler which can be used to asynchronously
+ * process the operation result when it is received, may be
+ * {@code null}.
+ * @param p
+ * 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}.
+ */
+ <P> ResultFuture<RootDSE> readRootDSE(
+ ResultHandler<RootDSE, P> handler, P p)
+ throws UnsupportedOperationException, IllegalStateException;
+
+
+
+ /**
+ * 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}.
+ * <p>
+ * Implementations may choose to perform optimizations such as
+ * caching.
+ *
+ * @param <P>
+ * The type of the additional parameter to the handler's
+ * methods.
+ * @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}.
+ * @param p
+ * 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}.
+ */
+ <P> ResultFuture<Schema> readSchema(DN name,
+ ResultHandler<Schema, P> handler, P p)
+ throws UnsupportedOperationException, IllegalStateException;
+
+
+
+ /**
+ * 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}.
+ * <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.
+ *
+ * @param <P>
+ * The type of the additional parameter to the handler's
+ * methods.
+ * @param name
+ * 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}.
+ * @param p
+ * 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}.
+ */
+ <P> ResultFuture<Schema> readSchemaForEntry(DN name,
+ ResultHandler<Schema, P> handler, P p)
+ 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.
+ *
+ * @param listener
+ * The listener which no longer wants to be notified when
+ * events occur on this connection.
+ * @throws NullPointerException
+ * If the {@code listener} was {@code null}.
+ */
+ void removeConnectionEventListener(ConnectionEventListener listener)
+ throws NullPointerException;
+
+
+
+ /**
* Searches the Directory Server using the provided search request.
*
* @param <P>
@@ -464,49 +667,39 @@
/**
- * 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.
+ * 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 listener
- * The listener which wants to be notified when events occur
- * on this connection.
+ * @param <P>
+ * The type of the additional parameter to the handler's
+ * methods.
+ * @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 p
+ * 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}.
* @throws NullPointerException
- * If the {@code listener} was {@code null}.
+ * If the {@code request} was {@code null}.
*/
- void addConnectionEventListener(ConnectionEventListener listener)
- throws IllegalStateException, NullPointerException;
-
-
-
- /**
- * 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.
- * @throws NullPointerException
- * If the {@code listener} was {@code null}.
- */
- void removeConnectionEventListener(ConnectionEventListener listener)
- throws NullPointerException;
-
-
-
- /**
- * 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();
+ <P> ResultFuture<SearchResultEntry> searchSingleEntry(
+ SearchRequest request,
+ ResultHandler<? super SearchResultEntry, P> handler, P p)
+ throws UnsupportedOperationException, IllegalStateException,
+ NullPointerException;
}
--
Gitblit v1.10.0