Package com.tangosol.util

Interface TransactionMap

All Superinterfaces:
ConcurrentMap, Map
public interface TransactionMap extends ConcurrentMap
ConcurrentMap with additional transaction support.

TransactionMap is a thread safe map that could be used by transactions. It maintains two copies of the data: the base [committed] and local [uncommitted].

In all cases, "get" operation reads the local map first and, if not found, the base map second. The "put" and "remove" always use the local map (using a special mark to denote the removed resources). Additionally, depending on a concurrency mode and transaction isolation level the processing strategy for various operations differs.

  • CONCUR_PESSIMISTIC
    • TRANSACTION_GET_COMMITTED
      "put" and "remove" operations lock the corresponding resources on the base map.
    • TRANSACTION_REPEATABLE_GET
      same as TRANSACTION_GET_COMMITTED plus "get" operations lock the corresponding resources on the base map.
    • TRANSACTION_SERIALIZABLE
      same as TRANSACTION_REPEATABLE_GET plus "keySet" operations lock the entire base map to prevent it from adding or removing resources

    During the "prepare" operation the locks for all the resources contained in the local map are checked (to make sure the locks did not expire). Upon successful validation the "commit" phase copies the local data into the base map and unlock everything. Any exception during "prepare" or "commit" causes the rollback which clears the local map and unlocks all relevant resources.

  • CONCUR_OPTIMISTIC
    During the "prepare" operation an attempt is made to lock all the resources contained in the local map and, if successful, the affected key sets are validated using the current Validator (chain). Upon successful validation the "commit" phase copies the local data into the base map and unlocks everything. Any exception during "prepare" or "commit" causes the rollback which clears the local map and unlocks all relevant resources.

  • CONCUR_EXTERNAL

    This concurrency strategy is very similar to the optimistic one, except that no locking is performed during the "prepare" operation and all synchronization and validation are assumed to be done by a supplied Validator.

