net.sf.ehcache.store
Class XATransactionalStore

java.lang.Object
  net.sf.ehcache.store.AbstractStore
      net.sf.ehcache.store.XATransactionalStore

All Implemented Interfaces:

Store

public class XATransactionalStore
extends AbstractStore

A transaction aware store that wraps the actual Store. It will provide proper READ_COMMITED transaction isolation. It does so by queuing write operations on the cache. These will eventually be executed at transaction commit time, or discarded in case of rollback.

Author:

Alex Snaps, Nabib El-Rahman

Field Summary

Fields inherited from interface net.sf.ehcache.store.Store

CLUSTER_COHERENT, NODE_COHERENT

Constructor Summary

XATransactionalStore(Ehcache cache, EhcacheXAStore ehcacheXAStore, TransactionManagerLookup transactionManagerLookup, javax.transaction.TransactionManager txnManager)
Create a store which will wrap another one to provide XA transactions.

Method Summary

boolean	bufferFull() Non transactional Some store types, such as the disk stores can fill their write buffers if puts come in too fast.
boolean	containsKey(java.lang.Object key) A check to see if a key is in the Store.
boolean	containsKeyInMemory(java.lang.Object key) A check to see if a key is in the Store and is currently held in memory.
boolean	containsKeyOffHeap(java.lang.Object key) A check to see if a key is in the Store and is currently held off-heap.
boolean	containsKeyOnDisk(java.lang.Object key) A check to see if a key is in the Store and is currently held on disk.
void	dispose() Non transactional
void	expireElements() Non transactional Expire all elements.
void	flush() Non transactional Flush elements to persistent store.
Element	get(java.lang.Object key) Gets an item from the cache.
Policy	getInMemoryEvictionPolicy() Non transactional
int	getInMemorySize() Returns the current local in-memory store size
long	getInMemorySizeInBytes() Gets the size of the in-memory portion of the store, in bytes.
java.lang.Object	getInternalContext() Non transactional This should not be used, and will generally return null
java.util.List	getKeys() Gets an Array of the keys for all elements in the disk store.
java.lang.Object	getMBean() Optional implementation specific MBean exposed by the store.
int	getOffHeapSize() Returns the current local off-heap store size
long	getOffHeapSizeInBytes() Gets the size of the off-heap portion of the store, in bytes.
int	getOnDiskSize() Returns the current local on-disk store size
long	getOnDiskSizeInBytes() Gets the size of the on-disk portion of the store, in bytes.
EhcacheXAResource	getOrCreateXAResource() This method either returns the XAResource associated with the current transaction or creates a new one if there was none yet.
Element	getQuiet(java.lang.Object key) Gets an Element from the Store, without updating statistics
int	getSize() TransactionContext impacted size of the store
Status	getStatus() Non transactional
int	getTerracottaClusteredSize() Returns the current Terracotta clustered store size
boolean	isCacheCoherent() Non transactional Indicates whether this store provides a coherent view of all the elements in a cache.
boolean	isClusterCoherent() Returns true if the cache is in coherent mode cluster-wide.
boolean	isNodeCoherent() Returns true if the cache is in coherent mode for the current node.
boolean	put(Element element) Puts an item into the store.
Element	putIfAbsent(Element element) Put an element in the store if no element is currently mapped to the elements key.
boolean	putWithWriter(Element element, CacheWriterManager writerManager) XATransactionalStore to put including to the underlying data store.
Element	remove(java.lang.Object key) Removes an item from the cache.
void	removeAll() Remove all of the elements from the store.
Element	removeElement(Element element) Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.
Element	removeWithWriter(java.lang.Object key, CacheWriterManager writerManager) XATransactionalStore to remove including from the underlying data store.
Element	replace(Element element) Replace the cached element only if an Element is currently cached for this key
boolean	replace(Element old, Element element) Replace the cached element only if the value of the current Element is equal to the value of the supplied old Element.
void	setInMemoryEvictionPolicy(Policy policy) Non transactional Sets the eviction policy strategy.
void	setNodeCoherent(boolean coherent) Sets the cache in coherent or incoherent mode for the current node depending on the parameter.
void	waitUntilClusterCoherent() This method waits until the cache is in coherent mode in all the connected nodes.

Methods inherited from class net.sf.ehcache.store.AbstractStore

addStoreListener, fireClusterCoherent, fireNodeCoherent, getEventListenerList, removeStoreListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XATransactionalStore

public XATransactionalStore(Ehcache cache,
                            EhcacheXAStore ehcacheXAStore,
                            TransactionManagerLookup transactionManagerLookup,
                            javax.transaction.TransactionManager txnManager)

Create a store which will wrap another one to provide XA transactions.

Parameters:

cache - the cache this store is backing

