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.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.
AsyncSession in 2.0)| Modifier and Type | Method and Description |
|---|---|
Transaction |
beginTransaction()
Begin a new explicit transaction.
|
Transaction |
beginTransaction(TransactionConfig config)
Begin a new explicit transaction with the specified
configuration. |
void |
close()
Signal that you are done using this session.
|
Bookmark |
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. |
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. |
<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. |
Transaction beginTransaction()
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.config - configuration for the new transaction.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 during committing,
or transaction is explicitly committed via Transaction.commit() or rolled back via Transaction.rollback().
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 during committing,
or transaction is explicitly committed via Transaction.commit() or rolled back via Transaction.rollback().
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> T writeTransaction(TransactionWork<T> work)
write transaction.
Transaction will automatically be committed unless exception is thrown from the unit of work itself or during committing,
or transaction is explicitly committed via Transaction.commit() or rolled back via Transaction.rollback().
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 during committing,
or transaction is explicitly committed via Transaction.commit() or rolled back via Transaction.rollback().
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.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.Bookmark 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()
close in interface AutoCloseableclose in interface ResourceCopyright © 2019. All rights reserved.