Call us: +1-415-738-4000
Ehcache has three storage tiers:
This page presents these cache storage tiers and provides the suitable element types for each storage option.
For information about sizing the tiers, refer to Cache Configuration Sizing Attributes.
MemoryStore is always enabled. It is not directly manipulated, but is a component of every cache.
All Elements are suitable for placement in the MemoryStore. It has the following characteristics:
Backed By JDK LinkedHashMap—The MemoryStore for JDK1.4 and higher is backed by an extended LinkedHashMap. This provides a combined linked list and a hash map, and is ideally suited for caching. Using this standard Java class simplifies the implementation of the memory cache. It directly supports obtaining the least recently used element.
Fast—The MemoryStore, being all in memory, is the fastest caching option.
All caches specify their maximum in-memory size, in terms of the number of elements, at configuration time.
When an element is added to a cache and it goes beyond its maximum memory size, an existing element is either:
Overflow options are discussed here.
If overflow is enabled, a check for expiry is carried out. Expired elements
are deleted; unexpired elements are spooled. The eviction of an item from
the memory store is based on the 'MemoryStoreEvictionPolicy' setting
specified in the configuration file.
memoryStoreEvictionPolicy is an optional attribute in
ehcache.xml, first introduced in Ehcache 1.2. Legal values are LRU (default, consistent with all earlier releases of Ehcache), LFU and FIFO:
For all the eviction policies there are also
getQuiet methods which do not update the last used timestamp.
When there is a
get or a
getQuiet on an element, it is checked for expiry. If expired, it is removed and null is returned.
Note that at any point in time there will usually be some expired elements in the cache. Memory sizing of an application must always take into account the maximum size of each cache.
There is a convenient method
which can provide an estimate of the size in bytes of the
It returns the serialized size of the cache. However, do not use this method in production, as it is very slow. It is only meant to provide a rough estimate.
An alternative would be to have an expiry thread. This is a trade-off between lower memory use and short locking periods and CPU utilization. The design is in favour of the latter. For those concerned with memory use, simply reduce the cache's size in memory (see How to Size Caches for more information).
BigMemory is a pure Java product from Terracotta that permits caches to use an additional type of memory store outside the object heap. This off-heap store, which is not subject to Java GC, allows extremely large caches to be created.
Because off-heap data is stored in bytes, there are two implications:
The MemoryStore still holds the hottest subset of data from the off-heap store, already in deserialized form, to maintain performance. In practice, however, when the GC involved with larger heaps is taken into account, the off-heap store is faster.
The DiskStore provides a disk spooling facility that can be used for additional storage during cache operation and for persisting caches through system restarts.
For more information about cache persistence on disk, refer to the Persistence and Restartability page.
diskStore element in ehcache.xml is optional. If all caches use only MemoryStores,
then there is no need to configure a DiskStore. This simplifies configuration, and uses less threads. It is also good when multiple CacheManagers are being used, and multiple disk store paths would need to be configured.
DiskStores are configured on a per CacheManager basis. If one or more caches requires a DiskStore but none is configured, a default directory will be used and a warning message will be logged to encourage explicit configuration of the DiskStore path.
To turn off disk store path creation, comment out the
diskStore element in ehcache.xml.
The ehcache-failsafe.xml configuration uses a DiskStore. This will remain the case so as to not affect
existing Ehcache deployments. So if you do not wish to use a DiskStore, make
sure you specify your own ehcache.xml and comment out the
Only Elements which are
Serializable can be placed in the DiskStore. Any non-serializable
Elements which attempt to overflow to the DiskStore will be removed instead, and a NotSerializableException will be thrown.
DiskStores are thread safe.
Writes to and from the disk use ObjectInputStream and the Java serialization mechanism.
Serialization speed is affected by the size of the objects being serialized and their type. It has been found in the ElementTest that:
Byte arrays are 20 times faster to serialize. Make use of byte arrays to increase DiskStore performance.
Two DiskStore options are available:
The "localTempSwap" strategy allows the cache to overflow to disk during cache operation, providing an extra tier for cache storage. This disk storage is temporary and is cleared after a restart.
If the disk store path is not specified, a default path is used, and the default will be auto-resolved in the case of a conflict with another CacheManager.
The TempSwap DiskStore creates a data file for each cache on startup called "
The "localRestartable" persistence strategy implements a restartable store that is a mirror of the in-memory cache. After any restart, data that was last in the cache will automatically load into the restartable store, and from there the data will be available to the cache.
The path to the directory where any required disk files will be created is configured with the
<diskStore> sub-element of the Ehcache configuration. In order to use the restartable store, a unique and explicitly specified path is required.
Files are created in the directory specified by the
configuration element. The
<diskStore> element has one attribute called
Legal values for the path attibute are legal file-system paths. For example, for Unix:
The following system properties are also legal, in which case they are translated:
Subdirectories can be specified below the system property, for example:
To programmatically set a DiskStore path:
DiskStoreConfiguration diskStoreConfiguration = new DiskStoreConfiguration(); diskStoreConfiguration.setPath("/my/path/dir"); // Already created a configuration object ... configuration.addDiskStore(diskStoreConfiguration); CacheManager mgr = new CacheManager(configuration);
Note: A CacheManager's DiskStore path cannot be changed once it is set in configuration. If the DiskStore path is changed, the CacheManager must be recycled for the new path to take effect.
Expired elements are eventually evicted to free up disk space. The element is also removed from the in-memory index of elements.
One thread per cache is used to remove expired elements. The optional attribute
sets the interval between runs of the expiry thread.
diskExpiryThreadIntervalSeconds to a low value
is not recommended. It can cause excessive DiskStore locking and high CPU utilization. The default value is 120 seconds.
If a cache's DiskStore has a limited size, Elements will be evicted from the DiskStore when it exceeds this limit. The LFU algorithm is used for these evictions. It is not configurable or changeable.
Note: With the "localTempSwap" strategy, you can use
maxBytesLocalDisk at either the Cache or CacheManager level to control the size of the swap-to-disk area.
These examples show how to allocate 8GB of machine memory to different stores. It assumes a data set of 7GB - say for a cache of 7M items (each 1kb in size).
For minimal application response-time variance (or minimizing GC pause times), the entire cache should fit into the off-heap store provided by BigMemory. Assuming that 1GB of heap is needed for the rest of the app, the Java config is set as follows:
java -Xms1G -Xmx1G -XX:maxDirectMemorySize=7G
Ehcache config is set as follows:
<cache maxEntriesLocalHeap=100 overflowToOffHeap="true" maxBytesLocalOffHeap="6G" ... />
To allow enough headroom for process-related data, a minimum of 256MB should be allotted via maxDirectMemorySize. This example allots an additional 1GB.
For maximum performance, a combination of on-heap and off-heap is recommended. The heap will be used for the hot set, the offheap for the rest. For example, if the hot set is 1M items (or 1GB) of the 7GB data, set Java config as follows:
java -Xms2G -Xmx2G -XX:maxDirectMemorySize=6G
And Ehcache config as follows:
<cache maxEntriesLocalHeap=1M overflowToOffHeap="true" maxBytesLocalOffHeap="5G" ...>
This configuration will compare VERY favorably against the alternative of keeping the less-hot set in a database (100x slower) or caching on local disk (20x slower).
Where the data set is small and pauses are not a problem, the whole data set can be kept on heap:
<cache maxEntriesLocalHeap=1M overflowToOffHeap="false" ...>
Where latency isn't an issue, overflow to disk can be used:
Where Ehcache is being used without off-heap, do not use any of the off-heap sizing attributes. Use heap and disk (
maxEntrtiesLocalDisk) sizing attributes to control overflow and conform to overall capacity.
The MemoryStore is approximately an order of magnitude faster than the DiskStore. The reason is that the DiskStore incurs the following extra overhead:
Note that writing to disk is not a synchronous performance overhead because it is handled by a separate thread.
For performance reasons, Ehcache should always use as much heap memory as possible without triggering GC pauses. Use BigMemory (the off-heap store) to hold the data that cannot fit in heap without causing GC pauses.