Added javadocs for async APIs

Author: lutovich

driver/src/main/java/org/neo4j/driver/v1/Driver.java

@@ -139,9 +139,20 @@ public interface Driver extends AutoCloseable
     Session session( AccessMode mode, Iterable<String> bookmarks );
 
     /**
-     * Close all the resources assigned to this driver, including any open connections.
+     * Close all the resources assigned to this driver, including open connections and IO threads.
+     * <p>
+     * This operation works the same way as {@link #closeAsync()} but blocks until all resources are closed.
      */
+    @Override
     void close();
 
+    /**
+     * Close all the resources assigned to this driver, including open connections and IO threads.
+     * <p>
+     * This operation is asynchronous and returns a {@link CompletionStage}. This stage is completed with
+     * {@code null} when all resources are closed. It is completed exceptionally if termination fails.
+     *
+     * @return a {@link CompletionStage completion stage} that represents the asynchronous close.
+     */
     CompletionStage<Void> closeAsync();
 }

driver/src/main/java/org/neo4j/driver/v1/Session.java

@@ -19,6 +19,8 @@
 package org.neo4j.driver.v1;
 
 import java.util.concurrent.CompletionStage;
+import java.util.concurrent.Executor;
+import java.util.function.Function;
 
 import org.neo4j.driver.v1.util.Resource;
 
@@ -42,19 +44,21 @@
  * the graph seen by the previous query. For more on causal consistency, see
  * the Neo4j clustering manual.
  * <p>
- * Typically, a session will wrap a TCP connection. Such a connection will be
- * acquired from a connection pool and released back there when the session is
- * destroyed. One connection can therefore be adopted by many sessions,
- * although by only one at a time. Application code should never need to deal
- * directly with connection management.
+ * Typically, a session will acquire a TCP connection to execute query or
+ * transaction. Such a connection will be acquired from a connection pool
+ * and released back there when query result is consumed or transaction is
+ * committed or rolled back. One connection can therefore be adopted by many
+ * sessions, although by only one at a time. Application code should never need
+ * to deal directly with connection management.
  * <p>
  * A session inherits its destination address and permissions from its
- * underlying connection. This means that one session may only ever target one
- * machine within a cluster and does not support re-authentication. To achieve
- * otherwise requires creation of a separate session.
+ * underlying connection. This means that for a single query/transaction one
+ * session may only ever target one machine within a cluster and does not
+ * support re-authentication. To achieve otherwise requires creation of a
+ * separate session.
  * <p>
  * Similarly, multiple sessions should be used when working with concurrency;
- * session implementations are generally not thread safe.
+ * session implementations are not thread safe.
  *
  * @since 1.0
  */
@@ -65,6 +69,9 @@ public interface Session extends Resource, StatementRunner
      * most one transaction may exist in a session at any point in time. To
      * maintain multiple concurrent transactions, use multiple concurrent
      * sessions.
