Transaction (GridGain 8.9.15)

All Superinterfaces:

AutoCloseable, IgniteAsyncSupport
```
public interface Transaction
extends AutoCloseable, IgniteAsyncSupport
```
Ignite cache transaction.
Description
Cache transactions have a default 2PC (two-phase-commit) behavior and can be plugged into ongoing JTA transaction by properly implementing CacheTmLookup interface. Cache transactions can also be started explicitly directly from IgniteTransactions API via any of the 'IgniteTransactions.txStart(..)' methods.
Cache transactions support the following isolation levels:
- TransactionIsolation.READ_COMMITTED isolation level means that always a committed value will be provided for read operations. With this isolation level values are always read from cache global memory or persistent store every time a value is accessed. In other words, if the same key is accessed more than once within the same transaction, it may have different value every time since global cache memory may be updated concurrently by other threads.
- TransactionIsolation.REPEATABLE_READ isolation level means that if a value was read once within transaction, then all consecutive reads will provide the same in-transaction value. With this isolation level accessed values are stored within in-transaction memory, so consecutive access to the same key within the same transaction will always return the value that was previously read or updated within this transaction. If concurrency is TransactionConcurrency.PESSIMISTIC, then a lock on the key will be acquired prior to accessing the value.
- TransactionIsolation.SERIALIZABLE isolation level means that all transactions occur in a completely isolated fashion, as if all transactions in the system had executed serially, one after the other. Read access with this level happens the same way as with TransactionIsolation.REPEATABLE_READ level. However, in TransactionConcurrency.OPTIMISTIC mode, if some transactions cannot be serially isolated from each other, then one winner will be picked and the other transactions in conflict will result in TransactionOptimisticException being thrown.
Cache transactions support the following concurrency models:
- TransactionConcurrency.OPTIMISTIC - in this mode all cache operations are not distributed to other nodes until commit() is called. In this mode one 'PREPARE' message will be sent to participating cache nodes to start acquiring per-transaction locks, and once all nodes reply 'OK' (i.e. Phase 1 completes successfully), a one-way' 'COMMIT' message is sent without waiting for reply. If it is necessary to know whenever remote nodes have committed as well, synchronous commit or synchronous rollback should be enabled via CacheConfiguration.setWriteSynchronizationMode(org.apache.ignite.cache.CacheWriteSynchronizationMode).
  Note that in this mode, optimistic failures are only possible in conjunction with TransactionIsolation.SERIALIZABLE isolation level. In all other cases, optimistic transactions will never fail optimistically and will always be identically ordered on all participating grid nodes.
- TransactionConcurrency.PESSIMISTIC - in this mode a lock is acquired on all cache operations with exception of read operations in TransactionIsolation.READ_COMMITTED mode. All optional filters passed into cache operations will be evaluated after successful lock acquisition. Whenever commit() is called, a single one-way 'COMMIT' message is sent to participating cache nodes without waiting for reply. Note that there is no reason for distributed 'PREPARE' step, as all locks have been already acquired. Just like with optimistic mode, it is possible to configure synchronous commit or rollback and wait till transaction commits on all participating remote nodes.
Cache Atomicity Mode
In addition to standard CacheAtomicityMode.TRANSACTIONAL behavior, Ignite also supports a lighter CacheAtomicityMode.ATOMIC mode as well. In this mode distributed transactions and distributed locking are not supported. Disabling transactions and locking allows to achieve much higher performance and throughput ratios. It is recommended that CacheAtomicityMode.ATOMIC mode is used whenever full ACID-compliant transactions are not needed.

Usage
You can use cache transactions as follows:
```
 Ignite ignite = Ignition.ignite();

 IgniteCache<String, Integer> cache = ignite.cache(cacheName);

 try (Transaction tx = ignite.transactions().txStart()) {
     // Perform transactional operations.
     Integer v1 = cache.get("k1");

     // Check if v1 satisfies some condition before doing a put.
     if (v1 != null && v1 > 0)
         cache.put("k1", 2);

     cache.remove("k2");

     // Commit the transaction.
     tx.commit();
 }
 
```

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`close()` Ends the transaction.
`void`	`commit()` Commits this transaction by initiating `two-phase-commit` process.
`IgniteFuture<Void>`	`commitAsync()` Asynchronously commits this transaction by initiating `two-phase-commit` process.
`TransactionConcurrency`	`concurrency()` Cache transaction concurrency mode.
`boolean`	`implicit()` Flag indicating whether transaction was started automatically by the system or not.
`boolean`	`isInvalidate()` Get invalidation flag for this transaction.
`TransactionIsolation`	`isolation()` Cache transaction isolation level.
`boolean`	`isRollbackOnly()` If transaction was marked as rollback-only.
`String`	`label()` Returns transaction's label.
`UUID`	`nodeId()` ID of the node on which this transaction started.
`void`	`resume()` Resume a transaction if it was previously suspended.
`void`	`rollback()` Rolls back this transaction.
`IgniteFuture<Void>`	`rollbackAsync()` Asynchronously rolls back this transaction.
`boolean`	`setRollbackOnly()` Modify the transaction associated with the current thread such that the only possible outcome of the transaction is to roll back the transaction.
`long`	`startTime()` Start time of this transaction.
`TransactionState`	`state()` Gets current transaction state value.
`void`	`suspend()` Suspends a transaction.
`long`	`threadId()` ID of the thread in which this transaction started.
`long`	`timeout()` Gets timeout value in milliseconds for this transaction.
`long`	`timeout(long timeout)` Sets transaction timeout value.
`IgniteUuid`	`xid()` Gets unique identifier for this transaction.

