Skip to content

Commit a87bf79

Browse files
author
Zhen Li
committed
Added missing API docs for reactive API
1 parent 5fa8ca6 commit a87bf79

File tree

4 files changed

+105
-14
lines changed

4 files changed

+105
-14
lines changed

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

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,8 @@
1818
*/
1919
package org.neo4j.driver.async;
2020

21-
import org.neo4j.driver.Transaction;
22-
2321
/**
24-
* Callback that executes operations against a given {@link Transaction}.
22+
* Callback that executes operations against a given {@link AsyncTransaction}.
2523
* To be used with {@link AsyncSession#readTransactionAsync(AsyncTransactionWork)} and
2624
* {@link AsyncSession#writeTransactionAsync(AsyncTransactionWork)} (AsyncTransactionWork)} methods.
2725
*

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,8 @@ public interface RxResult
4646
* When this publisher is {@linkplain Publisher#subscribe(Subscriber) subscribed}, the query statement is sent to the server and get executed.
4747
* This method does not start the record streaming nor publish query execution error.
4848
* To retrieve the execution result, either {@link #records()} or {@link #summary()} can be used.
49-
* {@link #records()} starts record streaming and report query execution error.
50-
* {@link #summary()} skips record streaming and directly report query execution error.
49+
* {@link #records()} starts record streaming and reports query execution error.
50+
* {@link #summary()} skips record streaming and directly reports query execution error.
5151
* <p>
5252
* Consuming of execution result ensures the resources (such as network connections) used by this result is freed correctly.
5353
* Consuming the keys without consuming the execution result will result in resource leak.
@@ -66,7 +66,7 @@ public interface RxResult
6666
* <p>
6767
* When the record publisher is {@linkplain Publisher#subscribe(Subscriber) subscribed},
6868
* the query statement is executed and the query result is streamed back as a record stream followed by a result summary.
69-
* This record publisher publishes all records in the result and signal the completion.
69+
* This record publisher publishes all records in the result and signals the completion.
7070
* However before completion or error reporting if any, a cleanup of result resources such as network connection will be carried out automatically.
7171
* <p>
7272
* Therefore the {@link Subscriber} of this record publisher shall wait for the termination signal (complete or error)
@@ -77,13 +77,13 @@ public interface RxResult
7777
* But it will not cancel the query execution.
7878
* As a result, a termination signal (complete or error) will still be sent to the {@link Subscriber} after the query execution is finished.
7979
* <p>
80-
* The record publishing event by default runs in Netty IO thread, as a result no blocking operation is allowed in this thread.
80+
* The record publishing event by default runs in an Network IO thread, as a result no blocking operation is allowed in this thread.
8181
* Otherwise network IO might be blocked by application logic.
8282
* <p>
8383
* This publisher can only be subscribed by one {@link Subscriber} once.
8484
* <p>
85-
* If this publisher is subscribed after {@link #keys()}, then the publish of records is carried out once each record arrives.
86-
* If this publisher is subscribed after {@link #summary()}, then the publish of records has been cancelled
85+
* If this publisher is subscribed after {@link #keys()}, then the publish of records is carried out after the arrival of keys.
86+
* If this publisher is subscribed after {@link #summary()}, then the publish of records is already cancelled
8787
* and an empty publisher of zero record will be return.
8888
* @return a cold unicast publisher of records.
8989
*/
@@ -94,7 +94,7 @@ public interface RxResult
9494
* <p>
9595
* {@linkplain Publisher#subscribe(Subscriber) Subscribing} the summary publisher results in the execution of the query followed by the result summary returned.
9696
* The summary publisher cancels record publishing if not yet subscribed and directly streams back the summary on query execution completion.
97-
* As a result, the invocation of {@link #records()} after this method, would receive a empty publisher.
97+
* As a result, the invocation of {@link #records()} after this method, would receive an empty publisher.
9898
* <p>
9999
* If subscribed after {@link #keys()}, then the result summary will be published after the query execution without streaming any record to client.
100100
* 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

Lines changed: 83 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@
2121
import org.reactivestreams.Publisher;
2222

2323
import java.util.Map;
24+
import java.util.concurrent.CompletableFuture;
2425

26+
import org.neo4j.driver.AccessMode;
2527
import org.neo4j.driver.Session;
2628
import org.neo4j.driver.Statement;
2729
import org.neo4j.driver.TransactionConfig;
@@ -43,7 +45,7 @@ public interface RxSession extends RxStatementRunner
4345
* maintain multiple concurrent transactions, use multiple concurrent
4446
* sessions.
4547
* <p>
46-
* It by default is executed in Netty IO thread, as a result no blocking operation is allowed in this thread.
48+
* It by default is executed in a Network IO thread, as a result no blocking operation is allowed in this thread.
4749
*
4850
* @return a new {@link RxTransaction}
4951
*/
@@ -52,22 +54,99 @@ public interface RxSession extends RxStatementRunner
5254
/**
5355
* Begin a new <em>explicit {@linkplain RxTransaction transaction}</em> with the specified {@link TransactionConfig configuration}.
5456
* At most one transaction may exist in a session at any point in time. To
55-
* maintain multiple concurrent transactions, use multiple concurrent
56-
* sessions.
57+
* maintain multiple concurrent transactions, use multiple concurrent sessions.
5758
* <p>
58-
* It by default is executed in Netty IO thread, as a result no blocking operation is allowed in this thread.
59+
* It by default is executed in a Network IO thread, as a result no blocking operation is allowed in this thread.
5960
*
6061
* @param config configuration for the new transaction.
6162
* @return a new {@link RxTransaction}
6263
*/
6364
Publisher<RxTransaction> beginTransaction( TransactionConfig config );
6465

66+
/**
67+
* Execute given unit of reactive work in a {@link AccessMode#READ read} reactive transaction.
68+
<p>
69+
* Transaction will automatically be committed unless given unit of work fails or
70+
* {@link RxTransaction#commit() transaction commit} fails.
71+
* It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
72+
* <p>
73+
* Returned publisher and given {@link RxTransactionWork} is completed/executed by an IO thread which should never block.
74+
* Otherwise IO operations on this and potentially other network connections might deadlock.
75+
* Please do not chain blocking operations like {@link CompletableFuture#get()} on the returned publisher and do not use them inside the
76+
* {@link RxTransactionWork}.
77+
*
78+
* @param work the {@link RxTransactionWork} to be applied to a new read transaction.
79+
* Operation executed by the given work must NOT include any blocking operation.
80+
* @param <T> the return type of the given unit of work.
81+
* @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
82+
* publisher can be completed exceptionally if given work or commit fails.
83+
*
84+
*/
6585
<T> Publisher<T> readTransaction( RxTransactionWork<Publisher<T>> work );
6686

87+
/**
88+
* Execute given unit of reactive work in a {@link AccessMode#READ read} reactive transaction with
89+
* the specified {@link TransactionConfig configuration}.
90+
<p>
91+
* Transaction will automatically be committed unless given unit of work fails or
92+
* {@link RxTransaction#commit() transaction commit} fails.
93+
* It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
94+
* <p>
95+
* Returned publisher and given {@link RxTransactionWork} is completed/executed by an IO thread which should never block.
96+
* Otherwise IO operations on this and potentially other network connections might deadlock.
97+
* Please do not chain blocking operations like {@link CompletableFuture#get()} on the returned publisher and do not use them inside the
98+
* {@link RxTransactionWork}.
99+
*
100+
* @param work the {@link RxTransactionWork} to be applied to a new read transaction.
101+
* Operation executed by the given work must NOT include any blocking operation.
102+
* @param <T> the return type of the given unit of work.
103+
* @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
104+
* publisher can be completed exceptionally if given work or commit fails.
105+
*
106+
*/
67107
<T> Publisher<T> readTransaction( RxTransactionWork<Publisher<T>> work, TransactionConfig config );
68108

109+
/**
110+
* Execute given unit of reactive work in a {@link AccessMode#WRITE write} reactive transaction.
111+
<p>
112+
* Transaction will automatically be committed unless given unit of work fails or
113+
* {@link RxTransaction#commit() transaction commit} fails.
114+
* It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
115+
* <p>
116+
* Returned publisher and given {@link RxTransactionWork} is completed/executed by an IO thread which should never block.
117+
* Otherwise IO operations on this and potentially other network connections might deadlock.
118+
* Please do not chain blocking operations like {@link CompletableFuture#get()} on the returned publisher and do not use them inside the
119+
* {@link RxTransactionWork}.
120+
*
121+
* @param work the {@link RxTransactionWork} to be applied to a new read transaction.
122+
* Operation executed by the given work must NOT include any blocking operation.
123+
* @param <T> the return type of the given unit of work.
124+
* @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
125+
* publisher can be completed exceptionally if given work or commit fails.
126+
*
127+
*/
69128
<T> Publisher<T> writeTransaction( RxTransactionWork<Publisher<T>> work );
70129

130+
/**
131+
* Execute given unit of reactive work in a {@link AccessMode#WRITE write} reactive transaction with
132+
* the specified {@link TransactionConfig configuration}.
133+
<p>
134+
* Transaction will automatically be committed unless given unit of work fails or
135+
* {@link RxTransaction#commit() transaction commit} fails.
136+
* It will also not be committed if explicitly rolled back via {@link RxTransaction#rollback()}.
137+
* <p>
138+
* Returned publisher and given {@link RxTransactionWork} is completed/executed by an IO thread which should never block.
139+
* Otherwise IO operations on this and potentially other network connections might deadlock.
140+
* Please do not chain blocking operations like {@link CompletableFuture#get()} on the returned publisher and do not use them inside the
141+
* {@link RxTransactionWork}.
142+
*
143+
* @param work the {@link RxTransactionWork} to be applied to a new read transaction.
144+
* Operation executed by the given work must NOT include any blocking operation.
145+
* @param <T> the return type of the given unit of work.
146+
* @return a {@link Publisher publisher} completed with the same result as returned by the given unit of work.
147+
* publisher can be completed exceptionally if given work or commit fails.
148+
*
149+
*/
71150
<T> Publisher<T> writeTransaction( RxTransactionWork<Publisher<T>> work, TransactionConfig config );
72151

73152
/**

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,21 @@
1818
*/
1919
package org.neo4j.driver.reactive;
2020

21+
/**
22+
* Callback that executes operations against a given {@link RxTransaction}.
23+
* To be used with {@link RxSession#readTransaction(RxTransactionWork)} and
24+
* {@link RxSession#writeTransaction(RxTransactionWork)} methods.
25+
*
26+
* @param <T> the return type of this work.
27+
* @since 2.0
28+
*/
2129
public interface RxTransactionWork<T>
2230
{
31+
/**
32+
* Executes all given operations against the same transaction.
33+
*
34+
* @param tx the transaction to use.
35+
* @return some result object or {@code null} if none.
36+
*/
2337
T execute( RxTransaction tx );
2438
}

0 commit comments

Comments
 (0)