ehcache

net.sf.ehcache.store.compound
Class CompoundStore

java.lang.Object
  extended by net.sf.ehcache.store.AbstractStore
      extended by net.sf.ehcache.store.compound.CompoundStore
All Implemented Interfaces:
Store
Direct Known Subclasses:
DiskPersistentStore, MemoryOnlyStore, OverflowToDiskStore

public abstract class CompoundStore
extends AbstractStore

The store used by default in Ehcache version 2. It is compound in the sense that whether the element is in memory or on disk, the key is held in memory. This store does not suffer from races which could occur in the older MemoryStore and DiskStore which could theoretically cause a cache miss if an element was moving between the stores due to overflow or retrieval. Subclasses allow for memory only, overflow to disk and persist to disk.

Author:
Chris Dennis

Field Summary
 
Fields inherited from interface net.sf.ehcache.store.Store
CLUSTER_COHERENT, NODE_COHERENT
 
Constructor Summary
CompoundStore(net.sf.ehcache.store.compound.InternalElementSubstituteFactory<?> primary, boolean copyOnRead, boolean copyOnWrite, ReadWriteCopyStrategy<Element> copyStrategy)
          Create a CompoundStore using the supplied factory as the primary factory.
CompoundStore(net.sf.ehcache.store.compound.InternalElementSubstituteFactory<?> primary, IdentityElementSubstituteFactory identity)
          Create a CompoundStore using the supplied primary, and designated identity factory.
CompoundStore(net.sf.ehcache.store.compound.InternalElementSubstituteFactory<?> primary, IdentityElementSubstituteFactory identity, boolean copyOnRead, boolean copyOnWrite, ReadWriteCopyStrategy<Element> copyStrategy)
          Create a CompoundStore using the supplied primary, and designated identity factory.
 
Method Summary
 boolean containsKey(Object key)
          A check to see if a key is in the Store.
 void dispose()
          Prepares for shutdown.
 Set<Element> elementSet()
          Get a set view of the elements in this store
 boolean evict(Object key, Object substitute)
          Remove the matching mapping.
 boolean fault(Object key, Object expect, Object fault)
          Atomically switch (CAS) the expect representation of this element for the fault representation.
 Element get(Object key)
          Gets an item from the cache.
 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.
 Element getQuiet(Object key)
          Gets an Element from the Store, without updating statistics
<T> List<T>
getRandomSample(ElementSubstituteFilter<T> factory, int sampleSize, Object keyHint)
          Select a random sample of elements generated by the supplied factory.
 int getSize()
          Returns the current local store size
 Status getStatus()
          Returns the cache status.
 Set<Object> keySet()
          Get a set view of the keys in this store
 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 putRawIfAbsent(Object key, Object encoded)
          Put the given encoded element directly into the store
 boolean putWithWriter(Element element, CacheWriterManager writerManager)
          Puts an item into the store and the cache writer manager in an atomic operation
 Element remove(Object key)
          Removes an item from the cache.
 void removeAll()
          Remove all of the elements from the store.
 Element removeElement(Element element, 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 element)
          Replace the cached element only if an Element is currently cached for this key
 boolean replace(Element old, Element element, ElementValueComparator comparator)
          Replace the cached element only if the value of the current Element is equal to the value of the supplied old Element.
 boolean tryFault(Object key, Object expect, Object fault)
          Try to atomically switch (CAS) the expect representation of this element for the fault representation.
 Object unretrievedGet(Object key)
          Return the unretrieved (undecoded) value for this key
 
Methods inherited from class net.sf.ehcache.store.AbstractStore
addStoreListener, executeQuery, getEventListenerList, getSearchAttribute, isCacheCoherent, isClusterCoherent, isNodeCoherent, 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
bufferFull, containsKeyInMemory, containsKeyOffHeap, containsKeyOnDisk, expireElements, flush, getInMemoryEvictionPolicy, getInMemorySize, getInMemorySizeInBytes, getMBean, getOffHeapSize, getOffHeapSizeInBytes, getOnDiskSize, getOnDiskSizeInBytes, getTerracottaClusteredSize, setInMemoryEvictionPolicy
 

Constructor Detail

CompoundStore

public CompoundStore(net.sf.ehcache.store.compound.InternalElementSubstituteFactory<?> primary,
                     boolean copyOnRead,
                     boolean copyOnWrite,
                     ReadWriteCopyStrategy<Element> copyStrategy)
