net.sf.ehcache.transaction.xa
Interface EhcacheXAStore

All Known Implementing Classes:

EhcacheXAStoreImpl

public interface EhcacheXAStore

The EhcacheXAStore is storing XA related data for a Transaction Cache instance on behalf of EhcacheXAResource:

• Maps Xid to their Transaction
• Stores TransactionContext for all Transactions
• Tracks "checked out" versions of keys by active transaction, in order to provide an optimistic locking strategy
• Stores in a persistent manner prepared Transaction data
• Tracks versioning information on keys which are "in commit" phase (prepared, yet not commited yet)

Mapping Xid to Transaction is required as the TransactionManager will only ever reference Xid, while the EhcacheXAResource will only get access to the current Transaction;

Based on that, during the UserTransaction, the TransactionContext will store the Commands for the current Transaction. While on prepare, XAResource.commit(javax.transaction.xa.Xid, boolean) commit}, XAResource.rollback(javax.transaction.xa.Xid) rollback} and other JTA XAResource operations, the EhcacheXAResource will get data back based on the Xid;

When an operation on the Cache involves a key, the EhcacheXAStore will track version information on that key. Version information isn't stored at the Element level, but rather in an independent store to minimize the impact on memory (only Element in use will be versioned, Element "only" referenced by the Cache are not);

When the EhcacheXAResource has successfully prepared a Transaction, it will ask EhcacheXAStore to save that data in a "safe" and persistent place, in case of failure;

The previous version of keys to be updated are "moved" to a read-only oldVersionStore, while the key on the underlying store is write-locked by the EhcacheXAResource. That oldVersionStore will always be accessed first, for read operations, providing non-blocking reads on "in-commit" phase keys.

Author:

Alex Snaps, Nabib El-Rahman

Method Summary

void	checkin(java.lang.Object key, javax.transaction.xa.Xid xid, boolean readOnly) Checks in changes to a key
long	checkout(java.lang.Object key, javax.transaction.xa.Xid xid) Checks a version for en Element out of the store
PreparedContext	createPreparedContext() Return a newly created prepare context if none exist.
TransactionContext	createTransactionContext(javax.transaction.xa.Xid xid) Creates a new TransactionContext for a given Transaction
Store	getOldVersionStore() Getter to the guarding read-only oldVersionStore
PreparedContext	getPreparedContext(javax.transaction.xa.Xid xid) Gets a PreparedContext from a persistent store for a previously prepared Transaction
javax.transaction.xa.Xid[]	getPreparedXids() Lists prepared, yet not commited Xids
TransactionContext	getTransactionContext(javax.transaction.xa.Xid xid) Gets a stored TransactionContext for a given Transaction
Store	getUnderlyingStore() Getter to the underlying store
boolean	isPrepared(javax.transaction.xa.Xid xid) Checks whether a Transaction is prepared
boolean	isValid(VersionAwareCommand command, javax.transaction.xa.Xid xid) Checks whether a command can safely be executed against the store, depending on the version lock
void	prepare(javax.transaction.xa.Xid xid, PreparedContext context) Save the Transaction's data as being prepared
void	removeData(javax.transaction.xa.Xid xid) Removes stored data of a given Xid

Method Detail

createTransactionContext

TransactionContext createTransactionContext(javax.transaction.xa.Xid xid)

Creates a new TransactionContext for a given Transaction

Parameters:

xid - of current transaction

Returns:

a TransactionContext for that Transaction

getTransactionContext

TransactionContext getTransactionContext(javax.transaction.xa.Xid xid)

Gets a stored TransactionContext for a given Transaction

Parameters:

xid - The Xid of the Transaction

Returns:

the matching TransactionContext

checkin

void checkin(java.lang.Object key,
             javax.transaction.xa.Xid xid,
             boolean readOnly)

Checks in changes to a key

Parameters:

key - the key of the affected Element in the Store

xid - the Xid of the Transaction executing the change

readOnly - whether the command modified the underlying Store

checkout

long checkout(java.lang.Object key,
              javax.transaction.xa.Xid xid)

Checks a version for en Element out of the store

Parameters:

key - the key to the Element in the store

xid - the Xid of the Transaction reading

Returns:

the version of the element

isValid

boolean isValid(VersionAwareCommand command,
                javax.transaction.xa.Xid xid)

Checks whether a command can safely be executed against the store, depending on the version lock

Parameters:

command - the Command

Returns:

true if safe, false if cannot be applied anymore

prepare

void prepare(javax.transaction.xa.Xid xid,
             PreparedContext context)

Save the Transaction's data as being prepared

Parameters:

xid - the Xid of the Transaction

context - the context with the transaction data

createPreparedContext

PreparedContext createPreparedContext()

Return a newly created prepare context if none exist.

Returns:

a new PreparedContext

getPreparedXids

javax.transaction.xa.Xid[] getPreparedXids()

Lists prepared, yet not commited Xids

Returns:

array of uncommited, yet prepared xids

getPreparedContext

PreparedContext getPreparedContext(javax.transaction.xa.Xid xid)

Gets a PreparedContext from a persistent store for a previously prepared Transaction

Parameters:

xid - The Xid of the Transaction

Returns:

the Prepared context for the Transaction, or null

getUnderlyingStore

Store getUnderlyingStore()

Getter to the underlying store

Returns:

the store

getOldVersionStore

Store getOldVersionStore()

Getter to the guarding read-only oldVersionStore

Returns:

the oldVersionStore

isPrepared

boolean isPrepared(javax.transaction.xa.Xid xid)

Checks whether a Transaction is prepared

Parameters:

xid - the Xid of the Transaction

Returns:

true if prepared

removeData

void removeData(javax.transaction.xa.Xid xid)

Removes stored data of a given Xid

Parameters:

xid - the Xid of the Transaction