Methods inherited from interface org.apache.ignite.lang.IgniteAsyncSupport
future, isAsync, withAsync

- Method Detail
  - xid
```
IgniteUuid xid()
```
    Gets unique identifier for this transaction.
    
    Returns:
    
    Transaction UID.
  - nodeId
```
UUID nodeId()
```
    ID of the node on which this transaction started.
    
    Returns:
    
    Originating node ID.
  - threadId
```
long threadId()
```
    ID of the thread in which this transaction started.
    
    Returns:
    
    Thread ID.
  - startTime
```
long startTime()
```
    Start time of this transaction.
    
    Returns:
    
    Start time of this transaction on this node.
  - isolation
```
TransactionIsolation isolation()
```
    Cache transaction isolation level.
    
    Returns:
    
    Isolation level.
  - concurrency
```
TransactionConcurrency concurrency()
```
    Cache transaction concurrency mode.
    
    Returns:
    
    Concurrency mode.
  - implicit
```
boolean implicit()
```
    Flag indicating whether transaction was started automatically by the system or not. System will start transactions implicitly whenever any cache put(..) or remove(..) operation is invoked outside of transaction.
    
    Returns:
    
    True if transaction was started implicitly.
  - isInvalidate
```
boolean isInvalidate()
```
    Get invalidation flag for this transaction. If set to true, then remote values will be invalidated (set to null) instead of updated.
    Invalidation messages don't carry new values, so they are a lot lighter than update messages. However, when a value is accessed on a node after it's been invalidated, it must be loaded from persistent store.
    
    Returns:
    
    Invalidation flag.
  - state
```
TransactionState state()
```
    Gets current transaction state value.
    
    Returns:
    
    Current transaction state.
  - timeout
```
long timeout()
```
    Gets timeout value in milliseconds for this transaction. If transaction times out prior to it's completion, TransactionTimeoutException will be thrown.
    
    Returns:
    
    Transaction timeout value.
  - timeout
```
long timeout(long timeout)
```
    Sets transaction timeout value. This value can be set only before a first operation on transaction has been performed.
    
    Parameters:
    
    timeout - Transaction timeout value.
    
    Returns:
    
    Previous timeout.
  - setRollbackOnly
```
boolean setRollbackOnly()
```
    Modify the transaction associated with the current thread such that the only possible outcome of the transaction is to roll back the transaction.
    
    Returns:
    
    True if rollback-only flag was set as a result of this operation, false if it was already set prior to this call or could not be set because transaction is already finishing up committing or rolling back.
  - isRollbackOnly
```
boolean isRollbackOnly()
```
    If transaction was marked as rollback-only.
    
    Returns:
    
    True if transaction can only be rolled back.
  - commit
```
void commit()
     throws IgniteException
```
    Commits this transaction by initiating two-phase-commit process.
    
    Throws:
    
    IgniteException - If commit failed.
    
    TransactionTimeoutException - If transaction is timed out.
    
    TransactionRollbackException - If transaction is automatically rolled back.
    
    TransactionOptimisticException - If transaction concurrency is TransactionConcurrency.OPTIMISTIC and commit is optimistically failed.
    
    TransactionHeuristicException - If transaction has entered an unknown state.
  - commitAsync
```
IgniteFuture<Void> commitAsync()
                        throws IgniteException
```
    Asynchronously commits this transaction by initiating two-phase-commit process.
    
    Returns:
    
    a Future representing pending completion of the commit.
    
    Throws:
    
    IgniteException - If commit failed.
    
    TransactionTimeoutException - If transaction is timed out.
    
    TransactionRollbackException - If transaction is manually/automatically rolled back.
    
    TransactionOptimisticException - If transaction concurrency is TransactionConcurrency.OPTIMISTIC and commit is optimistically failed.
    
    TransactionHeuristicException - If transaction has entered an unknown state.
  - close
```
void close()
    throws IgniteException
```
    Ends the transaction. Transaction will be rolled back if it has not been committed.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Throws:
    
    IgniteException - If transaction could not be gracefully ended.
  - rollback
```
void rollback()
       throws IgniteException
```
    Rolls back this transaction. Note, that it's allowed to roll back transaction from any thread at any time.
    
    Throws:
    
    IgniteException - If rollback failed.
  - rollbackAsync
```
IgniteFuture<Void> rollbackAsync()
                          throws IgniteException
```
    Asynchronously rolls back this transaction. Note, that it's allowed to roll back transaction from any thread at any time.
    
    Returns:
    
    a Future representing pending completion of the rollback.
    
    Throws:
    
    IgniteException - If rollback failed.
  - resume
```
void resume()
     throws IgniteException
```
    Resume a transaction if it was previously suspended. Supported only for optimistic transactions.
    
    Throws:
    
    IgniteException - If resume failed.
  - suspend
```
void suspend()
      throws IgniteException
```
    Suspends a transaction. It could be resumed later. Supported only for optimistic transactions.
    
    Throws:
    
    IgniteException - If suspension failed.
  - label
```
String label()
```
    Returns transaction's label.
    Use IgniteTransactions.withLabel(java.lang.String) to assign a label to a newly created transaction.
    
    Returns:
    
    Label or null if no label was assigned to the transaction.

Interface Transaction

Description

Cache Atomicity Mode

Usage

Method Summary

Methods inherited from interface org.apache.ignite.lang.IgniteAsyncSupport

Method Detail

xid

nodeId

threadId

startTime

isolation

concurrency

implicit

isInvalidate

state

timeout

timeout

setRollbackOnly

isRollbackOnly

commit

commitAsync

close

rollback

rollbackAsync

resume

suspend

label