org.apache.ignite.cache

## Enum CacheAtomicityMode

- java.lang.Object
- - java.lang.Enum<CacheAtomicityMode>
  - - org.apache.ignite.cache.CacheAtomicityMode

- All Implemented Interfaces:
    Serializable, Comparable<CacheAtomicityMode>

      public enum CacheAtomicityMode
      extends Enum<CacheAtomicityMode>

  Cache atomicity mode controls whether cache should maintain fully transactional semantics or more light-weight atomic behavior. It is recommended that `ATOMIC` mode is used whenever transactions and explicit locking are not needed. Note that in `ATOMIC` mode cache will still maintain full data consistency across all cache nodes.

  Cache atomicity may be set via `CacheConfiguration.getAtomicityMode()` configuration property.

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant and Description
    `ATOMIC` Specifies atomic-only cache behaviour.
    `TRANSACTIONAL` Enables fully `ACID`-compliant transactional cache behavior for the key-value API.
    `TRANSACTIONAL_SNAPSHOT` Deprecated. Use `TRANSACTIONAL` or `ATOMIC` instead. Please, be aware this API will be removed in the next releases.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static @Nullable CacheAtomicityMode` | `fromOrdinal(int ord)` Efficiently gets enumerated value from its ordinal.
    `static CacheAtomicityMode` | `valueOf(String name)` Returns the enum constant of this type with the specified name.
    `static CacheAtomicityMode[]` | `values()` Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class java.lang.Enum

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### TRANSACTIONAL

          public static final CacheAtomicityMode TRANSACTIONAL

      Enables fully `ACID`-compliant transactional cache behavior for the key-value API.

      Note! In this mode, transactional consistency is guaranteed for key-value API operations only. To enable ACID capabilities for SQL transactions, use the `TRANSACTIONAL_SNAPSHOT` mode.

      Note! This atomicity mode is not compatible with the other modes within the same transaction. if a transaction is executed over multiple caches, all caches must have the same atomicity mode, either `TRANSACTIONAL_SNAPSHOT` or `TRANSACTIONAL`.

      See `Transaction` for more information about transactions.

    - #### ATOMIC

          public static final CacheAtomicityMode ATOMIC

      Specifies atomic-only cache behaviour. In this mode distributed transactions and distributed locking are not supported. Disabling transactions and locking allows to achieve much higher performance and throughput ratios.

      In addition to transactions and locking, one of the main differences in `ATOMIC` mode is that bulk writes, such as `putAll(...)`, `removeAll(...)`, and `transformAll(...)` methods, become simple batch operations which can partially fail. In case of partial failure `CachePartialUpdateException` will be thrown which will contain a list of keys for which the update failed. It is recommended that bulk writes are used whenever multiple keys need to be inserted or updated in cache, as they reduce number of network trips and provide better performance.

      Note that even without locking and transactions, `ATOMIC` mode makes best effort to provide full consistency guarantees across all cache nodes. However, in following scenarios (but not limited to) full consistency is not possible and `TRANSACTIONAL` mode should be used or custom defined recovery logic should be applied to restore data consistency:

      - Node that originated update has left together with at least one primary node for this update operation, and left primary node has not finished update propagation to all nodes holding backup partitions. This way backup copies may differ. And also if persistent store is configured it may come to an inconsistent state as well.
      - If update originating node is alive then update is retried by default and for operations `put(...)`, `putAll(...)`, `remove(K, V)` and `removeAll(Set<K>)` all copies of partitions will come to a consistent state.
      - If `EntryProcessor` is used and processor is not idempotent then failure of primary node may result in applying the same processor on next chosen primary which may have already been updated within current operation. If processor is not idempotent it is recommended to disable automatic retries and manually restore consistency between key-value copies in case of update failure.
      - For operations `putIfAbsent(K, V)`, `replace(K, V, V)` and `remove(K, V)` return value on primary node crash may be incorrect because of the automatic retries. It is recommended to disable retries with `IgniteCache.withNoRetries()` and manually restore primary-backup consistency in case of update failure.

      Also note that all data modifications in `ATOMIC` mode are guaranteed to be atomic and consistent with writes to the underlying persistent store, if one is configured.

      Note! Consistency behavior of atomic cache will be improved in future releases.

      See Also:
        `IgniteCache.withNoRetries()`

    - #### TRANSACTIONAL_SNAPSHOT

          @Deprecated
          public static final CacheAtomicityMode TRANSACTIONAL_SNAPSHOT

      Deprecated. Use `TRANSACTIONAL` or `ATOMIC` instead. Please, be aware this API will be removed in the next releases.
      This is an experimental feature. Transactional SQL is currently in a beta status.

      Specifies fully `ACID`-compliant transactional cache behavior for both key-value API and SQL transactions.

      This atomicity mode enables multiversion concurrency control (MVCC) for the cache. In MVCC-enabled caches, when a transaction updates a row, it creates a new version of that row instead of overwriting it. Other users continue to see the old version of the row until the transaction is committed. In this way, readers and writers do not conflict with each other and always work with a consistent dataset. The old version of data is cleaned up when it's no longer accessed by anyone.

      With this mode enabled, one node is elected as an MVCC coordinator. This node tracks all in-flight transactions and queries executed in the cluster. Each transaction or query executed over the cache with `TRANSACTIONAL_SNAPSHOT` mode works with a current snapshot of data generated for this transaction or query by the coordinator. This snapshot ensures that the transaction works with a consistent database state during its execution period.

      Note! This atomicity mode is not compatible with the other modes within the same transaction. If a transaction is executed over multiple caches, all caches must have the same atomicity mode, either `TRANSACTIONAL_SNAPSHOT` or `TRANSACTIONAL`.

      See `Transaction` for more information about transactions.

  - ### Method Detail

    - #### values

          public static CacheAtomicityMode[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (CacheAtomicityMode c : CacheAtomicityMode.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static CacheAtomicityMode valueOf(String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
        `name` - the name of the enum constant to be returned.
      Returns:
        the enum constant with the specified name
      Throws:
        `IllegalArgumentException` - if this enum type has no constant with the specified name
        `NullPointerException` - if the argument is null

    - #### fromOrdinal

          @Nullable
          public static @Nullable CacheAtomicityMode fromOrdinal(int ord)

      Efficiently gets enumerated value from its ordinal.
      Parameters:
        `ord` - Ordinal value.
      Returns:
        Enumerated value or `null` if ordinal out of range.

2022 Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.12.0
Release Date | : January 10 2022