+     * <p>
+     * This operation works the same way as {@link #beginTransactionAsync()} but blocks until transaction is actually
+     * started.
      *
      * @return a new {@link Transaction}
      */
@@ -84,34 +91,101 @@ public interface Session extends Resource, StatementRunner
     @Deprecated
     Transaction beginTransaction( String bookmark );
 
+    /**
+     * Begin a new <em>explicit {@linkplain Transaction transaction}</em>. At
+     * most one transaction may exist in a session at any point in time. To
+     * maintain multiple concurrent transactions, use multiple concurrent
+     * sessions.
+     * <p>
+     * This operation is asynchronous and returns a {@link CompletionStage}. This stage is completed with a new
+     * {@link Transaction} object when begin operation is successful. It is completed exceptionally if
+     * transaction can't be started.
+     * <p>
+     * Returned stage can be completed by an IO thread which should never block. Otherwise IO operations on this and
+     * potentially other network connections might deadlock. Please do not chain blocking operations like
+     * {@link #run(String)} on the returned stage. Driver will throw {@link IllegalStateException} when blocking API
+     * call is executed in IO thread. Consider using asynchronous calls throughout the chain or offloading blocking
+     * operation to a different {@link Executor}. This can be done using methods with "Async" suffix like
+     * {@link CompletionStage#thenApplyAsync(Function)} or {@link CompletionStage#thenApplyAsync(Function, Executor)}.
+     *
+     * @return a {@link CompletionStage completion stage} that represents the asynchronous begin of a transaction.
+     */
     CompletionStage<Transaction> beginTransactionAsync();
 
     /**
      * Execute given unit of work in a  {@link AccessMode#READ read} transaction.
      * <p>
      * Transaction will automatically be committed unless exception is thrown from the unit of work itself or from
      * {@link Transaction#close()} or transaction is explicitly marked for failure via {@link Transaction#failure()}.
+     * <p>
+     * This operation works the same way as {@link #readTransactionAsync(TransactionWork)} but blocks until given
+     * blocking unit of work is completed.
      *
      * @param work the {@link TransactionWork} to be applied to a new read transaction.
      * @param <T> the return type of the given unit of work.
      * @return a result as returned by the given unit of work.
      */
     <T> T readTransaction( TransactionWork<T> work );
 
+    /**
+     * Execute given unit of asynchronous work in a  {@link AccessMode#READ read} asynchronous transaction.
+     * <p>
+     * Transaction will automatically be committed unless given unit of work fails or
+     * {@link Transaction#commitAsync() async transaction commit} fails. It will also not be committed if explicitly
+     * rolled back via {@link Transaction#rollbackAsync()}.
+     * <p>
+     * Returned stage and given {@link TransactionWork} can be completed/executed by an IO thread which should never
+     * block. Otherwise IO operations on this and potentially other network connections might deadlock. Please do not
+     * chain blocking operations like {@link #run(String)} on the returned stage and do not use them inside the
+     * {@link TransactionWork}. Driver will throw {@link IllegalStateException} when blocking API
+     * call is executed in IO thread. Consider using asynchronous calls throughout the chain or offloading blocking
+     * operation to a different {@link Executor}. This can be done using methods with "Async" suffix like
+     * {@link CompletionStage#thenApplyAsync(Function)} or {@link CompletionStage#thenApplyAsync(Function, Executor)}.
+     *
+     * @param work the {@link TransactionWork} to be applied to a new read transaction. Operation executed by the
+     * given work must be asynchronous.
+     * @param <T> the return type of the given unit of work.
+     * @return a {@link CompletionStage completion stage} completed with the same result as returned by the given
+     * unit of work. Stage can be completed exceptionally if given work or commit fails.
+     */
     <T> CompletionStage<T> readTransactionAsync( TransactionWork<CompletionStage<T>> work );
 
     /**
-     * Execute given unit of work in a {@link AccessMode#WRITE write} transaction.
+     * Execute given unit of work in a  {@link AccessMode#WRITE write} transaction.
      * <p>
      * Transaction will automatically be committed unless exception is thrown from the unit of work itself or from
      * {@link Transaction#close()} or transaction is explicitly marked for failure via {@link Transaction#failure()}.
+     * <p>
+     * This operation works the same way as {@link #writeTransactionAsync(TransactionWork)} but blocks until given
+     * blocking unit of work is completed.
      *
      * @param work the {@link TransactionWork} to be applied to a new write transaction.
      * @param <T> the return type of the given unit of work.
      * @return a result as returned by the given unit of work.
      */
     <T> T writeTransaction( TransactionWork<T> work );
 
+    /**
+     * Execute given unit of asynchronous work in a  {@link AccessMode#WRITE write} asynchronous transaction.
+     * <p>
+     * Transaction will automatically be committed unless given unit of work fails or
+     * {@link Transaction#commitAsync() async transaction commit} fails. It will also not be committed if explicitly
+     * rolled back via {@link Transaction#rollbackAsync()}.
+     * <p>
+     * Returned stage and given {@link TransactionWork} can be completed/executed by an IO thread which should never
+     * block. Otherwise IO operations on this and potentially other network connections might deadlock. Please do not
+     * chain blocking operations like {@link #run(String)} on the returned stage and do not use them inside the
+     * {@link TransactionWork}. Driver will throw {@link IllegalStateException} when blocking API
+     * call is executed in IO thread. Consider using asynchronous calls throughout the chain or offloading blocking
+     * operation to a different {@link Executor}. This can be done using methods with "Async" suffix like
+     * {@link CompletionStage#thenApplyAsync(Function)} or {@link CompletionStage#thenApplyAsync(Function, Executor)}.
+     *
+     * @param work the {@link TransactionWork} to be applied to a new write transaction. Operation executed by the
+     * given work must be asynchronous.
+     * @param <T> the return type of the given unit of work.
+     * @return a {@link CompletionStage completion stage} completed with the same result as returned by the given
+     * unit of work. Stage can be completed exceptionally if given work or commit fails.
+     */
     <T> CompletionStage<T> writeTransactionAsync( TransactionWork<CompletionStage<T>> work );
 
     /**
@@ -142,14 +216,23 @@ public interface Session extends Resource, StatementRunner
     void reset();
 
     /**
-     * Signal that you are done using this session. In the default driver usage, closing
-     * and accessing sessions is very low cost, because sessions are pooled by {@link Driver}.
-     *
-     * When this method returns, all outstanding statements in the session are guaranteed to
-     * have completed, meaning any writes you performed are guaranteed to be durably stored.
+     * Signal that you are done using this session. In the default driver usage, closing and accessing sessions is
+     * very low cost.
+     * <p>
+     * This operation works the same way as {@link #closeAsync()} but blocks until session is actually closed.
      */
     @Override
     void close();
 
+    /**
+     * Signal that you are done using this session. In the default driver usage, closing and accessing sessions is
+     * very low cost.
+     * <p>
+     * This operation is asynchronous and returns a {@link CompletionStage}. Stage is completed when all outstanding
+     * statements in the session have completed, meaning any writes you performed are guaranteed to be durably stored.
+     * It might be completed exceptionally when there are unconsumed errors from previous statements or transactions.
+     *
+     * @return a {@link CompletionStage completion stage} that represents the asynchronous close.
+     */
     CompletionStage<Void> closeAsync();
 }

