Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.util
Interface TransactionMap

All Superinterfaces:
  ConcurrentMap, java.util.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`
  - `TRANSACTION_GET_COMMITTED`
    no additional processing
  - `TRANSACTION_REPEATABLE_GET`
    "get" operations move the retrieved values into the local map
  - `TRANSACTION_SERIALIZABLE`
    same as TRANSACTION_REPEATABLE_GET plus "keySet" operations move all the values to the local map and "disconnect" the base to prevent the "phantom" gets
  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.

Nested Class Summary
`static interface` | `TransactionMap.Validator` A callback interface used by TransactionMap implementations.

Nested classes/interfaces inherited from interface java.util.Map
`java.util.Map.Entry`

Field Summary
`static int` | `CONCUR_EXTERNAL` External concurrency.
`static int` | `CONCUR_OPTIMISTIC` Optimistic concurrency.
`static int` | `CONCUR_PESSIMISTIC` Pessimistic concurrency.
`static int` | `TRANSACTION_GET_COMMITTED` Dirty gets are prevented; non-repeatable gets and phantom gets can occur.
`static int` | `TRANSACTION_REPEATABLE_GET` Dirty gets and non-repeatable gets are prevented; phantom gets can occur.
`static int` | `TRANSACTION_SERIALIZABLE` Dirty gets, non-repeatable gets and phantom gets are prevented.

Fields inherited from interface com.tangosol.util.ConcurrentMap
`LOCK_ALL`

Method Summary
`void` | `begin()` Start a transaction for this TransactionMap.
`void` | `commit()` Commit the changes made to the TransactionMap.
`ConcurrentMap` | `getBaseMap()` Return the base map, which contains this TransactionMap's committed data.
`int` | `getConcurrency()` Retrieve this TransactionMap's current concurrency mode.
`int` | `getTransactionIsolation()` Retrieve this TransactionMap's current transaction isolation level.
`int` | `getTransactionTimeout()` Retrieve transaction timeout value for this TransactionMap.
`TransactionMap.Validator` | `getValidator()` Retrieve the topmost Validator in TransactionMap's validation chain.
`boolean` | `isValuesImmutable()` Check whether or not the values stored in this TransactionMap are known to be immutable.
`void` | `prepare()` Prepare to commit changes made to the TransactionMap.
`void` | `rollback()` Rollback the changes made to the TransactionMap.
`void` | `setConcurrency(int nConcurrency)` Attempt to change the concurrency mode to the given value.
`void` | `setTransactionIsolation(int nLevel)` Attempt to change the transaction isolation level to the specified value.
`void` | `setTransactionTimeout(int cSeconds)` Set transaction timeout value for this TransactionMap.
`void` | `setValidator(TransactionMap.Validator validator)` Add the specified Validator to the top of validation chain for this TransactionMap.
`void` | `setValuesImmutable(boolean fImmutable)` Specify whether or not the values stored in this TransactionMap are known to be immutable.

Methods inherited from interface com.tangosol.util.ConcurrentMap
`clear, containsKey, containsValue, get, isEmpty, lock, lock, put, putAll, remove, size, unlock`

Methods inherited from interface java.util.Map
`entrySet, equals, hashCode, keySet, values`

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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.util.ConcurrentModificationException` - if the changes cannot be prepared due to the concurrency limitations
    `java.lang.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:
    `java.util.ConcurrentModificationException` - if the changes cannot be committed due to the concurrency limitations
    `java.lang.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.

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.