net.sf.ehcache.store
Class DiskStore

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

All Implemented Interfaces:

Store

public class DiskStore
extends java.lang.Object
implements Store

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.

Version:

$Id: DiskStore.java 704 2008-07-13 00:17:52Z gregluck $

Author:

Adam Murdoch, Greg Luck, patches contributed: Ben Houston

Field Summary

static java.lang.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.

Constructor Summary

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

Method Summary

boolean	backedUp() 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(java.lang.Object key) An unsynchronized and very low cost check to see if a key is in the Store.
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 java.lang.String	generateUniqueDirectory() Generates a unique directory name for use in automatically creating a diskStorePath where there is a conflict.
Element	get(java.lang.Object key) Gets an Element from the Disk Store.
java.lang.String	getDataFileName()
java.lang.String	getDataFilePath()
long	getDataFileSize()
java.lang.String	getIndexFileName()
long	getIndexFileSize()
java.lang.Object[]	getKeyArray() Gets an Array of the keys for all elements in the disk store.
Element	getQuiet(java.lang.Object key) Gets an Element from the Disk Store, without updating statistics
int	getSize() Returns the current store size.
Status	getStatus() Returns the store status.
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.
void	put(Element element) Puts an element into the disk store.
Element	remove(java.lang.Object key) Removes an item from the disk store.
void	removeAll() Remove all of the elements from the store.
java.lang.String	toString() Returns a String representation of the DiskStore

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 java.lang.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

public DiskStore(Ehcache cache,
                 java.lang.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

get

public final Element get(java.lang.Object key)

Gets an Element from the Disk Store.

Specified by:

get in interface Store

Returns:

The element

containsKey

public final boolean containsKey(java.lang.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(java.lang.Object key)

Gets an Element from the Disk Store, without updating statistics

Specified by:

getQuiet in interface Store

Returns:

The element

getKeyArray

public final java.lang.Object[] getKeyArray()

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

Specified by:

getKeyArray in interface Store

Returns:

An Object[] of Serializable keys

getSize

public final int getSize()

Returns the current store size.

Specified by:

getSize in interface Store

getStatus

public final Status getStatus()

Returns the store status.

Specified by:

getStatus in interface Store

put

public final void 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

backedUp

public boolean backedUp()

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:

backedUp in interface Store

Returns:

true if the spool is not being cleared fast enough

remove

public final Element remove(java.lang.Object key)

Removes an item from the disk store.

Specified by:

remove 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

flush

public final void flush()
                 throws java.io.IOException

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

Specified by:

flush in interface Store

Throws:

java.io.IOException

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 java.lang.String toString()

Returns a String representation of the DiskStore

Overrides:

toString in class java.lang.Object

generateUniqueDirectory

public static java.lang.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

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 java.lang.String getDataFileName()

Returns:

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

getDataFilePath

public final java.lang.String getDataFilePath()

Returns:

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

getIndexFileName

public final java.lang.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.