ehcacheXAStore - the XAStore to be used by this store

transactionManagerLookup - the TransactionManagerLookup used to get hold of the JTA transaction manager

txnManager -

Method Detail

put

public boolean put(Element element)
            throws CacheException

Puts an item into the store.

Returns:

true if this is a new put for the key or element is null. Returns false if it was an update.

Throws:

CacheException

putWithWriter

public boolean putWithWriter(Element element,
                             CacheWriterManager writerManager)
                      throws CacheException

XATransactionalStore to put including to the underlying data store. That needs to be registered with the TransactionManager and participate in the XA Transaction. The call to CacheWriterManager.put(net.sf.ehcache.Element) will be held back until commit time!

Parameters:

element - the element to add to the store

writerManager - will only work properly with WriteThroughManager

Returns:

true if this is a new put for the key or element is null. Returns false if it was an update.

Throws:

CacheException

get

public Element get(java.lang.Object key)

Gets an item from the cache.

getQuiet

public Element getQuiet(java.lang.Object key)

Gets an Element from the Store, without updating statistics

Returns:

The element

getKeys

public final java.util.List getKeys()

Gets an Array of the keys for all elements in the disk store.

Returns:

An List of Serializable keys

remove

public Element remove(java.lang.Object key)

Removes an item from the cache.

removeWithWriter

public Element removeWithWriter(java.lang.Object key,
                                CacheWriterManager writerManager)
                         throws CacheException

XATransactionalStore to remove including from the underlying data store. That needs to be registered with the TransactionManager and participate in the XA Transaction. The call to CacheWriterManager.remove(net.sf.ehcache.CacheEntry) will be not held back until commit time!

Parameters:

key - the key to remove

writerManager - will only work properly with WriteThroughManager

Returns:

the value to be removed

Throws:

CacheException

removeAll

public void removeAll()
               throws CacheException

Remove all of the elements from the store.

If there are registered CacheEventListeners they are notified of the expiry or removal of the Element as each is removed.

Throws:

CacheException

dispose

public void dispose()

Non transactional

Prepares for shutdown.

getSize

public int getSize()

TransactionContext impacted size of the store

Returns:

size of the store, including transaction local pending changes

getOnDiskSize

public int getOnDiskSize()

Returns the current local on-disk store size

Returns:

the count of the Elements in the Store and on-disk on the local machine

getOffHeapSize

public int getOffHeapSize()

Returns the current local off-heap store size

Returns:

the count of the Elements in the Store and off-heap on the local machine

getInMemorySize

public int getInMemorySize()

Returns the current local in-memory store size

Returns:

the count of the Elements in the Store and in-memory on the local machine

getTerracottaClusteredSize

public int getTerracottaClusteredSize()

Returns the current Terracotta clustered store size

Returns:

the count of the Elements in the Store across the cluster

getInMemorySizeInBytes

public long getInMemorySizeInBytes()

Gets the size of the in-memory portion of the store, in bytes.

This method may be expensive to run, depending on implementation. Implementers may choose to return an approximate size.

Returns:

the approximate in-memory size of the store in bytes

getOffHeapSizeInBytes

public long getOffHeapSizeInBytes()

Gets the size of the off-heap portion of the store, in bytes.

Returns:

the approximate off-heap size of the store in bytes

getOnDiskSizeInBytes

public long getOnDiskSizeInBytes()

Gets the size of the on-disk portion of the store, in bytes.

Returns:

the on-disk size of the store in bytes

getStatus

public Status getStatus()

Non transactional

Returns the cache status.

containsKey

public boolean containsKey(java.lang.Object key)

A check to see if a key is in the Store.

Parameters:

key - The Element key

Returns:

whether the element is currently in the cache, or pending put

containsKeyInMemory

public boolean containsKeyInMemory(java.lang.Object key)

A check to see if a key is in the Store and is currently held in memory.

Parameters:

key - The Element key

Returns:

true if found. No check is made to see if the Element is expired.

containsKeyOffHeap

public boolean containsKeyOffHeap(java.lang.Object key)

A check to see if a key is in the Store and is currently held off-heap.

Parameters:

key - The Element key

Returns:

true if found. No check is made to see if the Element is expired.

containsKeyOnDisk

public boolean containsKeyOnDisk(java.lang.Object key)

A check to see if a key is in the Store and is currently held on disk.

Parameters:

key - The Element key

Returns:

true if found. No check is made to see if the Element is expired.

expireElements

public void expireElements()

Non transactional Expire all elements.

flush

public void flush()
           throws java.io.IOException

Non transactional Flush elements to persistent store.

Throws:

java.io.IOException - if any IO error occurs

bufferFull

public boolean bufferFull()

