Skip to content

Commit 83aa083

Browse files
committed
Highlight managed/unmanaged in Session commentary
1 parent 4c6ca4a commit 83aa083

File tree

1 file changed

+56
-48
lines changed

1 file changed

+56
-48
lines changed

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

Lines changed: 56 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -26,38 +26,29 @@
2626
/**
2727
* Provides a context of work for database interactions.
2828
* <p>
29-
* A <em>Session</em> hosts a series of {@linkplain Transaction transactions}
30-
* carried out against a database. Within the database, all queries are
31-
* carried out within a transaction. Within application code, however, it is
32-
* not always necessary to explicitly {@link #beginTransaction() begin a
33-
* transaction}. If a query is {@link #run} directly against a {@link
34-
* Session}, the server will automatically <code>BEGIN</code> and
35-
* <code>COMMIT</code> that query within its own transaction. This type
36-
* of transaction is known as an <em>autocommit transaction</em>.
29+
* A <em>Session</em> is a logical container for a causally chained series of
30+
* {@linkplain Transaction transactions}. Client applications typically work
31+
* with <em>managed transactions</em>, which come in two flavours: transaction
32+
* functions and auto-commit transactions. Managed transactions automatically
33+
* handle the transaction boundaries (<code>BEGIN</code> and
34+
* <code>COMMIT</code>/<code>ROLLBACK</code>) and can also provide other
35+
* supporting features; transaction functions offer retry capabilities, for
36+
* example.
3737
* <p>
38-
* Unmanaged transactions allow multiple queries to be committed as part of
39-
* a single atomic operation and can be rolled back if necessary. They can also
40-
* be used to ensure <em>causal consistency</em>, meaning that an application
41-
* can run a series of queries on different members of a cluster, while
42-
* ensuring that each query sees the state of graph at least as up-to-date as
43-
* the graph seen by the previous query. For more on causal consistency, see
44-
* the Neo4j clustering manual.
38+
* Unmanaged transactions are also available but tend to be used by libraries
39+
* or tooling that require more fine-grained control.
4540
* <p>
46-
* Typically, a session will acquire a TCP connection to execute query or
47-
* transaction. Such a connection will be acquired from a connection pool
48-
* and released back there when query result is consumed or transaction is
49-
* committed or rolled back. One connection can therefore be adopted by many
50-
* sessions, although by only one at a time. Application code should never need
51-
* to deal directly with connection management.
41+
* Typically, a session will acquire a TCP connection from a connection pool
42+
* in order to carry out a transaction. Once the transaction has completed,
43+
* and the entire result has been consumed, this connection will be released
44+
* back into the pool. One connection can therefore be adopted by several
45+
* sessions over its lifetime, although it will only be owned by one at a
46+
* time. Client applications should never need to deal directly with
47+
* connection management.
5248
* <p>
53-
* A session inherits its destination address and permissions from its
54-
* underlying connection. This means that for a single query/transaction one
55-
* session may only ever target one machine within a cluster and does not
56-
* support re-authentication. To achieve otherwise requires creation of a
57-
* separate session.
58-
* <p>
59-
* Similarly, multiple sessions should be used when working with concurrency;
60-
* session implementations are not thread safe.
49+
* Session implementations are not generally thread-safe. Therefore, multiple
50+
* sessions should be used when an application requires multiple concurrent
51+
* threads of database work to be carried out.
6152
*
6253
* @since 1.0 (Removed async API to {@link AsyncSession} in 2.0)
6354
*/
@@ -74,21 +65,24 @@ public interface Session extends Resource, QueryRunner
7465
Transaction beginTransaction();
7566

7667
/**
77-
* Begin a new <em>unmanaged {@linkplain Transaction transaction}</em> with the specified {@link TransactionConfig configuration}.
78-
* At most one transaction may exist in a session at any point in time. To
79-
* maintain multiple concurrent transactions, use multiple concurrent
80-
* sessions.
68+
* Begin a new <em>unmanaged {@linkplain Transaction transaction}</em> with
69+
* the specified {@link TransactionConfig configuration}. At most one
70+
* transaction may exist in a session at any point in time. To maintain
71+
* multiple concurrent transactions, use multiple concurrent sessions.
8172
*
8273
* @param config configuration for the new transaction.
8374
* @return a new {@link Transaction}
8475
*/
8576
Transaction beginTransaction( TransactionConfig config );
8677

