Added missing API docs for reactive API

Author: Zhen Li

driver/src/main/java/org/neo4j/driver/async/AsyncTransactionWork.java

@@ -18,10 +18,8 @@
  */
 package org.neo4j.driver.async;
 
-import org.neo4j.driver.Transaction;
-
 /**
- * Callback that executes operations against a given {@link Transaction}.
+ * Callback that executes operations against a given {@link AsyncTransaction}.
  * To be used with {@link AsyncSession#readTransactionAsync(AsyncTransactionWork)} and
  * {@link AsyncSession#writeTransactionAsync(AsyncTransactionWork)} (AsyncTransactionWork)} methods.
  *

driver/src/main/java/org/neo4j/driver/reactive/RxResult.java

@@ -46,8 +46,8 @@ public interface RxResult
      * When this publisher is {@linkplain Publisher#subscribe(Subscriber) subscribed}, the query statement is sent to the server and get executed.
      * This method does not start the record streaming nor publish query execution error.
      * To retrieve the execution result, either {@link #records()} or {@link #summary()} can be used.
-     * {@link #records()} starts record streaming and report query execution error.
-     * {@link #summary()} skips record streaming and directly report query execution error.
+     * {@link #records()} starts record streaming and reports query execution error.
+     * {@link #summary()} skips record streaming and directly reports query execution error.
      * <p>
      * Consuming of execution result ensures the resources (such as network connections) used by this result is freed correctly.
      * Consuming the keys without consuming the execution result will result in resource leak.
@@ -66,7 +66,7 @@ public interface RxResult
      * <p>
      * When the record publisher is {@linkplain Publisher#subscribe(Subscriber) subscribed},
      * the query statement is executed and the query result is streamed back as a record stream followed by a result summary.
-     * This record publisher publishes all records in the result and signal the completion.
+     * This record publisher publishes all records in the result and signals the completion.
      * However before completion or error reporting if any, a cleanup of result resources such as network connection will be carried out automatically.
      * <p>
      * Therefore the {@link Subscriber} of this record publisher shall wait for the termination signal (complete or error)
@@ -77,13 +77,13 @@ public interface RxResult
      * But it will not cancel the query execution.
      * As a result, a termination signal (complete or error) will still be sent to the {@link Subscriber} after the query execution is finished.
      * <p>
-     * The record publishing event by default runs in Netty IO thread, as a result no blocking operation is allowed in this thread.
+     * The record publishing event by default runs in an Network IO thread, as a result no blocking operation is allowed in this thread.
      * Otherwise network IO might be blocked by application logic.
      * <p>
      * This publisher can only be subscribed by one {@link Subscriber} once.
      * <p>
-     * If this publisher is subscribed after {@link #keys()}, then the publish of records is carried out once each record arrives.
-     * If this publisher is subscribed after {@link #summary()}, then the publish of records has been cancelled
+     * If this publisher is subscribed after {@link #keys()}, then the publish of records is carried out after the arrival of keys.
+     * If this publisher is subscribed after {@link #summary()}, then the publish of records is already cancelled
      * and an empty publisher of zero record will be return.
      * @return a cold unicast publisher of records.
      */