Author:
gg 2002.03.21
See Also:

  • Field Details

    • TRANSACTION_GET_COMMITTED

      static final int TRANSACTION_GET_COMMITTED
      Dirty gets are prevented; non-repeatable gets and phantom gets can occur. This level only prohibits a transaction from getting an uncommitted values from a map.
      See Also:

    • TRANSACTION_REPEATABLE_GET

      static final int TRANSACTION_REPEATABLE_GET
      Dirty gets and non-repeatable gets are prevented; phantom gets can occur. This level prohibits a transaction from getting an uncommitted values in a map, and it also prohibits the situation where one transaction gets a value, a second transaction alters the value, and the first transaction retrieves the value again, getting a different values the second time (a "non-repeatable get").
      See Also:

    • TRANSACTION_SERIALIZABLE

      static final int TRANSACTION_SERIALIZABLE
      Dirty gets, non-repeatable gets and phantom gets are prevented. This level includes the prohibitions in TRANSACTION_REPEATABLE_GET and further prohibits the situation where one transaction gets an iterator for keys or values, a second transaction inserts a value, and the first transaction requests an iterator again, retrieving the additional "phantom" values the second time.
      See Also:

    • CONCUR_PESSIMISTIC

      static final int CONCUR_PESSIMISTIC
      Pessimistic concurrency. Every time an item is added to the TransactionMap (as a result of either "put", "remove" or "get" operation) the corresponding item is "locked" at the base.
      See Also:

    • CONCUR_OPTIMISTIC

      static final int CONCUR_OPTIMISTIC
      Optimistic concurrency. No locking occurs during "put", "remove" or "get" operations. All synchronization and validation is instead deferred until the "prepare" time.
      See Also:

    • CONCUR_EXTERNAL

      static final int CONCUR_EXTERNAL
      External concurrency. No locking is performed automatically. All synchronization and validation are assumed to be done by a custom transaction Validator during the validate call.
      Since:
      Coherence 3.3
      See Also:

  • Method Details

    • getBaseMap

      ConcurrentMap getBaseMap()
      Return the base map, which contains this TransactionMap's committed data.
      Returns:
      the ConcurrentMap serving as a base for this TransactionMap.

    • getTransactionIsolation

      int getTransactionIsolation()
      Retrieve this TransactionMap's current transaction isolation level.

      The TRANSACTION_* constants defined in this interface are the possible transaction isolation levels.

      Returns:
      the current TRANSACTION_* isolation value

    • setTransactionIsolation

      void setTransactionIsolation(int nLevel)
      Attempt to change the transaction isolation level to the specified value.

      The TRANSACTION_* constants defined in this interface are the possible transaction isolation levels.

      Note: This method cannot be called while in the middle of a transaction.

      Parameters:
      nLevel - one of the TRANSACTION_* isolation values
      Throws:
      IllegalStateException - if the transaction isolation level cannot be changed

    • getConcurrency

      int getConcurrency()
      Retrieve this TransactionMap's current concurrency mode.

      The CONCUR_* constants defined in this interface are the possible concurrency mode values.

      Returns:
      the current CONCUR_* mode

    • setConcurrency

      void setConcurrency(int nConcurrency)
      Attempt to change the concurrency mode to the given value.

      The CONCUR_* constants defined in this interface are the possible concurrency mode values.

      Note: This method cannot be called while in the middle of a transaction.

      Parameters:
      nConcurrency - one of the CONCUR_* mode values
      Throws:
      IllegalStateException - if the concurrency mode cannot be changed

    • isValuesImmutable

      boolean isValuesImmutable()
      Check whether or not the values stored in this TransactionMap are known to be immutable.
      Returns:
      true iff the values are known to be immutable
      Since:
      Coherence 2.3

    • setValuesImmutable

      void setValuesImmutable(boolean fImmutable)
      Specify whether or not the values stored in this TransactionMap are known to be immutable.

      If the values are not known to be immutable, TransactionMap must assume that they are mutable, and will clone the objects returned by the "get" method to ensure that any changes made to those values are rolled back if the transaction is rolled back.

      By explicitly specifying that the values are known to be immutable, the TransactionMap is permitted to skip the cloning step, which may result in better performance.

      Note: This method cannot be called while in the middle of a transaction.

      Parameters:
      fImmutable - true iff the values are known to be immutable
      Throws:
      IllegalStateException - if the setting cannot be changed
      Since:
      Coherence 2.3

    • getTransactionTimeout

      int getTransactionTimeout()
      Retrieve transaction timeout value for this TransactionMap.
      Returns:
      transaction timeout value in seconds.

    • setTransactionTimeout

      void setTransactionTimeout(int cSeconds)
      Set transaction timeout value for this TransactionMap.

      Note: This method cannot be called while in the middle of a transaction.

      Parameters:
      cSeconds - transaction timeout value in seconds. Value of zero means "no timeout".
      Throws:
      IllegalStateException - if the concurrency mode cannot be changed

    • getValidator

      TransactionMap.Validator getValidator()
      Retrieve the topmost Validator in TransactionMap's validation chain.
      Returns:
      the current Validator

    • setValidator

      void setValidator(TransactionMap.Validator validator)
      Add the specified Validator to the top of validation chain for this TransactionMap. The Validator is only used if the concurrency setting is CONCUR_OPTIMISTIC or CONCUR_EXTERNAL.

      Note: This method cannot be called while in the middle of a transaction.

      Parameters:
      validator - the Validator to be added
      Throws:
      IllegalStateException - if the validator cannot be added

    • begin

      void begin()
      Start a transaction for this TransactionMap. After this method is called and before commit or rollback are called, attempt to change the concurrency, isolation or timeout value will throw an exception.

      Note: specifc implementations may choose to support the concept of an implicit begin of a transaction making this operation a no-op.

      Throws:
      IllegalStateException - if this TransactionMap has been already started

    • prepare

      void prepare()
      Prepare to commit changes made to the TransactionMap. This phase usually ensures that all resources involved in this transaction are locked at the base map and validated by the current Validator. If this map serves as a base to another (nested) TransactionMap, specific implementations may choose to not allow its data to be prepared until the nested map is either committed or rolled back.
      Throws:
      ConcurrentModificationException - if the changes cannot be prepared due to the concurrency limitations
      IllegalStateException - if this TransactionMap serves as a base to a nested TransactionMap that has not yet been committed or rolled back

    • commit

      void commit()
      Commit the changes made to the TransactionMap. This effectively means copying the content of this map into the base map, clearing the content of this map and releasing all the locks. If this map serves as a base to another (nested) TransactionMap, specific implementations may choose to not allow its data to be committed until the nested map is either committed or rolled back.
      Throws:
      ConcurrentModificationException - if the changes cannot be committed due to the concurrency limitations
      IllegalStateException - if this TransactionMap serves as a base to a nested TransactionMap that has not yet been committed or rolled back

    • rollback

      void rollback()
      Rollback the changes made to the TransactionMap. This effectively means clearing the content of this map and releasing all the locks without changing the content of the base map.