org.neo4j.driver.v1

Interface Session

All Superinterfaces:

AutoCloseable, Resource, StatementRunner

public interface Session
extends Resource, StatementRunner

Provides a context of work for database interactions.

A Session hosts a series of transactions carried out against a database. Within the database, all statements are carried out within a transaction. Within application code, however, it is not always necessary to explicitly begin a transaction. If a statement is StatementRunner.run(java.lang.String, org.neo4j.driver.v1.Value) directly against a Session, the server will automatically BEGIN and COMMIT that statement within its own transaction. This type of transaction is known as an autocommit transaction.

Explicit transactions allow multiple statements 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:

1.0

Method Summary

Modifier and Type	Method and Description
Transaction	beginTransaction() Begin a new explicit transaction.
Transaction	beginTransaction(String bookmark) Deprecated. This method is deprecated in favour of Driver.session(Iterable) that accepts an initial bookmark. Session will ensure that all nested transactions are chained with bookmarks to guarantee causal consistency. This method will be removed in the next major release.
CompletionStage<Transaction>	beginTransactionAsync() Begin a new explicit transaction.
void	close() Signal that you are done using this session.
CompletionStage<Void>	closeAsync() Signal that you are done using this session.
String	lastBookmark() Return the bookmark received following the last completed transaction.
<T> T	readTransaction(TransactionWork<T> work) Execute given unit of work in a read transaction.
<T> CompletionStage<T>	readTransactionAsync(TransactionWork<CompletionStage<T>> work) Execute given unit of asynchronous work in a read asynchronous transaction.
void	reset() Deprecated. This method should not be used and violates the expected usage pattern of Session objects. They are expected to be not thread-safe and should not be shared between thread. However this method is only useful when Session object is passed to another monitoring thread that calls it when appropriate. It is not useful when Session is used in a single thread because in this case close() can be used. Since version 3.1, Neo4j database allows users to specify maximum transaction execution time and contains procedures to list and terminate running queries. These functions should be used instead of calling this method.
<T> T	writeTransaction(TransactionWork<T> work) Execute given unit of work in a write transaction.
<T> CompletionStage<T>	writeTransactionAsync(TransactionWork<CompletionStage<T>> work) Execute given unit of asynchronous work in a write asynchronous transaction.

Methods inherited from interface org.neo4j.driver.v1.util.Resource

isOpen

Methods inherited from interface org.neo4j.driver.v1.StatementRunner

run, run, run, run, run, runAsync, runAsync, runAsync, runAsync, runAsync, typeSystem

Method Detail

beginTransaction

Transaction beginTransaction()

Begin a new explicit 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 works the same way as beginTransactionAsync() but blocks until transaction is actually started.

Returns:

a new Transaction

beginTransaction

@Deprecated
Transaction beginTransaction(String bookmark)

Deprecated. This method is deprecated in favour of Driver.session(Iterable) that accepts an initial bookmark. Session will ensure that all nested transactions are chained with bookmarks to guarantee causal consistency. This method will be removed in the next major release.

Begin a new explicit transaction, requiring that the server hosting is at least as up-to-date as the transaction referenced by the supplied bookmark.

Parameters:

bookmark - a reference to a previous transaction

Returns:

a new Transaction

beginTransactionAsync

CompletionStage<Transaction> beginTransactionAsync()

Begin a new explicit 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 StatementRunner.run(String) on the returned stage. Driver will throw IllegalStateException when blocking API call is executed in IO thread. 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.

readTransaction

<T> T readTransaction(TransactionWork<T> work)

Execute given unit of work in a read transaction.

Transaction will automatically be committed unless exception is thrown from the unit of work itself or from Transaction.close() or transaction is explicitly marked for failure via Transaction.failure().

This operation works the same way as readTransactionAsync(TransactionWork) but blocks until given blocking unit of work is completed.

Type Parameters:

T - the return type of the given unit of work.

Parameters:

work - the TransactionWork to be applied to a new read transaction.

Returns:

a result as returned by the given unit of work.

readTransactionAsync

<T> CompletionStage<T> readTransactionAsync(TransactionWork<CompletionStage<T>> work)

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 Transaction.rollbackAsync().

Returned stage and given TransactionWork 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 StatementRunner.run(String) on the returned stage and do not use them inside the TransactionWork. Driver will throw IllegalStateException when blocking API call is executed in IO thread. 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 TransactionWork 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.

writeTransaction

<T> T writeTransaction(TransactionWork<T> work)

Execute given unit of work in a write transaction.

Transaction will automatically be committed unless exception is thrown from the unit of work itself or from Transaction.close() or transaction is explicitly marked for failure via Transaction.failure().

This operation works the same way as writeTransactionAsync(TransactionWork) but blocks until given blocking unit of work is completed.

Type Parameters:

T - the return type of the given unit of work.

Parameters:

work - the TransactionWork to be applied to a new write transaction.

Returns:

a result as returned by the given unit of work.

writeTransactionAsync

<T> CompletionStage<T> writeTransactionAsync(TransactionWork<CompletionStage<T>> work)

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 Transaction.rollbackAsync().

Returned stage and given TransactionWork 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 StatementRunner.run(String) on the returned stage and do not use them inside the TransactionWork. Driver will throw IllegalStateException when blocking API call is executed in IO thread. 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 TransactionWork 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.

lastBookmark

String lastBookmark()

Return the bookmark received following the last completed transaction. If no bookmark was received or if this transaction was rolled back, the bookmark value will be null.

Returns:

a reference to a previous transaction

reset

@Deprecated
void reset()

Deprecated. This method should not be used and violates the expected usage pattern of Session objects. They are expected to be not thread-safe and should not be shared between thread. However this method is only useful when Session object is passed to another monitoring thread that calls it when appropriate. It is not useful when Session is used in a single thread because in this case close() can be used. Since version 3.1, Neo4j database allows users to specify maximum transaction execution time and contains procedures to list and terminate running queries. These functions should be used instead of calling this method.

Reset the current session. This sends an immediate RESET signal to the server which both interrupts any statement that is currently executing and ignores any subsequently queued statements. Following the reset, the current transaction will have been rolled back and any outstanding failures will have been acknowledged.

close

void close()

Signal that you are done using this session. In the default driver usage, closing and accessing sessions is very low cost.

This operation works the same way as closeAsync() but blocks until session is actually closed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Resource

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 statements 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 statements or transactions.

Returns:

a completion stage that represents the asynchronous close.