26
26
/**
27
27
* Provides a context of work for database interactions.
28
28
* <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 .
37
37
* <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.
45
40
* <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.
52
48
* <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.
61
52
*
62
53
* @since 1.0 (Removed async API to {@link AsyncSession} in 2.0)
63
54
*/
@@ -74,21 +65,24 @@ public interface Session extends Resource, QueryRunner
74
65
Transaction beginTransaction ();
75
66
76
67
/**
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.
81
72
*
82
73
* @param config configuration for the new transaction.
83
74
* @return a new {@link Transaction}
84
75
*/
85
76
Transaction beginTransaction ( TransactionConfig config );
86
77
87
78
/**
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.
89
83
* <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()}) .
92
86
*
93
87
* @param work the {@link TransactionWork} to be applied to a new read transaction.
94
88
* @param <T> the return type of the given unit of work.
@@ -97,10 +91,14 @@ public interface Session extends Resource, QueryRunner
97
91
<T > T readTransaction ( TransactionWork <T > work );
98
92
99
93
/**
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}.
101
96
* <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()}).
104
102
*
105
103
* @param work the {@link TransactionWork} to be applied to a new read transaction.
106
104
* @param config configuration for all transactions started to execute the unit of work.
@@ -110,10 +108,13 @@ public interface Session extends Resource, QueryRunner
110
108
<T > T readTransaction ( TransactionWork <T > work , TransactionConfig config );
111
109
112
110
/**
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.
114
115
* <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()}) .
117
118
*
118
119
* @param work the {@link TransactionWork} to be applied to a new write transaction.
119
120
* @param <T> the return type of the given unit of work.
@@ -122,10 +123,14 @@ public interface Session extends Resource, QueryRunner
122
123
<T > T writeTransaction ( TransactionWork <T > work );
123
124
124
125
/**
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.
126
131
* <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()}) .
129
134
*
130
135
* @param work the {@link TransactionWork} to be applied to a new write transaction.
131
136
* @param config configuration for all transactions started to execute the unit of work.
@@ -135,7 +140,8 @@ public interface Session extends Resource, QueryRunner
135
140
<T > T writeTransaction ( TransactionWork <T > work , TransactionConfig config );
136
141
137
142
/**
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.
139
145
*
140
146
* @param query text of a Neo4j query.
141
147
* @param config configuration for the new transaction.
@@ -144,7 +150,8 @@ public interface Session extends Resource, QueryRunner
144
150
Result run (String query , TransactionConfig config );
145
151
146
152
/**
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.
148
155
* <p>
149
156
* This method takes a set of parameters that will be injected into the
150
157
* query by Neo4j. Using parameters is highly encouraged, it helps avoid
@@ -181,7 +188,8 @@ public interface Session extends Resource, QueryRunner
181
188
Result run (String query , Map <String ,Object > parameters , TransactionConfig config );
182
189
183
190
/**
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.
185
193
* <h2>Example</h2>
186
194
* <pre>
187
195
* {@code
0 commit comments