public interface Session extends Resource, StatementRunner
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.
| 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. |
Transaction beginTransaction()
This operation works the same way as beginTransactionAsync() but blocks until transaction is actually
started.
TransactionTransaction beginTransaction(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 works the same way as beginTransactionAsync(TransactionConfig) but blocks until
transaction is actually started.
config - configuration for the new transaction.Transaction@Deprecated Transaction beginTransaction(String bookmark)
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.bookmark - a reference to a previous transactionTransactionCompletionStage<Transaction> 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
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).
completion stage that represents the asynchronous begin of a transaction.CompletionStage<Transaction> 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
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).
config - configuration for the new transaction.completion stage that represents the asynchronous begin of a transaction.<T> T readTransaction(TransactionWork<T> work)
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.
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new read transaction.<T> T readTransaction(TransactionWork<T> work, TransactionConfig config)
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.
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new read transaction.config - configuration for all transactions started to execute the unit of work.<T> CompletionStage<T> readTransactionAsync(TransactionWork<CompletionStage<T>> work)
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).
T - the return type of the given unit of work.work - the TransactionWork 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.<T> CompletionStage<T> readTransactionAsync(TransactionWork<CompletionStage<T>> work, TransactionConfig config)
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).
T - the return type of the given unit of work.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.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> T writeTransaction(TransactionWork<T> work)
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.
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new write transaction.<T> T writeTransaction(TransactionWork<T> work, TransactionConfig config)
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.
T - the return type of the given unit of work.work - the TransactionWork to be applied to a new write transaction.config - configuration for all transactions started to execute the unit of work.<T> CompletionStage<T> writeTransactionAsync(TransactionWork<CompletionStage<T>> work)
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).
T - the return type of the given unit of work.work - the TransactionWork 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.<T> CompletionStage<T> writeTransactionAsync(TransactionWork<CompletionStage<T>> work, TransactionConfig config)
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).
T - the return type of the given unit of work.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.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.StatementResult run(String statement, TransactionConfig config)
configuration and return a result stream.statement - text of a Neo4j statement.config - configuration for the new transaction.StatementResult run(String statement, Map<String,Object> parameters, TransactionConfig config)
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.
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);
statement - text of a Neo4j statement.parameters - input data for the statement.config - configuration for the new transaction.StatementResult run(Statement statement, TransactionConfig config)
configuration and return a result stream.
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")));
statement - a Neo4j statement.config - configuration for the new transaction.CompletionStage<StatementResultCursor> runAsync(String statement, 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 StatementRunner for
more information.
statement - text of a Neo4j statement.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<StatementResultCursor> runAsync(String statement, 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 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.
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.statement - text of a Neo4j statement.parameters - input data for the statement.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<StatementResultCursor> runAsync(Statement statement, 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();
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.statement - a Neo4j statement.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.String lastBookmark()
@Deprecated void reset()
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.void close()
This operation works the same way as closeAsync() but blocks until session is actually closed.
close in interface AutoCloseableclose in interface ResourceCompletionStage<Void> closeAsync()
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.
completion stage that represents the asynchronous close.Copyright © 2019. All rights reserved.