Create a CompoundStore using the supplied factory as the primary factory.

Parameters:
primary - factory which new elements are passed through
copyOnRead - true should we copy Elements on reads, otherwise false
copyOnWrite - true should we copy Elements on writes, otherwise false
copyStrategy - the strategy to copy elements (needs to be non null if copyOnRead or copyOnWrite is true)

CompoundStore

public CompoundStore(net.sf.ehcache.store.compound.InternalElementSubstituteFactory<?> primary,
                     IdentityElementSubstituteFactory identity)
Create a CompoundStore using the supplied primary, and designated identity factory.

Parameters:
primary - factory which new elements are passed through
identity - factory which performs identity substitution

CompoundStore

public CompoundStore(net.sf.ehcache.store.compound.InternalElementSubstituteFactory<?> primary,
                     IdentityElementSubstituteFactory identity,
                     boolean copyOnRead,
                     boolean copyOnWrite,
                     ReadWriteCopyStrategy<Element> copyStrategy)
Create a CompoundStore using the supplied primary, and designated identity factory.

Parameters:
primary - factory which new elements are passed through
identity - factory which performs identity substitution
copyOnRead - true should we copy Elements on reads, otherwise false
copyOnWrite - true should we copy Elements on writes, otherwise false
copyStrategy - the strategy to copy elements (needs to be non null if copyOnRead or copyOnWrite is true)
Method Detail

put

public boolean put(Element element)
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 element,
                             CacheWriterManager writerManager)
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.

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

unretrievedGet

public Object unretrievedGet(Object key)
Return the unretrieved (undecoded) value for this key

Parameters:
key - key to lookup
Returns:
Element or ElementSubstitute

putRawIfAbsent

public boolean putRawIfAbsent(Object key,
                              Object encoded)
Put the given encoded element directly into the store


getKeys

public List getKeys()
Gets an Array of the keys for all elements in the disk store.

Returns:
An List of Serializable keys

keySet

public Set<Object> keySet()
Get a set view of the keys in this store


elementSet

public Set<Element> elementSet()
Get a set view of the elements in this store

Returns:
element set

remove

public Element remove(Object key)
Removes an item from the cache.


removeWithWriter

public Element removeWithWriter(Object key,
                                CacheWriterManager writerManager)
Removes an item from the store and the cache writer manager in an atomic operation.


removeAll

public void removeAll()
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.


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

getStatus

public Status getStatus()
Returns the cache status.


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

getInternalContext

public Object getInternalContext()
This should not be used, and will generally return null

Returns:
some internal context (probably null)

putIfAbsent

public Element putIfAbsent(Element element)
                    throws 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:
NullPointerException - if the element is null, or has a null key

removeElement

public Element removeElement(Element element,
                             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:
element - 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 element,
                       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
element - 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 element)
                throws 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:
NullPointerException - if the Element is null or has a null key

fault

public boolean fault(Object key,
                     Object expect,
                     Object fault)
Atomically switch (CAS) the expect representation of this element for the fault representation.

A successful switch will return true, and free the replaced element/element-proxy. A failed switch will return false and free the element/element-proxy which was not installed.

Parameters:
key - key to which this element (proxy) is mapped
expect - element (proxy) expected
fault - element (proxy) to install
Returns:
true if fault was installed

tryFault

public boolean tryFault(Object key,
                        Object expect,
                        Object fault)
Try to atomically switch (CAS) the expect representation of this element for the fault representation.

A successful switch will return true, and free the replaced element/element-proxy. A failed switch will return false and free the element/element-proxy which was not installed. Unlike fault this method can return false if the object could not be installed due to lock contention.

Parameters:
key - key to which this element (proxy) is mapped
expect - element (proxy) expected
fault - element (proxy) to install
Returns:
true if fault was installed

evict

public boolean evict(Object key,
                     Object substitute)
Remove the matching mapping. The evict method does referential comparison of the unretrieved substitute against the argument value.

Parameters:
key - key to match against
substitute - optional value to match against
Returns:
true on a successful remove

getRandomSample

public <T> List<T> getRandomSample(ElementSubstituteFilter<T> factory,
                                   int sampleSize,
                                   Object keyHint)
Select a random sample of elements generated by the supplied factory.

Type Parameters:
T - type of the elements or element substitutes
Parameters:
factory - generator of the given type
sampleSize - minimum number of elements to return
keyHint - a key on which we are currently working
Returns:
list of sampled elements/element substitute

ehcache

true