8778
/**
88-
* Execute given unit of work in a {@link AccessMode#READ read} transaction.
79+
* Execute a unit of work in a managed {@link AccessMode#READ read} transaction.
80+
* <p>
81+
* This transaction will automatically be committed unless an exception is
82+
* thrown during query execution or by the user code.
8983
* <p>
90-
* Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
91-
* or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
84+
* Managed transactions should not generally be explicitly committed (via
85+
* {@link Transaction#commit()}).
9286
*
9387
* @param work the {@link TransactionWork} to be applied to a new read transaction.
9488
* @param <T> the return type of the given unit of work.
@@ -97,10 +91,14 @@ public interface Session extends Resource, QueryRunner
9791
<T> T readTransaction( TransactionWork<T> work );
9892

9993
/**
100-
* Execute given unit of work in a {@link AccessMode#READ read} transaction with the specified {@link TransactionConfig configuration}.
94+
* Execute a unit of work in a managed {@link AccessMode#READ read} transaction
95+
* with the specified {@link TransactionConfig configuration}.
10196
* <p>
102-
* Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
103-
* or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
97+
* This transaction will automatically be committed unless an exception is
98+
* thrown during query execution or by the user code.
99+
* <p>
100+
* Managed transactions should not generally be explicitly committed (via
101+
* {@link Transaction#commit()}).
104102
*
105103
* @param work the {@link TransactionWork} to be applied to a new read transaction.
106104
* @param config configuration for all transactions started to execute the unit of work.
@@ -110,10 +108,13 @@ public interface Session extends Resource, QueryRunner
110108
<T> T readTransaction( TransactionWork<T> work, TransactionConfig config );
111109

112110
/**
113-
* Execute given unit of work in a {@link AccessMode#WRITE write} transaction.
111+
* Execute a unit of work in a managed {@link AccessMode#WRITE write} transaction.
112+
* <p>
113+
* This transaction will automatically be committed unless an exception is
114+
* thrown during query execution or by the user code.
114115
* <p>
115-
* Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
116-
* or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
116+
* Managed transactions should not generally be explicitly committed (via
117+
* {@link Transaction#commit()}).
117118
*
118119
* @param work the {@link TransactionWork} to be applied to a new write transaction.
119120
* @param <T> the return type of the given unit of work.
@@ -122,10 +123,14 @@ public interface Session extends Resource, QueryRunner
122123
<T> T writeTransaction( TransactionWork<T> work );
123124

124125
/**
125-
* Execute given unit of work in a {@link AccessMode#WRITE write} transaction with the specified {@link TransactionConfig configuration}.
126+
* Execute a unit of work in a managed {@link AccessMode#WRITE write} transaction
127+
* with the specified {@link TransactionConfig configuration}.
128+
* <p>
129+
* This transaction will automatically be committed unless an exception is
130+
* thrown during query execution or by the user code.
126131
* <p>
127-
* Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
128-
* or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
132+
* Managed transactions should not generally be explicitly committed (via
133+
* {@link Transaction#commit()}).
129134
*
130135
* @param work the {@link TransactionWork} to be applied to a new write transaction.
131136
* @param config configuration for all transactions started to execute the unit of work.
@@ -135,7 +140,8 @@ public interface Session extends Resource, QueryRunner
135140
<T> T writeTransaction( TransactionWork<T> work, TransactionConfig config );
136141

137142
/**
138-
* Run a query in an auto-commit transaction with the specified {@link TransactionConfig configuration} and return a result stream.
143+
* Run a query in a managed auto-commit transaction with the specified
144+
* {@link TransactionConfig configuration}, and return a result stream.
139145
*
140146
* @param query text of a Neo4j query.
141147
* @param config configuration for the new transaction.
@@ -144,7 +150,8 @@ public interface Session extends Resource, QueryRunner
144150
Result run(String query, TransactionConfig config );
145151

146152
/**
147-
* Run a query with parameters in an auto-commit transaction with specified {@link TransactionConfig configuration} and return a result stream.
153+
* Run a query with parameters in a managed auto-commit transaction with the
154+
* specified {@link TransactionConfig configuration}, and return a result stream.
148155
* <p>
149156
* This method takes a set of parameters that will be injected into the
150157
* query by Neo4j. Using parameters is highly encouraged, it helps avoid
@@ -181,7 +188,8 @@ public interface Session extends Resource, QueryRunner
181188
Result run(String query, Map<String,Object> parameters, TransactionConfig config );
182189

183190
/**
184-
* Run a query in an auto-commit transaction with specified {@link TransactionConfig configuration} and return a result stream.
191+
* Run a query in a managed auto-commit transaction with the specified
192+
* {@link TransactionConfig configuration}, and return a result stream.
185193
* <h2>Example</h2>
186194
* <pre>
187195
* {@code

0 commit comments

Comments
 (0)