software.amazon.qldb

Interface Transaction

All Superinterfaces:

AutoCloseable

@NotThreadSafe
public interface Transaction
extends AutoCloseable

Interface that represents an active transaction with QLDB.

Every transaction is tied to the parent QldbSession, meaning that if the parent session is closed or invalidated, the child transaction is automatically closed and cannot be used. Only one transaction can be active at any given time per parent session, and thus every transaction should call abort() or commit() when it is no longer needed, or when a new transaction is wanted from the parent session.

An InvalidSessionException indicates that the parent session is dead, and a new transaction cannot be created without a new QldbSession being created from the parent driver.

Any unexpected errors that occur within a transaction should not be retried using the same transaction, as the state of the transaction is now ambiguous.

When an OCC conflict occurs, the transaction is closed and must be handled manually by creating a new transaction and re-executing the desired queries.

Child Result objects will be closed when the transaction is aborted or committed.

Method Summary

Modifier and Type	Method and Description
void	abort() Abort the transaction and roll back any changes.
void	close() Clean up any resources, and abort the transaction if it has not already been committed or aborted.
void	commit() Commit the transaction.
Result	execute(String statement) Execute the statement against QLDB and retrieve the result.
Result	execute(String statement, List<com.amazon.ion.IonValue> parameters) Execute the statement using the specified parameters against QLDB and retrieve the result.
String	getTransactionId() Get the ID of the current transaction.

Method Detail

abort

void abort()

Abort the transaction and roll back any changes. Any open Results created by the transaction will be closed.

Throws:

com.amazonaws.AmazonClientException - if there is an error communicating with QLDB.

close

void close()

Clean up any resources, and abort the transaction if it has not already been committed or aborted.

Specified by:

close in interface AutoCloseable

commit

void commit()

Commit the transaction. Any open Result created by the transaction will be closed.

If QLDB detects that there has been an optimistic concurrency control conflict (failed validation check to ensure no other committed transaction has modified data that was read) then an OccConflictException will be thrown.

Throws:

IllegalStateException - if the transaction has been committed or aborted already, or if the returned commit digest from QLDB does not match.

com.amazonaws.services.qldbsession.model.OccConflictException - if an OCC conflict has been detected within the transaction.

com.amazonaws.AmazonClientException - if there is an error communicating with QLDB.

execute

Result execute(String statement)

Execute the statement against QLDB and retrieve the result.

Parameters:

statement - The PartiQL statement to be executed against QLDB.

Returns:

The result of executing the statement.

Throws:

IllegalStateException - if the transaction has been committed or aborted already.

com.amazonaws.AmazonClientException - if there is an error communicating with QLDB.

execute

Result execute(String statement,
               List<com.amazon.ion.IonValue> parameters)

Execute the statement using the specified parameters against QLDB and retrieve the result.

Parameters:

statement - The PartiQL statement to be executed against QLDB.

parameters - The parameters to be used with the PartiQL statement, for each ? placeholder in the statement.

Returns:

The result of executing the statement.

Throws:

IllegalStateException - if the transaction has been committed or aborted already.

com.amazonaws.AmazonClientException - if there is an error communicating with QLDB.

getTransactionId

String getTransactionId()

Get the ID of the current transaction.

Returns:

The ID of the current transaction.