Module org.neo4j.driver
Package org.neo4j.driver.async

Interface AsyncSession

All Superinterfaces:
AsyncQueryRunner, BaseSession
All Known Implementing Classes:
InternalAsyncSession
public interface AsyncSession extends BaseSession, AsyncQueryRunner
Provides a context of work for database interactions.

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.

Since:
4.0

  • Method Details

    • beginTransactionAsync

      CompletionStage<AsyncTransaction> beginTransactionAsync()
      Begin a new unmanaged transaction. 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 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).

      Returns:
      a completion stage that represents the asynchronous begin of a transaction.

    • beginTransactionAsync

      CompletionStage<AsyncTransaction> beginTransactionAsync(TransactionConfig config)
      Begin a new unmanaged transaction with the specified 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).

      Parameters:
      config - configuration for the new transaction.
      Returns:
      a completion stage that represents the asynchronous begin of a transaction.

    • readTransactionAsync

      @Deprecated <T> CompletionStage<T> readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
      Deprecated.
      superseded by executeReadAsync(AsyncTransactionCallback).
      Execute given unit of asynchronous work in a 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).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      work - the AsyncTransactionWork to be applied to a new read transaction. Operation executed by the given work must be asynchronous.
      Returns:
      a 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.

    • executeReadAsync

      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. 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.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      Returns:
      a completion stage that completes successfully with the result of the unit of work on success or completes exceptionally otherwise.

    • readTransactionAsync

      @Deprecated <T> CompletionStage<T> readTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work, TransactionConfig config)
      Deprecated.
      superseded by executeReadAsync(AsyncTransactionCallback, TransactionConfig).
      Execute given unit of asynchronous work in a 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).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      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.
      Returns:
      a 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.

    • executeReadAsync

      <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. 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.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      config - configuration for all transactions started to execute the unit of work.
      Returns:
      a completion stage that completes successfully with the result of the unit of work on success or completes exceptionally otherwise.

    • writeTransactionAsync

      @Deprecated <T> CompletionStage<T> writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work)
      Deprecated.
      superseded by executeWriteAsync(AsyncTransactionCallback).
      Execute given unit of asynchronous work in a 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).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      work - the AsyncTransactionWork to be applied to a new write transaction. Operation executed by the given work must be asynchronous.
      Returns:
      a 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.

    • executeWriteAsync

      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. 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.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      Returns:
      a completion stage that completes successfully with the result of the unit of work on success or completes exceptionally otherwise.

    • writeTransactionAsync

      @Deprecated <T> CompletionStage<T> writeTransactionAsync(AsyncTransactionWork<CompletionStage<T>> work, TransactionConfig config)
      Deprecated.
      superseded by executeWriteAsync(AsyncTransactionCallback, TransactionConfig).
      Execute given unit of asynchronous work in a 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).

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      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.
      Returns:
      a 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.

    • executeWriteAsync

      <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. 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.

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      config - configuration for all transactions started to execute the unit of work.
      Returns:
      a completion stage that completes successfully with the result of the unit of work on success or completes exceptionally otherwise.

    • runAsync

      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.

      It is not allowed to chain blocking operations on the returned CompletionStage. See class javadoc in AsyncQueryRunner for more information.

      Parameters:
      query - text of a Neo4j query.
      config - configuration for the new transaction.
      Returns:
      new 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.

    • runAsync

      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.

      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.

      Example

       
 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.
      Parameters:
      query - text of a Neo4j query.
      parameters - input data for the query.
      config - configuration for the new transaction.
      Returns:
      new 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.

    • runAsync

      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.

      Example

       
 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.
      Parameters:
      query - a Neo4j query.
      config - configuration for the new transaction.
      Returns:
      new 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.

    • lastBookmark

      @Deprecated Bookmark lastBookmark()
      Deprecated.
      Return the last bookmark of this session.

      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.

      Returns:
      the last bookmark.

    • lastBookmarks

      Set<Bookmark> lastBookmarks()
      Return a set of last bookmarks.

      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.

      Returns:
      the immutable set of last bookmarks.

    • closeAsync

      CompletionStage<Void> closeAsync()
      Signal that you are done using this session. In the default driver usage, closing and accessing sessions is very low cost.

      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.

      Returns:
      a completion stage that represents the asynchronous close.