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.
|
default <T> CompletionStage<T> |
executeReadAsync(AsyncTransactionCallback<CompletionStage<T>> callback)
Execute a unit of work as a single, managed transaction with
read access mode and retry behaviour. |
<T> CompletionStage<T> |
executeReadAsync(AsyncTransactionCallback<CompletionStage<T>> callback,
TransactionConfig config)
Execute a unit of work as a single, managed transaction with
read access mode and retry behaviour. |
default <T> CompletionStage<T> |
executeWriteAsync(AsyncTransactionCallback<CompletionStage<T>> callback)
Execute a unit of work as a single, managed transaction with
write access mode and retry behaviour. |
<T> CompletionStage<T> |
executeWriteAsync(AsyncTransactionCallback<CompletionStage<T>> callback,
TransactionConfig config)
Execute a unit of work as a single, managed transaction with
write access mode and retry behaviour. |
Bookmark |
lastBookmark()
Deprecated.
|
Set<Bookmark> |
lastBookmarks()
Return a set of last bookmarks.
|
<T> CompletionStage<T> |
readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
Deprecated.
superseded by
executeReadAsync(AsyncTransactionCallback). |
<T> CompletionStage<T> |
readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work,
TransactionConfig config)
Deprecated.
|
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)
Deprecated.
superseded by
executeWriteAsync(AsyncTransactionCallback). |
<T> CompletionStage<T> |
writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work,
TransactionConfig config)
Deprecated.
|
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.@Deprecated <T> CompletionStage<T> readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
executeReadAsync(AsyncTransactionCallback).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.default <T> CompletionStage<T> executeReadAsync(AsyncTransactionCallback<CompletionStage<T>> callback)
read access mode and retry behaviour. The transaction allows for one
or more statements to be run.
The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.
The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.
It is prohibited to block the thread completing the returned CompletionStage. Please avoid blocking operations or hand processing over to a
different thread.
T - the return type of the given unit of work.callback - the callback representing the unit of work.@Deprecated <T> CompletionStage<T> readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work, TransactionConfig config)
executeReadAsync(AsyncTransactionCallback, TransactionConfig).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> executeReadAsync(AsyncTransactionCallback<CompletionStage<T>> callback, TransactionConfig config)
read access mode and retry behaviour. The transaction allows for one or more statements to be run.
The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.
The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.
It is prohibited to block the thread completing the returned CompletionStage. Please avoid blocking operations or hand processing over to a
different thread.
T - the return type of the given unit of work.callback - the callback representing the unit of work.config - configuration for all transactions started to execute the unit of work.@Deprecated <T> CompletionStage<T> writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
executeWriteAsync(AsyncTransactionCallback).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.default <T> CompletionStage<T> executeWriteAsync(AsyncTransactionCallback<CompletionStage<T>> callback)
write access mode and retry behaviour. The transaction allows for
one or more statements to be run.
The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.
The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.
It is prohibited to block the thread completing the returned CompletionStage. Please avoid blocking operations or hand processing over to a
different thread.
T - the return type of the given unit of work.callback - the callback representing the unit of work.@Deprecated <T> CompletionStage<T> writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work, TransactionConfig config)
executeWriteAsync(AsyncTransactionCallback, TransactionConfig).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.<T> CompletionStage<T> executeWriteAsync(AsyncTransactionCallback<CompletionStage<T>> callback, TransactionConfig config)
write access mode and retry behaviour. The transaction allows for one or more statements to be run.
The driver will attempt committing the transaction when the provided unit of work completes successfully. Any exception emitted by the unit of work will result in a rollback attempt and abortion of execution unless exception is considered to be valid for retry attempt by the driver.
The provided unit of work should not return Result object as it won't be valid outside the scope of the transaction.
It is prohibited to block the thread completing the returned CompletionStage. Please avoid blocking operations or hand processing over to a
different thread.
T - the return type of the given unit of work.callback - the callback representing the unit of work.config - configuration for all transactions started to execute the unit of work.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.@Deprecated Bookmark lastBookmark()
When no new bookmark is received, the initial bookmarks are returned as a composite Bookmark containing all initial bookmarks. This may happen
when no work has been done using the session. If no initial bookmarks have been provided, an empty Bookmark is returned.
Set<Bookmark> lastBookmarks()
When no new bookmark is received, the initial bookmarks are returned. This may happen when no work has been done using the session. Multivalued Bookmark instances will be mapped to distinct Bookmark instances. If no initial bookmarks have been provided, an empty set is returned.
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.