[IGNITE-15086] Design a public tx API

• Type: Task
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 3.0.0-alpha3
• Labels: iep-61 ignite-3
• Epic Link: Ignite 3 transactions
• Assignee: Alexey Scherbakov
• Reporter: Alexey Scherbakov
• Created: 09/Jul/21 08:26
• Updated: 17/Nov/21 10:25
• Resolved: 15/Jul/21 14:16

Description

Design a public tx API.

The proposed design includes async and sync APIs to execute a transaction.

The transaction facade looks like this:

/**
 * Ignite Transactions facade.
 */
public interface IgniteTransactions {
    /**
     * Begins the transaction.
     *
     * @return The future.
     */
    CompletableFuture<Transaction> beginAsync();

    /**
     * Synchronously executes a closure within a transaction.
     * <p>
     * If the closure is executed normally (no exceptions), the transaction is automatically committed.
     *
     * @param clo The closure.
     */
    void runInTransaction(Consumer<Transaction> clo);
}

Transacton interface:

/**
 * The transaction.
 */
public interface Transaction {
    /**
     * Synchronously commits a transaction.
     * Does nothing if it's already finished by committing or rolling back.
     */
    void commit();

    /**
     * Asynchronously commits a transaction.
     * Does nothing if it's already finished by committing or rolling back.
     *
     * @return The future.
     */
    CompletableFuture<Void> commitAsync();

    /**
     * Synchronously rolls back a transaction.
     * Does nothing if it's already finished by committing or rolling back.
     */
    void rollback();

    /**
     * Asynchronously rolls back a transaction.
     * Does nothing if it's already finished by committing or rolling back.
     *
     * @return The future.
     */
    CompletableFuture<Void> rollbackAsync();
}

Example of synchronous transaction:

        igniteTransactions.runInTransaction(tx -> {
            Table txTable = table.withTransaction(tx); // table view enlisted in the transaction.

            txTable.upsertAsync(...);

            tx.commit(); 
        });

Example of asynchronous transaction:

        igniteTransactions.beginAsync()
            .thenApply(tx -> accounts.withTransaction(tx))
            .thenCompose(txTbl -> txTbl.upsertAsync(...).thenApply(i -> txTbl.transaction()))
            .thenCompose(Transaction::commitAsync);

Issue Links

• links to: GitHub Pull Request #214