driver/src/main/java/org/neo4j/driver/v1/StatementResultCursor.java

@@ -20,11 +20,45 @@
 
 import java.util.List;
 import java.util.concurrent.CompletionStage;
+import java.util.concurrent.Executor;
 
+import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 import org.neo4j.driver.v1.summary.ResultSummary;
 import org.neo4j.driver.v1.util.Consumer;
 import org.neo4j.driver.v1.util.Function;
 
+/**
+ * The result of asynchronous execution of a Cypher statement, conceptually an asynchronous stream of
+ * {@link Record records}.
+ * <p>
+ * Result can be eagerly fetched in a list using {@link #listAsync()} or navigated lazily using
+ * {@link #forEachAsync(Consumer)} or {@link #nextAsync()}.
+ * <p>
+ * Results are valid until the next statement is run or until the end of the current transaction,
+ * whichever comes first. To keep a result around while further statements are run, or to use a result outside the scope
+ * of the current transaction, see {@link #listAsync()}.
+ * <p>
+ * <h2>Important note on semantics</h2>
+ * <p>
+ * In order to handle very large results, and to minimize memory overhead and maximize
+ * performance, results are retrieved lazily. Please see {@link StatementRunner} for
+ * important details on the effects of this.
+ * <p>
+ * The short version is that, if you want a hard guarantee that the underlying statement
+ * has completed, you need to either call {@link Transaction#commitAsync()} on the {@link Transaction transaction}
+ * or {@link Session#closeAsync()} on the {@link Session session} that created this result, or you need to use
+ * the result.
+ * <p>
+ * <b>Note:</b> Every returned {@link CompletionStage} can be completed by an IO thread which should never block.
+ * Otherwise IO operations on this and potentially other network connections might deadlock. Please do not chain
+ * blocking operations like {@link Session#run(String)} on the returned stages. Driver will throw
+ * {@link IllegalStateException} when blocking API call is executed in IO thread. Consider using asynchronous calls
+ * throughout the chain or offloading blocking operation to a different {@link Executor}. This can be done using
+ * methods with "Async" suffix like {@link CompletionStage#thenApplyAsync(java.util.function.Function)} or
+ * {@link CompletionStage#thenApplyAsync(java.util.function.Function, Executor)}.
+ *
+ * @since 1.5
+ */
 public interface StatementResultCursor
 {
     /**
@@ -34,19 +68,97 @@ public interface StatementResultCursor
      */
     List<String> keys();
 
+    /**
+     * Asynchronously retrieve the result summary.
+     * <p>
+     * If the records in the result is not fully consumed, then calling this method will force to pull all remaining
+     * records into buffer to yield the summary.
+     * <p>
+     * If you want to obtain the summary but discard the records, use {@link #consumeAsync()} instead.
+     *
+     * @return a {@link CompletionStage} completed with a summary for the whole query result. Stage can also be
+     * completed exceptionally if query execution fails.
+     */
     CompletionStage<ResultSummary> summaryAsync();
 
+    /**
+     * Asynchronously navigate to and retrieve the next {@link Record} in this result. Returned stage can contain
+     * {@code null} if end of records stream has been reached.
+     *
+     * @return a {@link CompletionStage} completed with a record or {@code null}. Stage can also be
+     * completed exceptionally if query execution fails.
+     */
     CompletionStage<Record> nextAsync();
 
+    /**
+     * Asynchronously investigate the next upcoming {@link Record} without moving forward in the result. Returned
+     * stage can contain {@code null} if end of records stream has been reached.
+     *
+     * @return a {@link CompletionStage} completed with a record or {@code null}. Stage can also be
+     * completed exceptionally if query execution fails.
+     */
     CompletionStage<Record> peekAsync();
 
+    /**
+     * Asynchronously return the first record in the result, failing if there is not exactly
+     * one record left in the stream.
+     *
+     * @return a {@link CompletionStage} completed with the first and only record in the stream. Stage will be
+     * completed exceptionally with {@link NoSuchRecordException} if there is not exactly one record left in the
+     * stream. It can also be completed exceptionally if query execution fails.
+     */
     CompletionStage<Record> singleAsync();
 
+    /**
+     * Asynchronously consume the entire result, yielding a summary of it. Calling this method exhausts the result.
+     *
+     * @return a {@link CompletionStage} completed with a summary for the whole query result. Stage can also be
+     * completed exceptionally if query execution fails.
+     */
     CompletionStage<ResultSummary> consumeAsync();
 
+    /**
+     * Asynchronously apply the given {@link Consumer action} to every record in the result, yielding a summary of it.
+     *
+     * @param action the function to be applied to every record in the result. Provided function should not block.
+     * @return a {@link CompletionStage} completed with a summary for the whole query result. Stage can also be
+     * completed exceptionally if query execution or provided function fails.
+     */
     CompletionStage<ResultSummary> forEachAsync( Consumer<Record> action );
 
+    /**
+     * Asynchronously retrieve and store the entire result stream.
+     * This can be used if you want to iterate over the stream multiple times or to store the
+     * whole result for later use.
+     * <p>
+     * Note that this method can only be used if you know that the statement that
+     * yielded this result returns a finite stream. Some statements can yield
+     * infinite results, in which case calling this method will lead to running
+     * out of memory.
+     * <p>
+     * Calling this method exhausts the result.
+     *
+     * @return a {@link CompletionStage} completed with a list of all remaining immutable records. Stage can also be
+     * completed exceptionally if query execution fails.
+     */
     CompletionStage<List<Record>> listAsync();
 
+    /**
+     * Asynchronously retrieve and store a projection of the entire result.
+     * This can be used if you want to iterate over the stream multiple times or to store the
+     * whole result for later use.
+     * <p>
+     * Note that this method can only be used if you know that the statement that
+     * yielded this result returns a finite stream. Some statements can yield
+     * infinite results, in which case calling this method will lead to running
+     * out of memory.
+     * <p>
+     * Calling this method exhausts the result.
+     *
+     * @param mapFunction a function to map from Record to T. See {@link Records} for some predefined functions.
+     * @param <T> the type of result list elements
+     * @return a {@link CompletionStage} completed with a list of all remaining immutable records. Stage can also be
+     * completed exceptionally if query execution or provided function fails.
+     */
     <T> CompletionStage<List<T>> listAsync( Function<Record,T> mapFunction );
 }