software.amazon.qldb

Interface QldbDriver

All Superinterfaces:

AutoCloseable

public interface QldbDriver
extends AutoCloseable

The driver for Amazon QLDB.

The main goal of the driver is to receive lambda functions that are passed to any of its execute methods. The code in these lambda functions should be idempotent as the lambda function might be called more than once based on the TransactionRetryPolicy.

Idempotency:

A transaction needs to be idempotent to avoid undesirable side effects.

For example, consider the below transaction which inserts a document into People table. It first checks if the document already exists in the table or not. So even if this transaction is executed multiple times, it will not cause any side effects.

Without this check, the transaction might duplicate documents in the table if it is retried. A retry may happen when the transaction commits successfully on QLDB server side, but the driver/client timeouts waiting for a response.

For example, the following code shows a lambda that is retryable:

 driver.execute(txn -> {
     Result result = txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = 'Bob'");
     boolean recordExists = result.iterator().hasNext();
     if (recordExists) {
        txn.execute("UPDATE People SET age = 32 WHERE firstName = 'Bob'");
     } else {
        txn.execute("INSERT INTO People {'firstName': 'Bob', 'lastName': 'Doe', 'age':32}");
     }
 });
 

Instantiating the driver

The driver can be instantiated using the QldbDriverBuilder. Example:

     QldbSessionClientBuilder sessionClientBuilder = QldbSessionClient.builder();

     QldbDriverBuilder builder = QldbDriver
          .builder()
          .ledger(ledger);
          .maxConcurrentTransactions(poolLimit)
          .transactionRetryPolicy(RetryPolicy.maxRetries(3));
          .sessionClientBuilder(sessionClientBuilder)
          .build();
 

Method Summary

Modifier and Type	Method and Description
static QldbDriverBuilder	builder()
<T> T	execute(Executor<T> executor) Execute the Executor lambda against QLDB and retrieve the result within a transaction.
<T> T	execute(Executor<T> executor, RetryPolicy retryPolicy) Execute the Executor lambda against QLDB and retrieve the result within a transaction.
void	execute(ExecutorNoReturn executor) Execute the Executor lambda against QLDB within a transaction where no result is expected.
void	execute(ExecutorNoReturn executor, RetryPolicy retryPolicy) Execute the Executor lambda against QLDB within a transaction where no result is expected.
Iterable<String>	getTableNames() Retrieve the table names that are available within the ledger.

Methods inherited from interface java.lang.AutoCloseable

close

Method Detail

execute

void execute(ExecutorNoReturn executor)

Execute the Executor lambda against QLDB within a transaction where no result is expected.

Parameters:

executor - A lambda with no return value representing the block of code to be executed within the transaction. This cannot have any side effects as it may be invoked multiple times.

Throws:

software.amazon.awssdk.core.exception.SdkException - if there is an error executing against QLDB.

execute

void execute(ExecutorNoReturn executor,
             RetryPolicy retryPolicy)

Execute the Executor lambda against QLDB within a transaction where no result is expected.

This method accepts a RetryPolicy that overrides the RetryPolicy set when creating the driver. Use it to customize the backoff delay used when retrying transactions.

Parameters:

executor - A lambda with no return value representing the block of code to be executed within the transaction. This cannot have any side effects as it may be invoked multiple times.

retryPolicy - A RetryPolicy that overrides the RetryPolicy set when creating the driver. The given retry policy will be used when retrying the transaction.

Throws:

TransactionAbortedException - if the Executor lambda calls TransactionExecutor.abort().

software.amazon.awssdk.core.exception.SdkException - if there is an error executing against QLDB.

execute

<T> T execute(Executor<T> executor)

Execute the Executor lambda against QLDB and retrieve the result within a transaction.

Type Parameters:

T - The type of value that will be returned.

Parameters:

executor - A lambda representing the block of code to be executed within the transaction. This cannot have any side effects as it may be invoked multiple times, and the result cannot be trusted until the transaction is committed.

Returns:

The return value of executing the executor. Note that if you directly return a Result, this will be automatically buffered in memory before the implicit commit to allow reading, as the commit will close any open results. Any other Result instances created within the executor block will be invalidated, including if the return value is an object which nests said Result instances within it.

Throws:

TransactionAbortedException - if the Executor lambda calls TransactionExecutor.abort().

software.amazon.awssdk.core.exception.SdkException - if there is an error executing against QLDB.

execute

<T> T execute(Executor<T> executor,
              RetryPolicy retryPolicy)

Execute the Executor lambda against QLDB and retrieve the result within a transaction. This method accepts a RetryPolicy that overrides the RetryPolicy set when creating the driver. Use it to customize the backoff delay used when retrying transactions.

Type Parameters:

T - The type of value that will be returned.

Parameters:

executor - A lambda representing the block of code to be executed within the transaction. This cannot have any side effects as it may be invoked multiple times, and the result cannot be trusted until the transaction is committed.

retryPolicy - A RetryPolicy that overrides the RetryPolicy set when creating the driver. The given retry policy will be used when retrying the transaction.

Returns:

The return value of executing the executor. Note that if you directly return a Result, this will be automatically buffered in memory before the implicit commit to allow reading, as the commit will close any open results. Any other Result instances created within the executor block will be invalidated, including if the return value is an object which nests said Result instances within it.

Throws:

TransactionAbortedException - if the Executor lambda calls TransactionExecutor.abort().

software.amazon.awssdk.core.exception.SdkException - if there is an error executing against QLDB.

getTableNames

Iterable<String> getTableNames()

Retrieve the table names that are available within the ledger.

Returns:

The Iterable over the table names in the ledger.

Throws:

IllegalStateException - if this QldbSession has been closed already, or if the transaction's commit digest does not match the response from QLDB.

software.amazon.awssdk.core.exception.SdkException - if there is an error communicating with QLDB.

builder

static QldbDriverBuilder builder()