ehcache

net.sf.ehcache.store.disk
Class DiskStore

java.lang.Object
  extended by net.sf.ehcache.store.AbstractStore
      extended by net.sf.ehcache.store.disk.DiskStore
All Implemented Interfaces:
PoolableStore, Store, StripedReadWriteLockProvider, TierableStore

public final class DiskStore
extends AbstractStore
implements TierableStore, PoolableStore, StripedReadWriteLockProvider

Implements a persistent-to-disk store.

All new elements are automatically scheduled for writing to disk.

Author:
Chris Dennis, Ludovic Orban

Field Summary
 
Fields inherited from class net.sf.ehcache.store.AbstractStore
attributeExtractors
 
Fields inherited from interface net.sf.ehcache.store.Store
CLUSTER_COHERENT, NODE_COHERENT
 
Method Summary
 boolean bufferFull()
          Some store types, such as the disk stores can fill their write buffers if puts come in too fast.
 void changeDiskCapacity(int newCapacity)
          Change the disk capacity, in number of elements
 boolean cleanUpFailedMarker(Serializable key)
          Will check whether a Placeholder that failed to flush to disk is lying around If so, it'll try to evict it
 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.
static DiskStore create(Cache cache)
          Creates a persitent-to-disk store for the given cache, using the given disk path.
