Package io.rdbc.japi

Interface Connection

public interface Connection

Represents a database connection (session).

Instances of implementations of this interface can be obtained using a ConnectionFactory. When clients are done with the connection, they are required to call a `release` method co clean up resources such as open sockets.

Invoking any method of this interface when any previous operation has not completed yet is not allowed. Operation is considered complete when a resulting CompletionStage completes.

Transaction management has to be done using beginTx, commitTx and rollbackTx methods. Using SQL statements to manage transaction state is not allowed.

Method Summary

Modifier and Type	Method and Description
java.util.concurrent.CompletionStage<java.lang.Void>	beginTx() Begins a database transaction.
java.util.concurrent.CompletionStage<java.lang.Void>	beginTx(java.time.Duration timeout) Begins a database transaction.
java.util.concurrent.CompletionStage<java.lang.Void>	commitTx() Commits a database transaction.
java.util.concurrent.CompletionStage<java.lang.Void>	commitTx(java.time.Duration timeout) Commits a database transaction.
java.util.concurrent.CompletionStage<java.lang.Void>	forceRelease() Releases the connection and underlying resources regardless of whether the connection is currently in use or not.
java.util.concurrent.CompletionStage<java.lang.Void>	release() Releases the connection and underlying resources.
java.util.concurrent.CompletionStage<java.lang.Void>	rollbackTx() Rolls back a database transaction.
java.util.concurrent.CompletionStage<java.lang.Void>	rollbackTx(java.time.Duration timeout) Rolls back a database transaction.
Statement	statement(java.lang.String sql) Returns an Statement instance bound to this connection that represents a SQL statement.
Statement	statement(java.lang.String sql, StatementOptions statementOptions) Returns a Statement instance bound to this connection that represents any SQL statement.
java.util.concurrent.CompletionStage<java.lang.Void>	validate(java.time.Duration timeout) Checks whether the connection is still usable.
java.util.concurrent.CompletionStage<Connection>	watchForIdle() Returns a CompletionStage that is complete when this connection is idle and ready for accepting queries.
<T> java.util.concurrent.CompletionStage<T>	withTransaction(java.time.Duration txManageTimeout, ThrowingSupplier<java.util.concurrent.CompletionStage<T>> body) Executes a function in a context of a transaction.
<T> java.util.concurrent.CompletionStage<T>	withTransaction(ThrowingSupplier<java.util.concurrent.CompletionStage<T>> body) Executes a function in a context of a transaction.

Method Detail

beginTx

java.util.concurrent.CompletionStage<java.lang.Void> beginTx(java.time.Duration timeout)

Begins a database transaction.

Using this method is a preferred way of starting a transaction, using SQL statements to manage transaction state may lead to undefined behavior.

After the operation takes longer time than timeout, operation will be aborted. Note however, that it may not be feasible to abort the operation immediately.

Returned CompletionStage can fail with:

• BeginTxException when general error occurs
• TimeoutException when maximum operation time has been exceeded

beginTx

java.util.concurrent.CompletionStage<java.lang.Void> beginTx()

Begins a database transaction.

Using this method is a preferred way of starting a transaction, using SQL statements to manage transaction state may lead to undefined behavior.

Returned CompletionStage can fail with:

• BeginTxException when general error occurs

commitTx

java.util.concurrent.CompletionStage<java.lang.Void> commitTx(java.time.Duration timeout)

Commits a database transaction.

Using this method is a preferred way of committing a transaction, using SQL statements to manage transaction state may lead to undefined behavior.

After the operation takes longer time than timeout, operation will be aborted. Note however, that it may not be feasible to abort the operation immediately.

Returned CompletionStage can fail with:

• CommitTxException when general error occurs
• TimeoutException when maximum operation time has been exceeded

commitTx

java.util.concurrent.CompletionStage<java.lang.Void> commitTx()

Commits a database transaction.

Using this method is a preferred way of committing a transaction, using SQL statements to manage transaction state may lead to undefined behavior.

Returned CompletionStage can fail with:

• CommitTxException when general error occurs

rollbackTx

java.util.concurrent.CompletionStage<java.lang.Void> rollbackTx(java.time.Duration timeout)

Rolls back a database transaction.

Using this method is a preferred way of rolling back a transaction, using SQL statements to manage transaction state may lead to undefined behavior.

After the operation takes longer time than timeout, operation will be aborted. Note however, that it may not be feasible to abort the operation immediately.

Returned CompletionStage can fail with:

• RollbackTxException when general error occurs
• TimeoutException when maximum operation time has been exceeded

rollbackTx

java.util.concurrent.CompletionStage<java.lang.Void> rollbackTx()

Rolls back a database transaction.

Using this method is a preferred way of rolling back a transaction, using SQL statements to manage transaction state may lead to undefined behavior.

Returned CompletionStage can fail with:

• RollbackTxException when general error occurs

withTransaction

<T> java.util.concurrent.CompletionStage<T> withTransaction(ThrowingSupplier<java.util.concurrent.CompletionStage<T>> body)

Executes a function in a context of a transaction.

Executes a function in a context of a freshly started transaction. After the function finishes, transaction is committed in case of a success and rolled back in case of a failure.

withTransaction

<T> java.util.concurrent.CompletionStage<T> withTransaction(java.time.Duration txManageTimeout,
                                                            ThrowingSupplier<java.util.concurrent.CompletionStage<T>> body)

Executes a function in a context of a transaction.

Executes a function in a context of a freshly started transaction. After the function finishes, transaction is committed in case of a success and rolled back in case of a failure.

Parameters:

txManageTimeout - Timeout for operations managing transaction state.

release

java.util.concurrent.CompletionStage<java.lang.Void> release()

Releases the connection and underlying resources.

Only idle connections can be released using this method. To forcibly release the connection use forceRelease method.

After calling this method no future operations on the instance are allowed.

Returned CompletionStage can fail with:

• ConnectionReleaseException when general error occurs

forceRelease

java.util.concurrent.CompletionStage<java.lang.Void> forceRelease()

Releases the connection and underlying resources regardless of whether the connection is currently in use or not.

After calling this method no future operations on the instance are allowed.

Returned CompletionStage can fail with:

• ConnectionReleaseException when general error occurs

validate

java.util.concurrent.CompletionStage<java.lang.Void> validate(java.time.Duration timeout)

Checks whether the connection is still usable.

If checking takes longer than timeout, connection is considered unusable.

Returns:

Successful CompletionStage of Void iff connection is usable, CompletionStage failed with ConnectionValidationException otherwise.

statement

Statement statement(java.lang.String sql)

Returns an Statement instance bound to this connection that represents a SQL statement.

statement

Statement statement(java.lang.String sql,
                    StatementOptions statementOptions)

Returns a Statement instance bound to this connection that represents any SQL statement.

watchForIdle

java.util.concurrent.CompletionStage<Connection> watchForIdle()

Returns a CompletionStage that is complete when this connection is idle and ready for accepting queries.