Non transactional Some store types, such as the disk stores can fill their write buffers if puts come in too fast. The thread will wait for a short time before checking again.

Returns:

true if the store write buffer is backed up.

getInMemoryEvictionPolicy

public Policy getInMemoryEvictionPolicy()

Non transactional

Returns:

the current eviction policy. This may not be the configured policy, if it has been dynamically set.

See Also:

Store.setInMemoryEvictionPolicy(Policy)

setInMemoryEvictionPolicy

public void setInMemoryEvictionPolicy(Policy policy)

Non transactional Sets the eviction policy strategy. The Store will use a policy at startup. The store may allow changing the eviction policy strategy dynamically. Otherwise implementations will throw an exception if this method is called.

Parameters:

policy - the new policy

getInternalContext

public java.lang.Object getInternalContext()

Non transactional This should not be used, and will generally return null

Returns:

some internal context (probably null)

isCacheCoherent

public boolean isCacheCoherent()

Non transactional Indicates whether this store provides a coherent view of all the elements in a cache. Note that this is same as calling Store.isClusterCoherent() (introduced since 2.0) Use Store.isNodeCoherent() to find out if the cache is coherent in the current node in the cluster

Specified by:

isCacheCoherent in interface Store

Overrides:

isCacheCoherent in class AbstractStore

Returns:

true if the store is coherent; or false if the store potentially splits the cache storage with another store or isn't internally coherent

See Also:

Store.isCacheCoherent()

isClusterCoherent

public boolean isClusterCoherent()

Returns true if the cache is in coherent mode cluster-wide. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

isClusterCoherent in interface Store

Overrides:

isClusterCoherent in class AbstractStore

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

See Also:

Store.isClusterCoherent()

isNodeCoherent

public boolean isNodeCoherent()

Returns true if the cache is in coherent mode for the current node. Returns false otherwise.

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

isNodeCoherent in interface Store

Overrides:

isNodeCoherent in class AbstractStore

Returns:

true if the cache is in coherent mode cluster-wide, false otherwise

See Also:

Store.isNodeCoherent()

setNodeCoherent

public void setNodeCoherent(boolean coherent)

Sets the cache in coherent or incoherent mode for the current node depending on the parameter. Calling setNodeCoherent(true) when the cache is already in coherent mode or calling setNodeCoherent(false) when already in incoherent mode will be a no-op.

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

setNodeCoherent in interface Store

Overrides:

setNodeCoherent in class AbstractStore

Parameters:

coherent - true transitions to coherent mode, false to incoherent mode

See Also:

Store.setNodeCoherent(boolean)

waitUntilClusterCoherent

public void waitUntilClusterCoherent()

This method waits until the cache is in coherent mode in all the connected nodes. If the cache is already in coherent mode it returns immediately

It applies to coherent clustering mechanisms only e.g. Terracotta

Specified by:

waitUntilClusterCoherent in interface Store

Overrides:

waitUntilClusterCoherent in class AbstractStore

See Also:

Store.waitUntilClusterCoherent()

putIfAbsent

public Element putIfAbsent(Element element)
                    throws java.lang.NullPointerException

Put an element in the store if no element is currently mapped to the elements key.

Parameters:

element - element to be added

Returns:

the element previously cached for this key, or null if none.

Throws:

java.lang.NullPointerException - if the element is null, or has a null key

removeElement

public Element removeElement(Element element)
                      throws java.lang.NullPointerException

Remove the Element mapped to the key for the supplied element if the value of the supplied Element is equal to the value of the cached Element.

Parameters:

element - Element to be removed

Returns:

the Element removed or null if no Element was removed

Throws:

java.lang.NullPointerException - if the element is null, or has a null key

replace

public boolean replace(Element old,
                       Element element)
                throws java.lang.NullPointerException,
                       java.lang.IllegalArgumentException

Replace the cached element only if the value of the current Element is equal to the value of the supplied old Element.

Parameters:

old - Element to be test against

element - Element to be cached

Returns:

true is the Element was replaced

Throws:

java.lang.NullPointerException - if the either Element is null or has a null key

java.lang.IllegalArgumentException - if the two Element keys are non-null but not equal

replace

public Element replace(Element element)
                throws java.lang.NullPointerException

Replace the cached element only if an Element is currently cached for this key

Parameters:

element - Element to be cached

Returns:

the Element previously cached for this key, or null if no Element was cached

Throws:

java.lang.NullPointerException - if the Element is null or has a null key

getOrCreateXAResource

public EhcacheXAResource getOrCreateXAResource()

This method either returns the XAResource associated with the current transaction or creates a new one if there was none yet.

Returns:

the XAResource bound to this transaction

getMBean

public java.lang.Object getMBean()

Optional implementation specific MBean exposed by the store.

Returns:

implementation specific management bean