Highlight managed/unmanaged in Session commentary

Author: technige

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

@@ -26,38 +26,29 @@
 /**
  * Provides a context of work for database interactions.
  * <p>
- * A <em>Session</em> hosts a series of {@linkplain Transaction transactions}
- * carried out against a database. Within the database, all queries are
- * carried out within a transaction. Within application code, however, it is
- * not always necessary to explicitly {@link #beginTransaction() begin a
- * transaction}. If a query is {@link #run} directly against a {@link
- * Session}, the server will automatically <code>BEGIN</code> and
- * <code>COMMIT</code> that query within its own transaction. This type
- * of transaction is known as an <em>autocommit transaction</em>.
+ * A <em>Session</em> is a logical container for a causally chained series of
+ * {@linkplain Transaction transactions}. Client applications typically work
+ * with <em>managed transactions</em>, which come in two flavours: transaction
+ * functions and auto-commit transactions. Managed transactions automatically
+ * handle the transaction boundaries (<code>BEGIN</code> and
+ * <code>COMMIT</code>/<code>ROLLBACK</code>) and can also provide other
+ * supporting features; transaction functions offer retry capabilities, for
+ * example.
  * <p>
- * Unmanaged transactions allow multiple queries to be committed as part of
- * a single atomic operation and can be rolled back if necessary. They can also
- * be used to ensure <em>causal consistency</em>, meaning that an application
- * can run a series of queries on different members of a cluster, while
- * ensuring that each query sees the state of graph at least as up-to-date as
- * the graph seen by the previous query. For more on causal consistency, see
- * the Neo4j clustering manual.
+ * Unmanaged transactions are also available but tend to be used by libraries
+ * or tooling that require more fine-grained control.
  * <p>
- * 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.
+ * Typically, a session will acquire a TCP connection from a connection pool
+ * in order to carry out a transaction. Once the transaction has completed,
+ * and the entire result has been consumed, this connection will be released
+ * back into the pool. One connection can therefore be adopted by several
+ * sessions over its lifetime, although it will only be owned by one at a
+ * time. Client applications 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 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 not thread safe.
+ * Session implementations are not generally thread-safe. Therefore, multiple
+ * sessions should be used when an application requires multiple concurrent
+ * threads of database work to be carried out.
  *
  * @since 1.0 (Removed async API to {@link AsyncSession} in 2.0)
  */
@@ -74,21 +65,24 @@ public interface Session extends Resource, QueryRunner
     Transaction beginTransaction();
 
     /**
-     * Begin a new <em>unmanaged {@linkplain Transaction 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.
+     * Begin a new <em>unmanaged {@linkplain Transaction 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.
      *
      * @param config configuration for the new transaction.
      * @return a new {@link Transaction}
      */
     Transaction beginTransaction( TransactionConfig config );
 
     /**
-     * Execute given unit of work in a  {@link AccessMode#READ read} transaction.
+     * Execute a unit of work in a managed {@link AccessMode#READ read} transaction.
+     * <p>
+     * This transaction will automatically be committed unless an exception is
+     * thrown during query execution or by the user code.
      * <p>
-     * Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
-     * or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
+     * Managed transactions should not generally be explicitly committed (via
+     * {@link Transaction#commit()}).
      *
      * @param work the {@link TransactionWork} to be applied to a new read transaction.
      * @param <T> the return type of the given unit of work.
@@ -97,10 +91,14 @@ public interface Session extends Resource, QueryRunner
     <T> T readTransaction( TransactionWork<T> work );
 
     /**
-     * Execute given unit of work in a  {@link AccessMode#READ read} transaction with the specified {@link TransactionConfig configuration}.
+     * Execute a unit of work in a managed {@link AccessMode#READ read} transaction
+     * with the specified {@link TransactionConfig configuration}.
      * <p>
-     * Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
-     * or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
+     * This transaction will automatically be committed unless an exception is
+     * thrown during query execution or by the user code.
+     * <p>
+     * Managed transactions should not generally be explicitly committed (via
+     * {@link Transaction#commit()}).
      *
      * @param work the {@link TransactionWork} to be applied to a new read transaction.
      * @param config configuration for all transactions started to execute the unit of work.
@@ -110,10 +108,13 @@ public interface Session extends Resource, QueryRunner
     <T> T readTransaction( TransactionWork<T> work, TransactionConfig config );
 
     /**
-     * Execute given unit of work in a  {@link AccessMode#WRITE write} transaction.
+     * Execute a unit of work in a managed {@link AccessMode#WRITE write} transaction.
+     * <p>
+     * This transaction will automatically be committed unless an exception is
+     * thrown during query execution or by the user code.
      * <p>
-     * Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
-     * or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
+     * Managed transactions should not generally be explicitly committed (via
+     * {@link Transaction#commit()}).
      *
      * @param work the {@link TransactionWork} to be applied to a new write transaction.
      * @param <T> the return type of the given unit of work.
@@ -122,10 +123,14 @@ public interface Session extends Resource, QueryRunner
     <T> T writeTransaction( TransactionWork<T> work );
 
     /**
-     * Execute given unit of work in a  {@link AccessMode#WRITE write} transaction with the specified {@link TransactionConfig configuration}.
+     * Execute a unit of work in a managed {@link AccessMode#WRITE write} transaction
+     * with the specified {@link TransactionConfig configuration}.
+     * <p>
+     * This transaction will automatically be committed unless an exception is
+     * thrown during query execution or by the user code.
      * <p>
-     * Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
-     * or transaction is explicitly committed via {@link Transaction#commit()} or rolled back via {@link Transaction#rollback()}.
+     * Managed transactions should not generally be explicitly committed (via
+     * {@link Transaction#commit()}).
      *
      * @param work the {@link TransactionWork} to be applied to a new write transaction.
      * @param config configuration for all transactions started to execute the unit of work.
@@ -135,7 +140,8 @@ public interface Session extends Resource, QueryRunner
     <T> T writeTransaction( TransactionWork<T> work, TransactionConfig config );
 
     /**
-     * Run a query in an auto-commit transaction with the specified {@link TransactionConfig configuration} and return a result stream.
+     * Run a query in a managed auto-commit transaction with the specified
+     * {@link TransactionConfig configuration}, and return a result stream.
      *
      * @param query text of a Neo4j query.
      * @param config configuration for the new transaction.
@@ -144,7 +150,8 @@ public interface Session extends Resource, QueryRunner
     Result run(String query, TransactionConfig config );
 
     /**
-     * Run a query with parameters in an auto-commit transaction with specified {@link TransactionConfig configuration} and return a result stream.
+     * Run a query with parameters in a managed auto-commit transaction with the
+     * specified {@link TransactionConfig configuration}, and return a result stream.
      * <p>
      * This method takes a set of parameters that will be injected into the
      * query by Neo4j. Using parameters is highly encouraged, it helps avoid
@@ -181,7 +188,8 @@ public interface Session extends Resource, QueryRunner
     Result run(String query, Map<String,Object> parameters, TransactionConfig config );
 
     /**
-     * Run a query in an auto-commit transaction with specified {@link TransactionConfig configuration} and return a result stream.
+     * Run a query in a managed auto-commit transaction with the specified
+     * {@link TransactionConfig configuration}, and return a result stream.
      * <h2>Example</h2>
      * <pre>
      * {@code