net.sf.ehcache.store
Class DiskStore

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

All Implemented Interfaces:

CacheConfigurationListener, Store

public class DiskStore
extends AbstractStore
implements CacheConfigurationListener

A disk store implementation.

As of ehcache-1.2 (v1.41 of this file) DiskStore has been changed to a mix of finer grained locking using synchronized collections and synchronizing on the whole instance, as was the case with earlier versions.

The DiskStore, as of ehcache-1.2.4, supports eviction using an LFU policy, if a maximum disk store size is set. LFU uses statistics held at the Element level which survive moving between maps in the MemoryStore and DiskStores.

As of ehcache-2.0, a cache can be configured with a DiskStore with multiple stripes. This enables much higher throughput.

Version:

$Id: DiskStore.java 3115 2010-11-04 08:23:37Z lorban $

Author:

Adam Murdoch, Greg Luck, patches contributed: Ben Houston, patches contributed: James Abley, patches contributed: Manuel Dominguez Sarmiento

Nested Class Summary

static class

DiskStore.DiskElement A reference to an on-disk elements.

Field Summary

static String

AUTO_DISK_PATH_DIRECTORY_PREFIX If the CacheManager needs to resolve a conflict with the disk path, it will create a subdirectory in the given disk path with this prefix followed by a number.

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

CLUSTER_COHERENT, NODE_COHERENT

Constructor Summary

protected

DiskStore(Ehcache cache, String diskPath) Creates a disk store.

Method Summary

boolean	bufferFull() In some circumstances data can be written so quickly to the spool that the VM runs out of memory while waiting for the spooling to disk.
float	calculateDataFileSparseness() The design of the layout on the data file means that there will be small gaps created when DiskElements are reused.
boolean	containsKey(Object key) An unsynchronized and very low cost 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(Ehcache cache, String diskStorePath) A factory method to create a DiskStore.
protected void	deleteFilesInAutoGeneratedDirectory() Delete files in the auto generated directory.
void	deregistered(CacheConfiguration config) Indicates that this listener was removed from the given configuration
void	diskCapacityChanged(int oldCapacity, int newCapacity) Indicates a change in the configurations disk store capacity
void	dispose() Shuts down the disk store in preparation for cache shutdown If a VM crash happens, the shutdown hook will not run.
void	expireElements() Removes expired elements.
void	flush() Flush the spool if persistent, so we don't lose any data.
static String	generateUniqueDirectory() Generates a unique directory name for use in automatically creating a diskStorePath where there is a conflict.
Element	get(Object key) Gets an DiskStore.DiskElement from the Disk Store.
String	getDataFileName() Creates a file system safe data file.
String	getDataFilePath()
long	getDataFileSize()
Policy	getEvictionPolicy()
String	getIndexFileName()
long	getIndexFileSize()
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.
Element	getQuiet(Object key) Gets an DiskStore.DiskElement from the Disk Store, without updating statistics
int	getSize() Returns the current store size in number of Elements.
long	getSizeInBytes() Gets the size of the store, in bytes.
Status	getStatus() Returns the store status.
int	getTerracottaClusteredSize() Returns nothing since a disk store isn't clustered
long	getTotalFileSize()
long	getUsedDataSize() When elements are deleted, spaces are left in the file.
boolean	isSpoolThreadAlive() The spool thread is started when the disk store is created.
static DiskStore.DiskElement	leastHit(DiskStore.DiskElement[] sampledElements, DiskStore.DiskElement justAdded) Finds the least hit of the sampled elements provided
void	loggingChanged(boolean oldValue, boolean newValue) Indicates a change in the configuration for enable/disable logging
void	memoryCapacityChanged(int oldCapacity, int newCapacity) Indicates a change in the configurations memory store capacity
boolean	put(Element element) Puts an element into the disk store.
Element	putIfAbsent(Element element) Unsupported in DiskStore
boolean	putWithWriter(Element element, CacheWriterManager writerManager) Puts an item into the store and the cache writer manager in an atomic operation
void	registered(CacheConfiguration config) Indicates that this listener was registered with the given configuration
Element	remove(Object key) Removes an item from the disk store.
void	removeAll() Remove all of the elements from the store.
Element	removeElement(Element element, ElementValueComparator comparator) Unsupported in DiskStore
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) Unsupported in DiskStore
boolean	replace(Element old, Element element, ElementValueComparator comparator) Unsupported in DiskStore
void	setEvictionPolicy(Policy policy) Sets the eviction policy strategy.
void	setInMemoryEvictionPolicy(Policy policy) Sets the eviction policy strategy.
void	timeToIdleChanged(long oldTti, long newTti) Indicates a change in the configurations time to idle
void	timeToLiveChanged(long oldTtl, long newTtl) Indicates a change in the configurations time to live
String	toString() Returns a String representation of the DiskStore

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, wait, wait, wait

