net.sf.ehcache.store
Class FrontEndCacheTier<T extends TierableStore,U extends TierableStore>

java.lang.Object
  net.sf.ehcache.store.AbstractStore
      net.sf.ehcache.store.FrontEndCacheTier<T,U>

Type Parameters:

T - the cache tier store type

U - the authority tier store type

All Implemented Interfaces:

Store

Direct Known Subclasses:

DiskBackedMemoryStore, MemoryOnlyStore

public abstract class FrontEndCacheTier<T extends TierableStore,U extends TierableStore>
extends AbstractStore

Abstract class for stores which combine two other stores, one caching the other (aka authority)'s elements.

Author:

Chris Dennis, Ludovic Orban

Field Summary

protected U	authority The authority tier store
protected T	cache The cache tier store

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

attributeExtractors

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

CLUSTER_COHERENT, NODE_COHERENT

Constructor Summary

FrontEndCacheTier(T cache, U authority, ReadWriteCopyStrategy<Element> copyStrategy, SearchManager searchManager, boolean copyOnWrite, boolean copyOnRead)
Constructor for FrontEndCacheTier

Method Summary

boolean	bufferFull() Some store types, such as the disk stores can fill their write buffers if puts come in too fast.
boolean	containsKey(Object key) A check to see if a key is in the Store.
boolean	containsKeyInMemory(Object key) A check to see if a key is in the Store and is currently held in memory.
boolean	containsKeyOffHeap(Object key) A check to see if a key is in the Store and is currently held off-heap.
boolean	containsKeyOnDisk(Object key) A check to see if a key is in the Store and is currently held on disk.
protected Element	copyElementForReadIfNeeded(Element element) Perform copy on read on an element if configured
protected Element	copyElementForWriteIfNeeded(Element element) Perform copy on write on an element if configured
void	dispose() Prepares for shutdown.
void	expireElements() Expire all elements.
void	flush() Flush elements to persistent store.
Element	get(Object key) Gets an item from the cache.
protected List<ReadWriteLockSync>	getAllLocks() Returns all ReadWriteLockSyncs guarding this store.
Policy	getInMemoryEvictionPolicy()
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.
Object	getInternalContext() This should not be used, and will generally return null
List<?>	getKeys() Gets an Array of the keys for all elements in the disk store.
ReadWriteLock	getLockFor(Object key) Returns the ReadWriteLock guarding this key.
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.
Element	getQuiet(Object key) Gets an Element from the Store, without updating statistics
int	getSize() Returns the current local store size
Status	getStatus() Returns the cache status.
int	getTerracottaClusteredSize() Returns the current Terracotta clustered store size
boolean	hasAbortedSizeOf() Checks if the cache may contain elements for which the SizeOf engine gave up and only partially calculated the size.
boolean	isCached(Object key) Checks whether the key is held in the fronting cache
boolean	isEvictionCandidate(Element e) Checks whether the element can be safely evicted.
boolean	isPinned(Object key) Check if the key is pinned
boolean	notifyEvictionFromCache(Serializable key) Whether evicting this from the cache should fire when evicting from upper tiers
boolean	put(Element e) Puts an item into the store.
Element	putIfAbsent(Element e) Put an element in the store if no element is currently mapped to the elements key.
boolean	putWithWriter(Element e, CacheWriterManager writer) Puts an item into the store and the cache writer manager in an atomic operation
void	recalculateSize(Object key) Recalculate size of the element mapped to the key
Element	remove(Object key) Removes an item from the cache.
void	removeAll() Remove all of the elements from the store.
Element	removeElement(Element e, ElementValueComparator comparator) 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(Object key, CacheWriterManager writerManager) Removes an item from the store and the cache writer manager in an atomic operation.
Element	replace(Element e) Replace the cached element only if an Element is currently cached for this key
boolean	replace(Element old, Element e, ElementValueComparator comparator) 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) Sets the eviction policy strategy.
void	setPinned(Object key, boolean pinned) Mark the key as pinned or not
void	unpinAll() unpin all pinned keys

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

addStoreListener, executeQuery, getAll, getAllQuiet, getEventListenerList, getSearchAttribute, isCacheCoherent, isClusterCoherent, isNodeCoherent, putAll, removeAll, removeStoreListener, setAttributeExtractors, setNodeCoherent, waitUntilClusterCoherent

Methods inherited from class java.lang.Object

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

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

getMBean

Field Detail

cache

protected final T extends TierableStore cache

The cache tier store

authority

protected final U extends TierableStore authority

The authority tier store

Constructor Detail

FrontEndCacheTier

public FrontEndCacheTier(T cache,
                         U authority,
                         ReadWriteCopyStrategy<Element> copyStrategy,
                         SearchManager searchManager,
                         boolean copyOnWrite,
                         boolean copyOnRead)

Constructor for FrontEndCacheTier

Parameters:

cache - the caching tier

authority - the authority tier

copyStrategy - the copyStrategy to use

searchManager - the search manager to use

copyOnWrite - whether to copy on writes, false otherwise

copyOnRead - whether to copy on reads, false otherwise

Method Detail

unpinAll

