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 run(java.lang.String, org.neo4j.driver.v1.TransactionConfig) 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.
Transaction	beginTransaction(TransactionConfig config) Begin a new explicit transaction with the specified configuration.
CompletionStage<Transaction>	beginTransactionAsync() Begin a new explicit transaction.
CompletionStage<Transaction>	beginTransactionAsync(TransactionConfig config) Begin a new explicit transaction with the specified configuration.
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> T	readTransaction(TransactionWork<T> work, TransactionConfig config) Execute given unit of work in a read transaction with the specified configuration.
<T> CompletionStage<T>	readTransactionAsync(TransactionWork<CompletionStage<T>> work) Execute given unit of asynchronous work in a read asynchronous transaction.
<T> CompletionStage<T>	readTransactionAsync(TransactionWork<CompletionStage<T>> work, TransactionConfig config) Execute given unit of asynchronous work in a read asynchronous transaction with the specified configuration.
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.
StatementResult	run(Statement statement, TransactionConfig config) Run a statement in an auto-commit transaction with specified configuration and return a result stream.
StatementResult	run(String statement, Map<String,Object> parameters, TransactionConfig config) Run a statement with parameters in an auto-commit transaction with specified configuration and return a result stream.
StatementResult	run(String statement, TransactionConfig config) Run a statement in an auto-commit transaction with the specified configuration and return a result stream.
CompletionStage<StatementResultCursor>	runAsync(Statement statement, TransactionConfig config) Run a statement asynchronously in an auto-commit transaction with the specified configuration and return a CompletionStage with a result cursor.
CompletionStage<StatementResultCursor>	runAsync(String statement, Map<String,Object> parameters, TransactionConfig config) Run a statement asynchronously in an auto-commit transaction with the specified configuration and return a CompletionStage with a result cursor.
CompletionStage<StatementResultCursor>	runAsync(String statement, TransactionConfig config) Run a statement asynchronously in an auto-commit transaction with the specified configuration and return a CompletionStage with a result cursor.
<T> T	writeTransaction(TransactionWork<T> work) Execute given unit of work in a write transaction.
<T> T	writeTransaction(TransactionWork<T> work, TransactionConfig config) Execute given unit of work in a write transaction with the specified configuration.
<T> CompletionStage<T>	writeTransactionAsync(TransactionWork<CompletionStage<T>> work) Execute given unit of asynchronous work in a write asynchronous transaction.
<T> CompletionStage<T>	writeTransactionAsync(TransactionWork<CompletionStage<T>> work, TransactionConfig config) Execute given unit of asynchronous work in a write asynchronous transaction with the specified configuration.

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

Transaction beginTransaction(TransactionConfig config)

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

Parameters:

config - configuration for the new transaction.

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.

beginTransactionAsync

CompletionStage<Transaction> beginTransactionAsync(TransactionConfig config)

Begin a new explicit 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 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).

Parameters:

config - configuration for the new transaction.

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.

readTransaction

<T> T readTransaction(TransactionWork<T> work,
                      TransactionConfig config)

Execute given unit of work in a read transaction with the specified configuration.

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.

config - configuration for all transactions started to execute the unit of work.

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.

readTransactionAsync

<T> CompletionStage<T> readTransactionAsync(TransactionWork<CompletionStage<T>> work,
                                            TransactionConfig config)

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

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.

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.

writeTransaction

<T> T writeTransaction(TransactionWork<T> work,
                       TransactionConfig config)

Execute given unit of work in a write transaction with the specified configuration.

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.

config - configuration for all transactions started to execute the unit of work.

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.

writeTransactionAsync

<T> CompletionStage<T> writeTransactionAsync(TransactionWork<CompletionStage<T>> work,
                                             TransactionConfig config)

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

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.

run

StatementResult run(String statement,
                    TransactionConfig config)

Run a statement in an auto-commit transaction with the specified configuration and return a result stream.

Parameters:

statement - text of a Neo4j statement.

config - configuration for the new transaction.

Returns:

a stream of result values and associated metadata.

run

StatementResult run(String statement,
                    Map<String,Object> parameters,
                    TransactionConfig config)

Run a statement with parameters in an auto-commit transaction with specified configuration and return a result stream.

This method takes a set of parameters that will be injected into the statement 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");

 StatementResult cursor = session.run("MATCH (n) WHERE n.name = {myNameParam} RETURN (n)", parameters, config);
 
 

Parameters:

statement - text of a Neo4j statement.

parameters - input data for the statement.

config - configuration for the new transaction.

Returns:

a stream of result values and associated metadata.

run

StatementResult run(Statement statement,
                    TransactionConfig config)

Run a statement in an auto-commit transaction with specified configuration and return a result stream.

Example

 
 Map<String, Object> metadata = new HashMap<>();
 metadata.put("type", "update name");

 TransactionConfig config = TransactionConfig.builder()
                 .withTimeout(Duration.ofSeconds(3))
                 .withMetadata(metadata)
                 .build();

 Statement statement = new Statement("MATCH (n) WHERE n.name=$myNameParam RETURN n.age");
 StatementResult cursor = session.run(statement.withParameters(Values.parameters("myNameParam", "Bob")));
 
 

Parameters:

statement - a Neo4j statement.

config - configuration for the new transaction.

Returns:

a stream of result values and associated metadata.

runAsync

CompletionStage<StatementResultCursor> runAsync(String statement,
                                                TransactionConfig config)

Run a statement 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 StatementRunner for more information.

Parameters:

statement - text of a Neo4j statement.

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<StatementResultCursor> runAsync(String statement,
                                                Map<String,Object> parameters,
                                                TransactionConfig config)

Run a statement 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 statement 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<StatementResultCursor> 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 StatementRunner for more information.

Parameters:

statement - text of a Neo4j statement.

parameters - input data for the statement.

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<StatementResultCursor> runAsync(Statement statement,
                                                TransactionConfig config)

Run a statement 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();

 Statement statement = new Statement( "MATCH (n) WHERE n.name=$myNameParam RETURN n.age" );
 CompletionStage<StatementResultCursor> cursorStage = session.runAsync(statement, config);
 
 

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

Parameters:

statement - a Neo4j statement.

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

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.