Module org.neo4j.driver
Package org.neo4j.driver.reactivestreams

Interface ReactiveSession

All Superinterfaces:
BaseSession, ReactiveQueryRunner
All Known Implementing Classes:
InternalReactiveSession
public interface ReactiveSession extends BaseSession, ReactiveQueryRunner
A reactive session is the same as Session except it provides a reactive API.
Since:
5.2
See Also:

  • Method Details

    • beginTransaction

      default org.reactivestreams.Publisher<ReactiveTransaction> beginTransaction()
      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.

      It is by default is executed in a Network IO thread, as a result no blocking operation is allowed in this thread.

      Returns:
      a new ReactiveTransaction

    • beginTransaction

      org.reactivestreams.Publisher<ReactiveTransaction> beginTransaction(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.

      It is by default is executed in a Network IO thread, as a result no blocking operation is allowed in this thread.

      Parameters:
      config - configuration for the new transaction.
      Returns:
      a new ReactiveTransaction

    • executeRead

      default <T> org.reactivestreams.Publisher<T> executeRead(ReactiveTransactionCallback<? extends org.reactivestreams.Publisher<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 ReactiveResult 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.

      The driver uses the provided ReactiveTransactionCallback to get a publisher and emits its signals via the resulting publisher. If the supplied publisher emits a RetryableException and the driver is in a position to retry, it calls the provided callback again to get a new publisher and attempts to stream its signals. In case of retries, the resulting publisher contains the successfully emitted values from all retry attempts. For instance, if a retryable exception occurs after streaming values [v1, v2, v3] and a successful retry emits values [v1, v2, v3, v4] then the resulting publisher emits the following values: [v1, v2, v3, v1, v2, v3, v4].

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      Returns:
      a publisher that emits the result of the unit of work and success signals on success or error otherwise.

    • executeRead

      <T> org.reactivestreams.Publisher<T> executeRead(ReactiveTransactionCallback<? extends org.reactivestreams.Publisher<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 ReactiveResult 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.

      The driver uses the provided ReactiveTransactionCallback to get a publisher and emits its signals via the resulting publisher. If the supplied publisher emits a RetryableException and the driver is in a position to retry, it calls the provided callback again to get a new publisher and attempts to stream its signals. In case of retries, the resulting publisher contains the successfully emitted values from all retry attempts. For instance, if a retryable exception occurs after streaming values [v1, v2, v3] and a successful retry emits values [v1, v2, v3, v4] then the resulting publisher emits the following values: [v1, v2, v3, v1, v2, v3, v4].

      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 publisher that emits the result of the unit of work and success signals on success or error otherwise.

    • executeWrite

      default <T> org.reactivestreams.Publisher<T> executeWrite(ReactiveTransactionCallback<? extends org.reactivestreams.Publisher<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 ReactiveResult 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.

      The driver uses the provided ReactiveTransactionCallback to get a publisher and emits its signals via the resulting publisher. If the supplied publisher emits a RetryableException and the driver is in a position to retry, it calls the provided callback again to get a new publisher and attempts to stream its signals. In case of retries, the resulting publisher contains the successfully emitted values from all retry attempts. For instance, if a retryable exception occurs after streaming values [v1, v2, v3] and a successful retry emits values [v1, v2, v3, v4] then the resulting publisher emits the following values: [v1, v2, v3, v1, v2, v3, v4].

      Type Parameters:
      T - the return type of the given unit of work.
      Parameters:
      callback - the callback representing the unit of work.
      Returns:
      a publisher that emits the result of the unit of work and success signals on success or error otherwise.

    • executeWrite

      <T> org.reactivestreams.Publisher<T> executeWrite(ReactiveTransactionCallback<? extends org.reactivestreams.Publisher<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 ReactiveResult 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.

      The driver uses the provided ReactiveTransactionCallback to get a publisher and emits its signals via the resulting publisher. If the supplied publisher emits a RetryableException and the driver is in a position to retry, it calls the provided callback again to get a new publisher and attempts to stream its signals. In case of retries, the resulting publisher contains the successfully emitted values from all retry attempts. For instance, if a retryable exception occurs after streaming values [v1, v2, v3] and a successful retry emits values [v1, v2, v3, v4] then the resulting publisher emits the following values: [v1, v2, v3, v1, v2, v3, v4].

      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 publisher that emits the result of the unit of work and success signals on success or error otherwise.

    • run

      default org.reactivestreams.Publisher<ReactiveResult> run(String query, TransactionConfig config)
      Run a query with parameters in an auto-commit transaction with specified TransactionConfig and return a publisher of ReactiveResult.

      Invoking this method will result in a Bolt RUN message exchange with server and the returned publisher will either emit an instance of ReactiveResult on success or an error otherwise.

      Parameters:
      query - text of a Neo4j query.
      config - configuration for the new transaction.
      Returns:
      a publisher of reactive result.

    • run

      default org.reactivestreams.Publisher<ReactiveResult> run(String query, Map<String,Object> parameters, TransactionConfig config)
      Run a query with parameters in an auto-commit transaction with specified TransactionConfig and return a publisher of ReactiveResult.

      Invoking this method will result in a Bolt RUN message exchange with server and the returned publisher will either emit an instance of ReactiveResult on success or an error otherwise.

      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 run 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<>();
 parameters.put("myNameParam", "Bob");

 reactiveSession.run("MATCH (n) WHERE n.name = $myNameParam RETURN (n)", parameters, config);
      Parameters:
      query - text of a Neo4j query.
      parameters - input data for the query.
      config - configuration for the new transaction.
      Returns:
      a publisher of reactive result.

    • run

      org.reactivestreams.Publisher<ReactiveResult> run(Query query, TransactionConfig config)
      Run a query in an auto-commit transaction with specified configuration and return a publisher of ReactiveResult.

      Invoking this method will result in a Bolt RUN message exchange with server and the returned publisher will either emit an instance of ReactiveResult on success or an error otherwise.

      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");

 reactiveSession.run(query.withParameters(Values.parameters("myNameParam", "Bob")));
      Parameters:
      query - a Neo4j query.
      config - configuration for the new transaction.
      Returns:
      a publisher of reactive result.

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

    • close

      <T> org.reactivestreams.Publisher<T> close()
      Signal that you are done using this session. In the default driver usage, closing and accessing sessions is very low cost.

      This operation is not needed if 1) all results created in the session have been fully consumed and 2) all transactions opened by this session have been either committed or rolled back.

      This method is a fallback if you failed to fulfill the two requirements above. This publisher 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.

      Type Parameters:
      T - makes it easier to be chained.
      Returns:
      an empty publisher that represents the reactive close.