public void unpinAll()

unpin all pinned keys

isPinned

public boolean isPinned(Object key)

Check if the key is pinned

Parameters:

key - the key to be checked

Returns:

true if the element is pinned

setPinned

public void setPinned(Object key,
                      boolean pinned)

Mark the key as pinned or not

Parameters:

key - the key to be pinned or not

pinned - true if the key should be pinned, false otherwise

copyElementForReadIfNeeded

protected Element copyElementForReadIfNeeded(Element element)

Perform copy on read on an element if configured

Parameters:

element - the element to copy for read

Returns:

a copy of the element with the reconstructed original value

copyElementForWriteIfNeeded

protected Element copyElementForWriteIfNeeded(Element element)

Perform copy on write on an element if configured

Parameters:

element - the element to copy for write

Returns:

a copy of the element with a storage-ready value

get

public Element get(Object key)

Gets an item from the cache.

getQuiet

public Element getQuiet(Object key)

Gets an Element from the Store, without updating statistics

Returns:

The element

put

public boolean put(Element e)

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.

putWithWriter

public boolean putWithWriter(Element e,
                             CacheWriterManager writer)

Puts an item into the store and the cache writer manager in an atomic operation

Returns:

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

remove

public Element remove(Object key)

Removes an item from the cache.

removeWithWriter

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

Removes an item from the store and the cache writer manager in an atomic operation.

Throws:

CacheException

putIfAbsent

public Element putIfAbsent(Element e)
                    throws NullPointerException

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

Parameters:

e - element to be added

Returns:

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

Throws:

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

removeElement

public Element removeElement(Element e,
                             ElementValueComparator comparator)
                      throws 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. This is a CAS operation. It is consistent even against a distributed cache that is not coherent. If the old value is stale when this operation is attempted the remove does not take place.

Parameters:

e - Element to be removed

comparator - ElementValueComparator to use to compare elements

Returns:

the Element removed or null if no Element was removed

Throws:

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

replace

public boolean replace(Element old,
                       Element e,
                       ElementValueComparator comparator)
                throws NullPointerException,
                       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

e - Element to be cached

comparator - ElementValueComparator to use to compare elements

Returns:

true is the Element was replaced

Throws:

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

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

replace

public Element replace(Element e)
                throws NullPointerException

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

Parameters:

e - Element to be cached

Returns:

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

Throws:

NullPointerException - if the Element is null or has a null key

containsKey

public boolean containsKey(Object key)

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

Parameters:

key - The Element key

Returns:

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

containsKeyOnDisk

public boolean containsKeyOnDisk(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.

containsKeyOffHeap

public boolean containsKeyOffHeap(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.

containsKeyInMemory

public boolean containsKeyInMemory(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.

getKeys

public List<?> getKeys()

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

Returns:

An List of Serializable keys

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()

Prepares for shutdown.

getSize

public int getSize()

Returns the current local store size

Returns:

the count of the Elements in the Store 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

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

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

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

expireElements

public void expireElements()

Expire all elements.

flush

public void flush()
           throws IOException

Flush elements to persistent store.

Throws:

IOException - if any IO error occurs

bufferFull

public boolean bufferFull()

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.

getLockFor

public ReadWriteLock getLockFor(Object key)

Returns the ReadWriteLock guarding this key.

Parameters:

key - key of interest

Returns:

lock for the supplied key

getAllLocks

protected List<ReadWriteLockSync> getAllLocks()

Returns all ReadWriteLockSyncs guarding this store.

getStatus

public Status getStatus()

Returns the cache status.

getInMemoryEvictionPolicy

public Policy getInMemoryEvictionPolicy()

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)

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 final Object getInternalContext()

This should not be used, and will generally return null

Returns:

some internal context (probably null)

isEvictionCandidate

public boolean isEvictionCandidate(Element e)

Checks whether the element can be safely evicted. It is done by checking whether we can lock the master lock for that Element's key and, if we could, remove that key from all other tiers, but the lowest.

Failing to obey this, might result in firing an Element Evicted Event, while it is still present in higher tiers

Parameters:

e - The element we want to evict

Returns:

true, if it can be evicted, false otherwise

isCached

public boolean isCached(Object key)

Checks whether the key is held in the fronting cache

Parameters:

key - the key to check for

Returns:

true if cached, false otherwise

notifyEvictionFromCache

public boolean notifyEvictionFromCache(Serializable key)

Whether evicting this from the cache should fire when evicting from upper tiers

Parameters:

key - the key to the element

Returns:

true if we should fire, otherwise false

hasAbortedSizeOf

public boolean hasAbortedSizeOf()

Checks if the cache may contain elements for which the SizeOf engine gave up and only partially calculated the size.

Specified by:

hasAbortedSizeOf in interface Store

Overrides:

hasAbortedSizeOf in class AbstractStore

Returns:

true if at least one partially sized element may be in the cache

recalculateSize

public void recalculateSize(Object key)

Description copied from class: AbstractStore

Recalculate size of the element mapped to the key

Specified by:

recalculateSize in interface Store

Overrides:

recalculateSize in class AbstractStore

Parameters:

key - the key