Class TransactionContext

java.lang.Object
com.loomcache.server.transaction.TransactionContext
public final class TransactionContext extends Object
Transactional context enabling cross-data-structure batch operations with explicit transaction boundaries and automatic rollback support.

Purpose: A TransactionContext allows buffering multiple operations across different data structures and executing them atomically. If the commit succeeds, all operations are applied. If any operation fails, all already-executed operations are rolled back via per-operation undo records.

Lifecycle:

  • ACTIVE: accepting buffered operations
  • COMMITTED: all operations applied successfully
  • ROLLED_BACK: manual rollback via rollback()
  • TIMED_OUT: automatic rollback due to timeout
  • OUTCOME_UNKNOWN: replicated commit was submitted but coordinator failover or timeout made the final outcome unknowable from this node

Thread Safety: This class is thread-safe. Multiple threads can safely interact with the same transaction using the internal contextLock.

Since:
1.0

  • Constructor Details

    • TransactionContext

      public TransactionContext(DataStructureRegistry registry, long timeoutMillis)
      Creates a new transaction context.
      Parameters:
      registry - the data structure registry (must not be null)
      timeoutMillis - transaction timeout in milliseconds (must be positive)
      Throws:
      NullPointerException - if registry is null
      IllegalArgumentException - if timeoutMillis invalid input: '<'= 0

    • TransactionContext

      public TransactionContext(DataStructureRegistry registry, UUID transactionId, long timeoutMillis)
      Creates a new transaction context with a caller-specified id.

      Used by the stateless wire-transaction commit path so client-visible ids are preserved in logs and error messages even though no server-side session exists before commit.

  • Method Details

    • isActive

      public boolean isActive()
      Checks if the transaction is still active (not timed out).

      A transaction is active if it is in ACTIVE state AND has not exceeded its deadline.

      Returns:
      true if the transaction is active, false if timed out

    • timeRemainingMillis

      public long timeRemainingMillis()
      Gets the milliseconds remaining until timeout.
      Returns:
      milliseconds remaining (0 if deadline has passed)

    • mapPut

      public void mapPut(String mapName, String key, String value)
      Buffers a map put operation.
      Parameters:
      mapName - the name of the map (must not be null)
      key - the key to put (must not be null)
      value - the value to associate (must not be null)
      Throws:
      IllegalStateException - if transaction is not active

    • mapDelete

      public void mapDelete(String mapName, String key)
      Buffers a map delete operation.
      Parameters:
      mapName - the name of the map (must not be null)
      key - the key to delete (must not be null)
      Throws:
      IllegalStateException - if transaction is not active

    • mapPutIfAbsent

      public void mapPutIfAbsent(String mapName, String key, String value)
      Buffer a map putIfAbsent operation.

    • mapGetForUpdate

      public @Nullable String mapGetForUpdate(String mapName, String key)
      Reads the current value for a map key after the transaction manager has recorded the pessimistic TX-scoped key lock.

    • setAdd

      public void setAdd(String setName, String member)
      Buffer a set add operation.

    • setRemove

      public void setRemove(String setName, String member)
      Buffer a set remove operation.

    • queueOffer

      public void queueOffer(String queueName, String element)
      Buffer a queue offer operation.

    • queuePoll

      public void queuePoll(String queueName)
      Buffer a queue poll operation.

    • multiMapPut

      public void multiMapPut(String mapName, String key, String value)
      Buffer a multimap put operation.

    • multiMapRemove

      public void multiMapRemove(String mapName, String key, String value)
      Buffer a multimap remove operation.

    • commit

      public void commit()
      Commits the transaction: executes all buffered operations atomically with per-operation undo records, and releases locks.

      Phases:

      1. Acquire structure locks in sorted order (deadlock prevention)
      2. Execute each operation, capturing an undo record for rollback
      3. If any operation fails, replay undo records in reverse

      Deadlock Prevention: Structures are locked in sorted order to prevent deadlock.

      Throws:
      IllegalStateException - if transaction is not ACTIVE or has timed out
      RuntimeException - if commit fails (operation throws exception)

    • rollback

      public void rollback()
      Rolls back the transaction: discards all buffered operations and reverses executed ones.

      This can be called at any time while the transaction is ACTIVE. After rollback, all data structures are restored to their pre-transaction state.

      Throws:
      IllegalStateException - if transaction is not ACTIVE

    • getOperationCount

      public int getOperationCount()
      Gets the number of buffered operations.
      Returns:
      the count of buffered operations (>= 0)