Package dev.mintychochip.mint

Interface Transaction

@AvailableSince("1.0") public interface Transaction
Represents an atomic transaction against one or more accounts.

Operations are staged until commit() is called, at which point all operations execute atomically or not at all. Transactions follow strict behavioral guarantees:

  • Atomicity: All operations execute together or none execute. Partial application is impossible.
  • Ordering: Operations execute in the order they were added to the transaction.
  • Multi-Account: Transfers involve two accounts; both must succeed for commit to succeed.
  • Validation: Amount validation (sign, precision) occurs during staging. Balance validation occurs at commit.
  • Idempotency: Operations cannot be retried after commit/rollback. Create a new transaction instead.
  • Thread Safety: Instances are not thread-safe. Use from a single thread or synchronize externally.
  • Failure Handling: On commit failure, transaction auto-rolls back and throws TransactionException.
Since:
1.0

  • Method Details

    • deposit

      Transaction deposit(BigDecimal amount) throws IllegalArgumentException
      Stages a deposit operation to add funds to the account.

      In implementations with deposit limits (e.g., priority queues), the actual deposited amount may be less than requested rather than throwing an exception.

      Parameters:
      amount - the amount to deposit (must be positive)
      Returns:
      this transaction for chaining
      Throws:
      IllegalArgumentException - if amount is negative or exceeds precision limits

    • withdraw

      Transaction withdraw(BigDecimal amount) throws IllegalArgumentException
      Stages a withdrawal operation to remove funds from the account.

      In implementations with withdrawal limits or insufficient funds handling, the actual withdrawn amount may be less than requested rather than failing at commit.

      Parameters:
      amount - the amount to withdraw (must be positive)
      Returns:
      this transaction for chaining
      Throws:
      IllegalArgumentException - if amount is negative or exceeds precision limits

    • set

      Transaction set(BigDecimal amount) throws IllegalArgumentException
      Stages an operation to set the account balance to an exact value.
      Parameters:
      amount - the exact balance to set (must be non-negative)
      Returns:
      this transaction for chaining
      Throws:
      IllegalArgumentException - if amount is negative or exceeds precision limits

    • transferTo

      Transaction transferTo(UUID accountId, BigDecimal amount) throws IllegalArgumentException
      Stages a transfer operation to send funds from this account to another account.

      This withdraws from the source account and deposits to the target account atomically. In implementations with transfer limits, the actual transferred amount may be less than requested rather than throwing an exception.

      Parameters:
      accountId - the target account identifier
      amount - the amount to transfer (must be positive)
      Returns:
      this transaction for chaining
      Throws:
      IllegalArgumentException - if amount is negative or exceeds precision limits

    • transferFrom

      Transaction transferFrom(UUID accountId, BigDecimal amount) throws IllegalArgumentException
      Stages a transfer operation to receive funds from another account to this account.

      This withdraws from the source account and deposits to the target account atomically. In implementations with transfer limits, the actual transferred amount may be less than requested rather than throwing an exception.

      Parameters:
      accountId - the source account identifier
      amount - the amount to receive (must be positive)
      Returns:
      this transaction for chaining
      Throws:
      IllegalArgumentException - if amount is negative or exceeds precision limits

    • commit

      CompletableFuture<TransactionResult> commit()
      Executes all staged operations atomically and persists changes.

      On success, transitions to Transaction.State.COMMITTED and returns a TransactionResult. On failure, transitions to Transaction.State.ROLLED_BACK and throws TransactionException.

      After commit (success or failure), this transaction cannot be reused. Create a new transaction for subsequent operations.

      Returns:
      future completing with transaction result on success
      Throws:
      TransactionException - if validation fails, insufficient funds, or persistence fails

    • rollback

      void rollback()
      Discards all staged operations without applying changes.

      Transitions to Transaction.State.ROLLED_BACK. This operation is idempotent and safe to call multiple times or after commit.

    • getState

      Transaction.State getState()
      Returns the current lifecycle state of this transaction.
      Returns:
      the current state