CoherenceTM v3.4
Copyright© 2000-2008 by Oracle Corporation

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.

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.


CoherenceTM v3.4
Copyright© 2000-2008 by Oracle Corporation