Field Detail

AUTO_DISK_PATH_DIRECTORY_PREFIX

public static final String AUTO_DISK_PATH_DIRECTORY_PREFIX

If the CacheManager needs to resolve a conflict with the disk path, it will create a subdirectory in the given disk path with this prefix followed by a number. The presence of this name is used to determined whether it makes sense for a persistent DiskStore to be loaded. Loading persistent DiskStores will only have useful semantics where the diskStore path has not changed.

See Also:

Constant Field Values

Constructor Detail

DiskStore

protected DiskStore(Ehcache cache,
                    String diskPath)

Creates a disk store.

Parameters:

cache - the Cache that the store is part of

diskPath - the directory in which to create data and index files

Method Detail

create

public static DiskStore create(Ehcache cache,
                               String diskStorePath)

A factory method to create a DiskStore.

Parameters:

cache -

diskStorePath -

Returns:

an instance of a DiksStore

get

public final Element get(Object key)

Gets an DiskStore.DiskElement from the Disk Store.

Specified by:

get in interface Store

Returns:

The element

containsKey

public final boolean containsKey(Object key)

An unsynchronized and very low cost check to see if a key is in the Store. No check is made to see if the Element is expired.

Specified by:

containsKey in interface Store

Parameters:

key - The Element key

Returns:

true if found. If this method return false, it means that an Element with the given key is definitely not in the MemoryStore. If it returns true, there is an Element there. An attempt to get it may return null if the Element has expired.

getQuiet

public final Element getQuiet(Object key)

Gets an DiskStore.DiskElement from the Disk Store, without updating statistics

Specified by:

getQuiet in interface Store

Returns:

The element

See Also:

get(Object)

getKeys

public final List getKeys()

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

Specified by:

getKeys in interface Store

Returns:

An Object[] of Serializable keys

getSize

public final int getSize()

Returns the current store size in number of Elements. This method may not measure data in transit from the spool to the disk.

Specified by:

getSize in interface Store

Returns:

the count of the Elements in the Store on the local machine

See Also:

getDataFileSize()

getTerracottaClusteredSize

public final int getTerracottaClusteredSize()

Returns nothing since a disk store isn't clustered

Specified by:

getTerracottaClusteredSize in interface Store

Returns:

returns 0

getSizeInBytes

public long getSizeInBytes()

Gets the size of the store, in bytes.

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

This implementation returns the size of the data file, but does not take into account the memory in the spool.

Returns:

the approximate size of the store in bytes

getStatus

public final Status getStatus()

Returns the store status.

Specified by:

getStatus in interface Store

put

public final boolean put(Element element)

Puts an element into the disk store.

This method is not synchronized. It is however threadsafe. It uses fine-grained synchronization on the spool.

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)
                      throws CacheException

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.

Throws:

CacheException

bufferFull

public boolean bufferFull()

In some circumstances data can be written so quickly to the spool that the VM runs out of memory while waiting for the spooling to disk.

This is a very simple and quick test which estimates the spool size based on the last element's written size.

Specified by:

bufferFull in interface Store

Returns:

true if the spool is not being cleared fast enough

remove

public final Element remove(Object key)

Removes an item from the disk store.

Specified by:

remove in interface Store

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 final 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 final void dispose()

Shuts down the disk store in preparation for cache shutdown

If a VM crash happens, the shutdown hook will not run. The data file and the index file will be out of synchronisation. At initialisation we always delete the index file after we have read the elements, so that it has a zero length. On a dirty restart, it still will have and the data file will automatically be deleted, thus preserving safety.

Specified by:

dispose in interface Store

deleteFilesInAutoGeneratedDirectory

protected void deleteFilesInAutoGeneratedDirectory()

Delete files in the auto generated directory. These are one time only for those who create multiple CacheManagers with the same disk path settings.

flush

public final void flush()

Flush the spool if persistent, so we don't lose any data.

This, as of ehcache-1.6.0, is an asynchronous operation. It will write the next time the spoolAndExpiryThread runs. By default this is every 200ms.

Specified by:

flush in interface Store

expireElements

public void expireElements()

Removes expired elements.

Note that the DiskStore cannot efficiently expire based on TTI. It does it on TTL. However any gets out of the DiskStore are check for both before return.

Specified by:

expireElements in interface Store

toString

public final String toString()

Returns a String representation of the DiskStore

Overrides:

toString in class Object

generateUniqueDirectory

public static String generateUniqueDirectory()

