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:
    H.T. KUNG and JOHN T. ROBINSON, On Optimistic Methods for Concurrency Control, ACM Transactions on Database Systems, Vol. 6, No. 2, June 1981.

    • Field Detail

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

    • Method Detail

      • 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.