Skip navigation links

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.

Skip navigation links