@@ -94,7 +94,7 @@ public interface RxResult
      * <p>
      * {@linkplain Publisher#subscribe(Subscriber) Subscribing} the summary publisher results in the execution of the query followed by the result summary returned.
      * The summary publisher cancels record publishing if not yet subscribed and directly streams back the summary on query execution completion.
-     * As a result, the invocation of {@link #records()} after this method, would receive a empty publisher.
+     * As a result, the invocation of {@link #records()} after this method, would receive an empty publisher.
      * <p>
      * If subscribed after {@link #keys()}, then the result summary will be published after the query execution without streaming any record to client.
      * If subscribed after {@link #records()}, then the result summary will be published after the query execution and the streaming of records.

driver/src/main/java/org/neo4j/driver/reactive/RxSession.java

@@ -21,7 +21,9 @@
 import org.reactivestreams.Publisher;
 
 import java.util.Map;
+import java.util.concurrent.CompletableFuture;
 
+import org.neo4j.driver.AccessMode;
 import org.neo4j.driver.Session;
 import org.neo4j.driver.Statement;
 import org.neo4j.driver.TransactionConfig;
@@ -43,7 +45,7 @@ public interface RxSession extends RxStatementRunner
      * maintain multiple concurrent transactions, use multiple concurrent
      * sessions.
      * <p>
-     * It by default is executed in Netty IO thread, as a result no blocking operation is allowed in this thread.
+     * It by default is executed in a Network IO thread, as a result no blocking operation is allowed in this thread.
      *
      * @return a new {@link RxTransaction}
      */
@@ -52,22 +54,99 @@ public interface RxSession extends RxStatementRunner
     /**
      * Begin a new <em>explicit {@linkplain RxTransaction transaction}</em> with the specified {@link TransactionConfig configuration}.
      * At most one transaction may exist in a session at any point in time. To
-     * maintain multiple concurrent transactions, use multiple concurrent
-     * sessions.
+     * maintain multiple concurrent transactions, use multiple concurrent sessions.
      * <p>
-     * It by default is executed in Netty IO thread, as a result no blocking operation is allowed in this thread.
+     * It by default is executed in a Network IO thread, as a result no blocking operation is allowed in this thread.
      *
      * @param config configuration for the new transaction.
      * @return a new {@link RxTransaction}
      */
     Publisher<RxTransaction> beginTransaction( TransactionConfig config );
 
+    /**
+     * Execute given unit of reactive work in a {@link AccessMode#READ read} reactive transaction.
+     <p>
+     * Transaction will automatically be committed unless given unit of work fails or
+     * {@link RxTransaction#commit() transaction commit} fails.
+     * It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
+     * <p>
+     * Returned publisher and given {@link RxTransactionWork} is 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 CompletableFuture#get()} on the returned publisher and do not use them inside the
+     * {@link RxTransactionWork}.
+     *
+     * @param work the {@link RxTransactionWork} to be applied to a new read transaction.
+     * Operation executed by the given work must NOT include any blocking operation.
+     * @param <T> the return type of the given unit of work.
+     * @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
+     * publisher can be completed exceptionally if given work or commit fails.
+     *
+     */
     <T> Publisher<T> readTransaction( RxTransactionWork<Publisher<T>> work );
 
+    /**
+     * Execute given unit of reactive work in a {@link AccessMode#READ read} reactive transaction with
+     * the specified {@link TransactionConfig configuration}.
+     <p>
+     * Transaction will automatically be committed unless given unit of work fails or
+     * {@link RxTransaction#commit() transaction commit} fails.
+     * It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
+     * <p>
+     * Returned publisher and given {@link RxTransactionWork} is 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 CompletableFuture#get()} on the returned publisher and do not use them inside the
+     * {@link RxTransactionWork}.
+     *
+     * @param work the {@link RxTransactionWork} to be applied to a new read transaction.
+     * Operation executed by the given work must NOT include any blocking operation.
+     * @param <T> the return type of the given unit of work.
+     * @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
+     * publisher can be completed exceptionally if given work or commit fails.
+     *
+     */
     <T> Publisher<T> readTransaction( RxTransactionWork<Publisher<T>> work, TransactionConfig config );
 
+    /**
+     * Execute given unit of reactive work in a {@link AccessMode#WRITE write} reactive transaction.
+     <p>
+     * Transaction will automatically be committed unless given unit of work fails or
+     * {@link RxTransaction#commit() transaction commit} fails.
+     * It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
+     * <p>
+     * Returned publisher and given {@link RxTransactionWork} is 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 CompletableFuture#get()} on the returned publisher and do not use them inside the
+     * {@link RxTransactionWork}.
+     *
+     * @param work the {@link RxTransactionWork} to be applied to a new read transaction.
+     * Operation executed by the given work must NOT include any blocking operation.
+     * @param <T> the return type of the given unit of work.
+     * @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
+     * publisher can be completed exceptionally if given work or commit fails.
+     *
+     */
     <T> Publisher<T> writeTransaction( RxTransactionWork<Publisher<T>> work );
 
+    /**
+     * Execute given unit of reactive work in a {@link AccessMode#WRITE write} reactive transaction with
+     * the specified {@link TransactionConfig configuration}.
+     <p>
+     * Transaction will automatically be committed unless given unit of work fails or
+     * {@link RxTransaction#commit() transaction commit} fails.
+     * It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
+     * <p>
+     * Returned publisher and given {@link RxTransactionWork} is 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 CompletableFuture#get()} on the returned publisher and do not use them inside the
+     * {@link RxTransactionWork}.
+     *
+     * @param work the {@link RxTransactionWork} to be applied to a new read transaction.
+     * Operation executed by the given work must NOT include any blocking operation.
+     * @param <T> the return type of the given unit of work.
+     * @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
+     * publisher can be completed exceptionally if given work or commit fails.
+     *
+     */
     <T> Publisher<T> writeTransaction( RxTransactionWork<Publisher<T>> work, TransactionConfig config );
 
     /**

driver/src/main/java/org/neo4j/driver/reactive/RxTransactionWork.java

@@ -18,7 +18,21 @@
  */
 package org.neo4j.driver.reactive;
 
+/**
+ * Callback that executes operations against a given {@link RxTransaction}.
+ * To be used with {@link RxSession#readTransaction(RxTransactionWork)} and
+ * {@link RxSession#writeTransaction(RxTransactionWork)} methods.
+ *
+ * @param <T> the return type of this work.
+ * @since 2.0
+ */
 public interface RxTransactionWork<T>
 {
+    /**
+     * Executes all given operations against the same transaction.
+     *
+     * @param tx the transaction to use.
+     * @return some result object or {@code null} if none.
+     */
     T execute( RxTransaction tx );
 }