static DiskStore create(Ehcache cache, Pool onHeapPool, Pool onDiskPool)
          Creates a persitent-to-disk store for the given cache, using the given disk path.
 StripedReadWriteLock createStripedReadWriteLock()
          Will create a StripedReadWriteLock always using the same spreading function
 void dispose()
          Prepares for shutdown.
 boolean evict(Object key, DiskStorageFactory.DiskSubstitute substitute)
          Remove the matching mapping.
 Element evictElement(Object key, DiskStorageFactory.DiskSubstitute substitute)
          Remove the matching mapping.
 boolean evictFromOnDisk(int count, long size)
          Perform eviction to release on-disk resources
 boolean evictFromOnHeap(int count, long size)
          Perform eviction to release on-heap resources
 void expireElements()
          Expire all elements.
 boolean fault(Object key, net.sf.ehcache.store.disk.DiskStorageFactory.Placeholder expect, DiskStorageFactory.DiskMarker fault)
          Atomically switch (CAS) the expect representation of this element for the fault representation.
 void fill(Element e)
          Add this element to the cache if the key is already present or the add can succeed without resorting to eviction.
 void flush()
          Flush elements to persistent store.
 Element get(Object key)
          Gets an item from the cache.
 long getApproximateDiskByteSize()
          Return the approximate disk size in bytes
 long getApproximateDiskCountSize()
          Return the approximate disk size
 float getApproximateDiskHitRate()
          Return the approximate disk hit rate
 float getApproximateDiskMissRate()
          Return the approximate disk miss rate
 long getApproximateHeapByteSize()
          Return the approximate heap size in bytes
 long getApproximateHeapCountSize()
          Return the approximate heap size
 float getApproximateHeapHitRate()
          Return the approximate heap hit rate
 float getApproximateHeapMissRate()
          Return the approximate heap miss rate
 File getDataFile()
          Return a reference to the data file backing this store.
 File getIndexFile()
          Return a reference to the index file for 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.
 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.
 Set getPresentPinnedKeys()
          Returns all the keys that are pinned, for which there is a mapping present
 Element getQuiet(Object key)
          Gets an Element from the Store, without updating statistics
 List<DiskStorageFactory.DiskSubstitute> getRandomSample(ElementSubstituteFilter 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.
 int getTerracottaClusteredSize()
          Returns the current Terracotta clustered store size
 boolean isPersistent()
          Is this store persistent (data survives a JVM restart)
 boolean isPinned(Object key)
          Check if the key is pinned
 boolean isTierPinned()
          Is this TierableStore pinned ?
 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, DiskStorageFactory.DiskMarker 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.
 boolean removeIfNotPinned(Object key)
          This method will only remove if the element or the store is not pinned and the key is present in the store
 void removeNoReturn(Object key)
          Removes an item from the cache.
 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.
 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
 Object unretrievedGet(Object key)
          Return the unretrieved (undecoded) value for this key
 
Methods inherited from class net.sf.ehcache.store.AbstractStore
addStoreListener, executeQuery, getAll, getAllQuiet, getEventListenerList, getSearchAttribute, hasAbortedSizeOf, isCacheCoherent, isClusterCoherent, isNodeCoherent, putAll, recalculateSize, 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
addStoreListener, executeQuery, getAll, getAllQuiet, getSearchAttribute, hasAbortedSizeOf, isCacheCoherent, isClusterCoherent, isNodeCoherent, putAll, recalculateSize, removeAll, removeStoreListener, setAttributeExtractors, setNodeCoherent, waitUntilClusterCoherent
 

Method Detail

create

public static DiskStore create(Ehcache cache,
                               Pool onHeapPool,
                               Pool onDiskPool)
Creates a persitent-to-disk store for the given cache, using the given disk path.

Parameters:
cache - cache that fronts this store
onHeapPool - pool to track heap usage
onDiskPool - pool to track disk usage
Returns:
a fully initialized store

create

public static DiskStore create(Cache cache)
Creates a persitent-to-disk store for the given cache, using the given disk path. Heap and disk usage are not tracked by the returned store.

Parameters:
cache - cache that fronts this store
Returns:
a fully initialized store

unpinAll

public void unpinAll()
unpin all pinned keys

Specified by:
unpinAll in interface Store

isPinned

public boolean isPinned(Object key)
Check if the key is pinned

Specified by:
isPinned in interface Store
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

Specified by:
setPinned in interface Store
Parameters:
key - the key to be pinned or not
pinned - true if the key should be pinned, false otherwise

cleanUpFailedMarker

public boolean cleanUpFailedMarker(Serializable key)
Will check whether a Placeholder that failed to flush to disk is lying around If so, it'll try to evict it

Parameters:
key - the key
Returns:
true if a failed marker was or is still there, false otherwise

createStripedReadWriteLock

public StripedReadWriteLock createStripedReadWriteLock()
Will create a StripedReadWriteLock always using the same spreading function

Specified by:
createStripedReadWriteLock in interface StripedReadWriteLockProvider
Returns:
a newly created StripedReadWriteLock

changeDiskCapacity

public void changeDiskCapacity(int newCapacity)
Change the disk capacity, in number of elements

Parameters:
newCapacity - the new max elements on disk

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.

Specified by:
bufferFull in interface Store
Returns:
true if the store write buffer is backed up.

containsKeyInMemory

public boolean containsKeyInMemory(Object key)
A check to see if a key is in the Store and is currently held in memory.

Specified by:
containsKeyInMemory in interface Store
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.

Specified by:
containsKeyOffHeap in interface Store
Parameters:
key - The Element key
Returns:
true if found. No check is made to see if the Element is expired.

containsKeyOnDisk

public boolean containsKeyOnDisk(Object key)
A check to see if a key is in the Store and is currently held on disk.

Specified by:
containsKeyOnDisk in interface Store
Parameters:
key - The Element key
Returns:
true if found. No check is made to see if the Element is expired.

expireElements

public void expireElements()
Expire all elements.

Specified by:
expireElements in interface Store

flush

public void flush()
           throws IOException
Flush elements to persistent store.

Specified by:
flush in interface Store
Throws:
IOException - if any IO error occurs

getInMemoryEvictionPolicy

public Policy getInMemoryEvictionPolicy()

Specified by:
getInMemoryEvictionPolicy in interface Store
Returns:
the current eviction policy. This may not be the configured policy, if it has been dynamically set.
See Also:
Store.setInMemoryEvictionPolicy(Policy)

getInMemorySize

public int getInMemorySize()
Returns the current local in-memory store size

Specified by:
getInMemorySize in interface Store
Returns:
the count of the Elements in the Store and in-memory on the local machine

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.

Specified by:
getInMemorySizeInBytes in interface Store
Returns:
the approximate in-memory size of the store in bytes

getOffHeapSize

public int getOffHeapSize()
Returns the current local off-heap store size

Specified by:
getOffHeapSize in interface Store
Returns:
the count of the Elements in the Store and off-heap on the local machine

getOffHeapSizeInBytes

public long getOffHeapSizeInBytes()
Gets the size of the off-heap portion of the store, in bytes.

Specified by:
getOffHeapSizeInBytes in interface Store
Returns:
the approximate off-heap size of the store in bytes

getOnDiskSize

public int getOnDiskSize()
Returns the current local on-disk store size

Specified by:
getOnDiskSize in interface Store
Returns:
the count of the Elements in the Store and on-disk on the local machine

getOnDiskSizeInBytes

public long getOnDiskSizeInBytes()
Gets the size of the on-disk portion of the store, in bytes.

Specified by:
getOnDiskSizeInBytes in interface Store
Returns:
the on-disk size of the store in bytes

getTerracottaClusteredSize

public int getTerracottaClusteredSize()
Returns the current Terracotta clustered store size

Specified by:
getTerracottaClusteredSize in interface Store
Returns:
the count of the Elements in the Store across the cluster

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.

Specified by:
setInMemoryEvictionPolicy in interface Store
Parameters:
policy - the new policy

getDataFile

public File getDataFile()
Return a reference to the data file backing this store.

Returns:
a reference to the data file backing this store.

getIndexFile

public File getIndexFile()
Return a reference to the index file for this store.

Returns:
a reference to the index file for this store.

getMBean

public Object getMBean()
Optional implementation specific MBean exposed by the store.

Specified by:
getMBean in interface Store
Returns:
implementation specific management bean

fill

public void fill(Element e)
Add this element to the cache if the key is already present or the add can succeed without resorting to eviction.

Specified by:
fill in interface TierableStore
Parameters:
e - element to be added

removeIfNotPinned

public boolean removeIfNotPinned(Object key)
This method will only remove if the element or the store is not pinned and the key is present in the store

Specified by:
removeIfNotPinned in interface TierableStore
Parameters:
key - the key to the element
Returns:
true if an element was removed
See Also:
Store.remove(Object)

put

public boolean put(Element element)
Puts an item into the store.

Specified by:
put in interface 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

Specified by:
putWithWriter in interface Store
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.

Specified by:
get in interface Store

getQuiet

public Element getQuiet(Object key)
Gets an Element from the Store, without updating statistics

Specified by:
getQuiet in interface Store
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,
                              DiskStorageFactory.DiskMarker encoded)
                       throws IllegalArgumentException
