public interface AsyncSession extends AsyncQueryRunner
An AsyncSession hosts a series of 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 begin a
transaction. If a query is runAsync(java.lang.String, org.neo4j.driver.TransactionConfig) directly against a AsyncSession, the server will automatically BEGIN and
COMMIT that query within its own transaction. This type
of transaction is known as an autocommit transaction.
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 causal consistency, 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.
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.
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.
Similarly, multiple sessions should be used when working with concurrency; session implementations are not thread safe.
| Modifier and Type | Method and Description |
|---|---|
CompletionStage<AsyncTransaction> |
beginTransactionAsync()
Begin a new unmanaged transaction.
|
CompletionStage<AsyncTransaction> |
beginTransactionAsync(TransactionConfig config)
Begin a new unmanaged transaction with the specified
configuration. |
CompletionStage<Void> |
closeAsync()
Signal that you are done using this session.
|
Bookmark |
lastBookmark()
Return the bookmark received following the last completed
transaction.
|
<T> CompletionStage<T> |
readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
Execute given unit of asynchronous work in a
read asynchronous transaction. |
<T> CompletionStage<T> |
readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work,
TransactionConfig config)
Execute given unit of asynchronous work in a
read asynchronous transaction with
the specified configuration. |
CompletionStage<ResultCursor> |
runAsync(Query query,
TransactionConfig config)
Run a query asynchronously in an auto-commit transaction with the specified
configuration and return a
CompletionStage with a result cursor. |
CompletionStage<ResultCursor> |
runAsync(String query,
Map<String,Object> parameters,
TransactionConfig config)
Run a query asynchronously in an auto-commit transaction with the specified
configuration and return a
CompletionStage with a result cursor. |
CompletionStage<ResultCursor> |
runAsync(String query,
TransactionConfig config)
Run a query asynchronously in an auto-commit transaction with the specified
configuration and return a
CompletionStage with a result cursor. |
<T> CompletionStage<T> |
writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
Execute given unit of asynchronous work in a
write asynchronous transaction. |
<T> CompletionStage<T> |
writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work,
TransactionConfig config)
Execute given unit of asynchronous work in a
write asynchronous transaction with
the specified configuration. |
CompletionStage<AsyncTransaction> beginTransactionAsync()
This operation is asynchronous and returns a CompletionStage. This stage is completed with a new
Transaction object when begin operation is successful.
It is completed exceptionally if transaction can't be started.
Returned stage can be completed 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 CompletableFuture.get() on the returned stage.
Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor.
This can be done using methods with "Async" suffix like
CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).
completion stage that represents the asynchronous begin of a transaction.CompletionStage<AsyncTransaction> beginTransactionAsync(TransactionConfig config)
configuration.
At most one transaction may exist in a session at any point in time.
To maintain multiple concurrent transactions, use multiple concurrent sessions.
This operation is asynchronous and returns a CompletionStage. This stage is completed with a new
AsyncTransaction object when begin operation is successful. It is completed exceptionally if
transaction can't be started.
Returned stage can be completed 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 CompletableFuture.get() on the returned stage.
Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor.
This can be done using methods with "Async" suffix like
CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).
config - configuration for the new transaction.completion stage that represents the asynchronous begin of a transaction.<T> CompletionStage<T> readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
read asynchronous transaction.
Transaction will automatically be committed unless given unit of work fails or
async transaction commit fails.
It will also not be committed if explicitly rolled back via AsyncTransaction.rollbackAsync().
Returned stage and given AsyncTransactionWork can be 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 CompletableFuture.get() on the returned stage and do not use them inside the
AsyncTransactionWork.
Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor.
This can be done using methods with "Async" suffix like
CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).
T - the return type of the given unit of work.work - the AsyncTransactionWork to be applied to a new read transaction. Operation executed by the
given work must be asynchronous.completion stage completed with the same result as returned by the given
unit of work. Stage can be completed exceptionally if given work or commit fails.<T> CompletionStage<T> readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work, TransactionConfig config)
read asynchronous transaction with
the specified configuration.
Transaction will automatically be committed unless given unit of work fails or
async transaction commit fails.
It will also not be committed if explicitly rolled back via AsyncTransaction.rollbackAsync().
Returned stage and given AsyncTransactionWork can be 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 CompletableFuture.get() on the returned stage and do not use them inside the
AsyncTransactionWork.
Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor.
This can be done using methods with "Async" suffix like
CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).
T - the return type of the given unit of work.work - the AsyncTransactionWork to be applied to a new read transaction. Operation executed by the
given work must be asynchronous.config - configuration for all transactions started to execute the unit of work.completion stage completed with the same result as returned by the given
unit of work. Stage can be completed exceptionally if given work or commit fails.<T> CompletionStage<T> writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
write asynchronous transaction.
Transaction will automatically be committed unless given unit of work fails or
async transaction commit fails. It will also not be committed if explicitly
rolled back via AsyncTransaction.rollbackAsync().
Returned stage and given AsyncTransactionWork can be 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 CompletableFuture.get() on the returned stage and do not use them inside the
AsyncTransactionWork.
Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor.
This can be done using methods with "Async" suffix like
CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).
T - the return type of the given unit of work.work - the AsyncTransactionWork to be applied to a new write transaction. Operation executed by the
given work must be asynchronous.completion stage completed with the same result as returned by the given
unit of work. Stage can be completed exceptionally if given work or commit fails.<T> CompletionStage<T> writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work, TransactionConfig config)
write asynchronous transaction with
the specified configuration.
Transaction will automatically be committed unless given unit of work fails or
async transaction commit fails. It will also not be committed if explicitly
rolled back via AsyncTransaction.rollbackAsync().
Returned stage and given AsyncTransactionWork can be 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 CompletableFuture.get() on the returned stage and do not use them inside the
AsyncTransactionWork.
Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor.
This can be done using methods with "Async" suffix like
CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).
T - the return type of the given unit of work.work - the AsyncTransactionWork to be applied to a new write transaction. Operation executed by the
given work must be asynchronous.config - configuration for all transactions started to execute the unit of work.completion stage completed with the same result as returned by the given
unit of work. Stage can be completed exceptionally if given work or commit fails.CompletionStage<ResultCursor> runAsync(String query, TransactionConfig config)
configuration and return a
CompletionStage with a result cursor.
It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc in AsyncQueryRunner for
more information.
query - text of a Neo4j query.config - configuration for the new transaction.CompletionStage that gets completed with a result cursor when query execution is successful.
Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.CompletionStage<ResultCursor> runAsync(String query, Map<String,Object> parameters, TransactionConfig config)
configuration and return a
CompletionStage with a result cursor.
This method takes a set of parameters that will be injected into the query by Neo4j. Using parameters is highly encouraged, it helps avoid dangerous cypher injection attacks and improves database performance as Neo4j can re-use query plans more often.
This version of runAsync takes a Map of parameters. The values in the map
must be values that can be converted to Neo4j types. See Values.parameters(Object...) for
a list of allowed types.
Map<String, Object> metadata = new HashMap<>();
metadata.put("type", "update name");
TransactionConfig config = TransactionConfig.builder()
.withTimeout(Duration.ofSeconds(3))
.withMetadata(metadata)
.build();
Map<String, Object> parameters = new HashMap<String, Object>();
parameters.put("myNameParam", "Bob");
CompletionStage<ResultCursor> cursorStage = session.runAsync(
"MATCH (n) WHERE n.name = $myNameParam RETURN (n)",
parameters,
config);
It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc in AsyncQueryRunner for
more information.query - text of a Neo4j query.parameters - input data for the query.config - configuration for the new transaction.CompletionStage that gets completed with a result cursor when query execution is successful.
Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.CompletionStage<ResultCursor> runAsync(Query query, TransactionConfig config)
configuration and return a
CompletionStage with a result cursor.
Map<String, Object> metadata = new HashMap<>();
metadata.put("type", "update name");
TransactionConfig config = TransactionConfig.builder()
.withTimeout(Duration.ofSeconds(3))
.withMetadata(metadata)
.build();
Query query = new Query( "MATCH (n) WHERE n.name = $myNameParam RETURN n.age" );
CompletionStage<ResultCursor> cursorStage = session.runAsync(query, config);
It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc in AsyncQueryRunner for
more information.query - a Neo4j query.config - configuration for the new transaction.CompletionStage that gets completed with a result cursor when query execution is successful.
Stage can be completed exceptionally when error happens, e.g. connection can't be acquired from the pool.Bookmark lastBookmark()
CompletionStage<Void> closeAsync()
This operation is asynchronous and returns a CompletionStage. Stage is completed when all outstanding
queries in the session have completed, meaning any writes you performed are guaranteed to be durably stored.
It might be completed exceptionally when there are unconsumed errors from previous queries or transactions.
completion stage that represents the asynchronous close.