Generates a unique directory name for use in automatically creating a diskStorePath where there is a conflict.

Returns:

a path consisting of AUTO_DISK_PATH_DIRECTORY_PREFIX followed by "_" followed by the current time as a long e.g. ehcache_auto_created_1149389837006

timeToIdleChanged

public void timeToIdleChanged(long oldTti,
                              long newTti)

Indicates a change in the configurations time to idle

Specified by:

timeToIdleChanged in interface CacheConfigurationListener

Parameters:

oldTti - previous time to idle value

newTti - new time to idle value

timeToLiveChanged

public void timeToLiveChanged(long oldTtl,
                              long newTtl)

Indicates a change in the configurations time to live

Specified by:

timeToLiveChanged in interface CacheConfigurationListener

Parameters:

oldTtl - previous time to live value

newTtl - new time to live value

diskCapacityChanged

public void diskCapacityChanged(int oldCapacity,
                                int newCapacity)

Indicates a change in the configurations disk store capacity

Specified by:

diskCapacityChanged in interface CacheConfigurationListener

Parameters:

oldCapacity - previous capacity

newCapacity - new capacity

memoryCapacityChanged

public void memoryCapacityChanged(int oldCapacity,
                                  int newCapacity)

Indicates a change in the configurations memory store capacity

Specified by:

memoryCapacityChanged in interface CacheConfigurationListener

Parameters:

oldCapacity - previous capacity

newCapacity - new capacity

loggingChanged

public void loggingChanged(boolean oldValue,
                           boolean newValue)

Indicates a change in the configuration for enable/disable logging

Specified by:

loggingChanged in interface CacheConfigurationListener

Parameters:

oldValue - old value whether logging was enabled or not

newValue - new value whether logging was enabled or not

registered

public void registered(CacheConfiguration config)

Indicates that this listener was registered with the given configuration

Specified by:

registered in interface CacheConfigurationListener

deregistered

public void deregistered(CacheConfiguration config)

Indicates that this listener was removed from the given configuration

Specified by:

deregistered in interface CacheConfigurationListener

getMBean

public Object getMBean()

Optional implementation specific MBean exposed by the store.

Specified by:

getMBean in interface Store

Returns:

implementation specific management bean

getTotalFileSize

public final long getTotalFileSize()

Returns:

the total size of the data file and the index file, in bytes.

getDataFileSize

public final long getDataFileSize()

Returns:

the size of the data file in bytes.

calculateDataFileSparseness

public final float calculateDataFileSparseness()

The design of the layout on the data file means that there will be small gaps created when DiskElements are reused.

Returns:

the sparseness, measured as the percentage of space in the Data File not used for holding data

getUsedDataSize

public final long getUsedDataSize()

When elements are deleted, spaces are left in the file. These spaces are tracked and are reused when new elements need to be written.

This method indicates the actual size used for data, excluding holes. It can be compared with getDataFileSize() as a measure of fragmentation.

getIndexFileSize

public final long getIndexFileSize()

Returns:

the size of the index file, in bytes.

getDataFileName

public final String getDataFileName()

Creates a file system safe data file. Any incidences of or / are replaced with _ so there are no unwanted side effects.

Returns:

the file name of the data file where the disk store stores data, without any path information.

getDataFilePath

public final String getDataFilePath()

Returns:

the disk path, which will be dependent on the operating system

getIndexFileName

public final String getIndexFileName()

Returns:

the file name of the index file, which maintains a record of elements and their addresses on the data file, without any path information.

isSpoolThreadAlive

public final boolean isSpoolThreadAlive()

The spool thread is started when the disk store is created.

It will continue to run until the dispose() method is called, at which time it should be interrupted and then die.

Returns:

true if the spoolThread is still alive.

leastHit

public static DiskStore.DiskElement leastHit(DiskStore.DiskElement[] sampledElements,
                                             DiskStore.DiskElement justAdded)

Finds the least hit of the sampled elements provided

Parameters:

sampledElements - this should be a random subset of the population

justAdded - we never want to select the element just added. May be null.

Returns:

the least hit

getEvictionPolicy

public Policy getEvictionPolicy()

Returns:

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

See Also:

setEvictionPolicy(Policy)

setEvictionPolicy

public void setEvictionPolicy(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 Object getInternalContext()

This should not be used, and will generally return null

Specified by:

getInternalContext in interface Store

Returns:

some internal context (probably null)

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.

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

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

putIfAbsent

public Element putIfAbsent(Element element)
                    throws NullPointerException

Unsupported in DiskStore

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

Unsupported in DiskStore

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

Unsupported in DiskStore

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

Unsupported in DiskStore

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