Put the given encoded element directly into the store

Parameters:
key - the key of the element
encoded - the encoded element
Returns:
true if the encoded element was installed
Throws:
IllegalArgumentException - if the supplied key is already present

getKeys

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

Specified by:
getKeys in interface Store
Returns:
An List of Serializable keys

keySet

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

Returns:
a set view of the keys in this store

remove

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

Specified by:
remove in interface Store

removeNoReturn

public void removeNoReturn(Object key)
Removes an item from the cache.

Specified by:
removeNoReturn in interface TierableStore

isTierPinned

public boolean isTierPinned()
Is this TierableStore pinned ?

Specified by:
isTierPinned in interface TierableStore
Returns:
true if pinned

getPresentPinnedKeys

public Set getPresentPinnedKeys()
Returns all the keys that are pinned, for which there is a mapping present

Specified by:
getPresentPinnedKeys in interface TierableStore
Returns:
the set of keys with values that are currently pinned

isPersistent

public boolean isPersistent()
Is this store persistent (data survives a JVM restart)

Specified by:
isPersistent in interface TierableStore
Returns:
true if persistent

removeWithWriter

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

Specified by:
removeWithWriter in interface Store

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.

Specified by:
removeAll in interface Store

dispose

public void dispose()
Prepares for shutdown.

Specified by:
dispose in interface Store

getSize

public int getSize()
Returns the current local store size

Specified by:
getSize in interface Store
Returns:
the count of the Elements in the Store on the local machine

getStatus

public Status getStatus()
Returns the cache status.

Specified by:
getStatus in interface Store

evictFromOnHeap

public boolean evictFromOnHeap(int count,
                               long size)
Perform eviction to release on-heap resources

Specified by:
evictFromOnHeap in interface PoolableStore
Parameters:
count - the number of elements to evict
size - the size in bytes to free (hint)
Returns:
true if the requested number of elements could be evicted

evictFromOnDisk

public boolean evictFromOnDisk(int count,
                               long size)
Perform eviction to release on-disk resources

Specified by:
evictFromOnDisk in interface PoolableStore
Parameters:
count - the number of elements to evict
size - the size in bytes to free (hint)
Returns:
true if the requested number of elements could be evicted

getApproximateDiskHitRate

public float getApproximateDiskHitRate()
Return the approximate disk hit rate

Specified by:
getApproximateDiskHitRate in interface PoolableStore
Returns:
the approximate disk hit rate

getApproximateDiskMissRate

public float getApproximateDiskMissRate()
Return the approximate disk miss rate

Specified by:
getApproximateDiskMissRate in interface PoolableStore
Returns:
the approximate disk miss rate

getApproximateDiskCountSize

public long getApproximateDiskCountSize()
Return the approximate disk size

Specified by:
getApproximateDiskCountSize in interface PoolableStore
Returns:
the approximate disk size

getApproximateDiskByteSize

public long getApproximateDiskByteSize()
Return the approximate disk size in bytes

Specified by:
getApproximateDiskByteSize in interface PoolableStore
Returns:
the approximate disk size in bytes

getApproximateHeapHitRate

public float getApproximateHeapHitRate()
Return the approximate heap hit rate

Specified by:
getApproximateHeapHitRate in interface PoolableStore
Returns:
the approximate heap hit rate

getApproximateHeapMissRate

public float getApproximateHeapMissRate()
Return the approximate heap miss rate

Specified by:
getApproximateHeapMissRate in interface PoolableStore
Returns:
the approximate heap miss rate

getApproximateHeapCountSize

public long getApproximateHeapCountSize()
Return the approximate heap size

Specified by:
getApproximateHeapCountSize in interface PoolableStore
Returns:
the approximate heap size

getApproximateHeapByteSize

public long getApproximateHeapByteSize()
Return the approximate heap size in bytes

Specified by:
getApproximateHeapByteSize in interface PoolableStore
Returns:
the approximate heap size in bytes

containsKey

public boolean containsKey(Object key)
A check to see if a key is in the Store.

Specified by:
containsKey in interface 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

Specified by:
getInternalContext in interface Store
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.

Specified by:
putIfAbsent in interface Store
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.

Specified by:
removeElement in interface Store
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.

Specified by:
replace in interface Store
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

Specified by:
replace in interface Store
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,
                     net.sf.ehcache.store.disk.DiskStorageFactory.Placeholder expect,
                     DiskStorageFactory.DiskMarker 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

evict

public boolean evict(Object key,
                     DiskStorageFactory.DiskSubstitute 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

evictElement

public Element evictElement(Object key,
                            DiskStorageFactory.DiskSubstitute 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:
the evicted element on a successful remove

getRandomSample

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

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

Copyright © 2003-2014 Terracotta, Inc.. All Rights Reserved.