GemFire 5.7

com.gemstone.gemfire.cache
Interface CacheTransactionManager


public interface CacheTransactionManager

The CacheTransactionManager interface allows applications to manage transactions on a per Cache basis.

The life cycle of a GemFire transaction starts with a begin operation. The life cycle ends with either a commit or rollback operation. Between the begin and the commit/rollback are typically Region operations. In general, those that either create, destroy, invalidate or update Region.Entry are considered transactional, that is they modify transactional state.

A GemFire transaction may involve operations on multiple regions, each of which may have different attributes.

While a GemFire transaction and its operations are invoked in the local VM, the resulting transaction state is distributed to other VM's at commit time as per the attributes of each participant Region.

A transaction can have no more than one thread associated with it and conversely a thread can only operate on one transaction at any given time. Child threads will not inherit the existing transaction.

Each of the following methods operate on the current thread. All methods throw CacheClosedException if the Cache is closed.

GemFire Transactions currently only support Read Committed isolation. In addition, they are optimistic transactions in that write locking and conflict checks are performed as part of the commit operation.

For guaranteed Read Committed isolation, avoid making "in place" changes, because such changes will be "seen" by other transactions and break the Read Committed isolation guarantee. e.g.

    CacheTransactionManager txMgr = cache.getCacheTransactionManager();
    txMgr.begin();
    StringBuffer s = (StringBuffer) r.get("stringBuf");
    s.append("Changes seen before commit. NOT Read Committed!");
    r.put("stringBuf", s);
    txMgr.commit();
  

To aid in creating copies, the "copy on read" Cache attribute and the CopyHelper.copy(java.lang.Object) method are provided. The following is a Read Committed safe example using the CopyHelper.copy method.

    CacheTransactionManager txMgr = cache.getCacheTransactionManager();
    txMgr.begin();
    Object o = r.get("stringBuf");
    StringBuffer s = (StringBuffer) CopyHelper.copy(o);
    s.append("Changes unseen before commit. Read Committed.");
    r.put("stringBuf", s);
    txMgr.commit();
  

Its important to note that creating copies can negatively impact both performance and memory consumption.

Distributed No Ack and Distributed Ack Regions are supported (see AttributesFactory for Scope). For both scopes, a consistent configuration (per VM) is enforced.

Global Regions, client Regions (see com.gemstone.gemfire.cache.client) and persistent Regions (see DiskWriteAttributes) do not support transactions.

Since:
4.0
See Also:
Cache

Method Summary
 void addListener(TransactionListener aListener)
          Adds a transaction listener to the end of the list of transaction listeners on this cache.
 void begin()
          Creates a new transaction and associates it with the current thread.
 void commit()
          Commit the transaction associated with the current thread.
 boolean exists()
          Reports the existence of a Transaction for this thread
 TransactionListener getListener()
          Deprecated. as of GemFire 5.0, use getListeners() instead
 TransactionListener[] getListeners()
          Returns an array of all the transaction listeners on this cache.
 TransactionId getTransactionId()
          Returns the transaction identifier for the current thread
 void initListeners(TransactionListener[] newListeners)
          Removes all transaction listeners, calling CacheCallback.close() on each of them, and then adds each listener in the specified array.
 void removeListener(TransactionListener aListener)
          Removes a transaction listener from the list of transaction listeners on this cache.
 void rollback()
          Roll back the transaction associated with the current thread.
 TransactionListener setListener(TransactionListener newListener)
          Deprecated. as of GemFire 5.0, use addListener(com.gemstone.gemfire.cache.TransactionListener) or initListeners(com.gemstone.gemfire.cache.TransactionListener[]) instead.
 

Method Detail

begin

void begin()
Creates a new transaction and associates it with the current thread.

Throws:
IllegalStateException - if the thread is already associated with a transaction
Since:
4.0

commit

void commit()
            throws CommitConflictException
Commit the transaction associated with the current thread. If the commit operation fails due to a conflict it will destroy the transaction state and throw a CommitConflictException. If the commit operation succeeds, it returns after the transaction state has been merged with committed state. When this method completes, the thread is no longer associated with a transaction.

Throws:
IllegalStateException - if the thread is not associated with a transaction
CommitConflictException - if the commit operation fails due to a write conflict.

rollback

void rollback()
Roll back the transaction associated with the current thread. When this method completes, the thread is no longer associated with a transaction and the transaction context is destroyed.

Throws:
IllegalStateException - if the thread is not associated with a transaction
Since:
4.0

exists

boolean exists()
Reports the existence of a Transaction for this thread

Returns:
true if a transaction exists, false otherwise
Since:
4.0

getTransactionId

TransactionId getTransactionId()
Returns the transaction identifier for the current thread

Returns:
the transaction identifier or null if no transaction exists
Since:
4.0

getListener

TransactionListener getListener()
Deprecated. as of GemFire 5.0, use getListeners() instead

Gets the transaction listener for this Cache.

Returns:
The TransactionListener instance or null if no listener.
Throws:
IllegalStateException - if more than one listener exists on this cache

getListeners

TransactionListener[] getListeners()
Returns an array of all the transaction listeners on this cache. Modifications to the returned array will not effect what listeners are on this cache.

Returns:
the cache's TransactionListeners; an empty array if no listeners
Since:
5.0

setListener

TransactionListener setListener(TransactionListener newListener)
Deprecated. as of GemFire 5.0, use addListener(com.gemstone.gemfire.cache.TransactionListener) or initListeners(com.gemstone.gemfire.cache.TransactionListener[]) instead.

Sets the transaction listener for this Cache.

Parameters:
newListener - the TransactionListener to register with the Cache. Use a null to deregister the current listener without registering a new one.
Returns:
the previous TransactionListener
Throws:
IllegalStateException - if more than one listener exists on this cache

addListener

void addListener(TransactionListener aListener)
Adds a transaction listener to the end of the list of transaction listeners on this cache.

Parameters:
aListener - the user defined transaction listener to add to the cache.
Throws:
IllegalArgumentException - if aListener is null
Since:
5.0

removeListener

void removeListener(TransactionListener aListener)
Removes a transaction listener from the list of transaction listeners on this cache. Does nothing if the specified listener has not been added. If the specified listener has been added then CacheCallback.close() will be called on it; otherwise does nothing.

Parameters:
aListener - the transaction listener to remove from the cache.
Throws:
IllegalArgumentException - if aListener is null
Since:
5.0

initListeners

void initListeners(TransactionListener[] newListeners)
Removes all transaction listeners, calling CacheCallback.close() on each of them, and then adds each listener in the specified array.

Parameters:
newListeners - a possibly null or empty array of listeners to add to this cache.
Throws:
IllegalArgumentException - if the newListeners array has a null element
Since:
5.0

GemFire 5.7

Copyright © 2002-2008 GemStone Systems, Inc. All Rights Reserved.