Ehcache(2.9.x)

About Ehcache Configuration

Ehcache supports declarative configuration via an XML configuration file, as well as programmatic configuration via class-constructor APIs. Choosing one approach over the other can be a matter of preference or a requirement, such as when an application requires a certain run-time context to determine appropriate configuration settings.

If your project permits the separation of configuration from run time use, there are advantages to the declarative approach:

• Cache configuration can be changed more easily at deployment time.
• Configuration can be centrally organized for greater visibility.
• Configuration lifecycle can be separated from application-code lifecycle.
• Configuration errors are checked at startup rather than causing an unexpected runtime error.
• If the configuration file is not provided, a default configuration is always loaded at runtime.

This guide focuses on XML declarative configuration. Programmatic configuration is explored in certain examples and is documented in the Javadoc.

XML Configuration

By default, Ehcache looks for an ASCII or UTF8 encoded XML configuration file called ehcache.xml at the top level of the Java classpath. You may specify alternate paths and filenames for the XML configuration file by using the various CacheManager constructors as described in the CacheManager Javadoc.

To avoid resource conflicts, one XML configuration is required for each CacheManager that is created. For example, directory paths and listener ports require unique values. Ehcache will attempt to resolve conflicts, and, if one is found, it will emit a warning reminding the user to use separate configurations for multiple CacheManagers.

A sample ehcache.xml file is included in the Ehcache distribution. It contains full commentary on how to configure each element. This file can also be downloaded from http://ehcache.org/ehcache.xml.

Note: Prior to ehcache-1.6, Ehcache only supported ASCII ehcache.xml configuration files. Starting with ehcache-1.6, UTF8 is supported, so that configuration can use Unicode. Because UTF8 is backwardly compatible with ASCII, no conversion is necessary.

Note: Some elements documented in the ehcache.xml sample file pertain only to the Terracotta BigMemory products and are not valid for the open-source version of Ehcache.

ehcache.xsd

Ehcache configuration files must comply with the Ehcache XML schema, ehcache.xsd, which can be downloaded from http://ehcache.org/ehcache.xsd.

The Ehcache distribution also contains a copy of ehcache.xsd.

Note: Note that some elements documented by the Ehcache XML schema pertain only to the Terracotta BigMemory products and are not valid for the open-source version of Ehcache.

ehcache-failsafe.xml

If the CacheManager default constructor or factory method is called, Ehcache looks for a file called ehcache.xml in the top level of the classpath. Failing that, it looks for ehcache-failsafe.xml in the classpath. The ehcache-failsafe.xml file is packaged in the Ehcache JAR and should always be found.

ehcache-failsafe.xml provides a simple default configuration to enable users to get started before they create their own ehcache.xml.

When ehcache-failsafe.xml is used, Ehcache will emit a warning, reminding the user to set up a proper configuration. The meaning of the elements and attributes are explained in the section on ehcache.xml.

<ehcache> 
  <diskStore path="java.io.tmpdir"/> 
  <defaultCache 
     maxEntriesLocalHeap="10000" 
     eternal="false" 
     timeToIdleSeconds="120" 
     timeToLiveSeconds="120" 
     maxEntriesLocalDisk="10000000" 
     diskExpiryThreadIntervalSeconds="120" 
     memoryStoreEvictionPolicy="LRU"> 
     <persistence strategy="localTempSwap"/> 
  </defaultCache> 
</ehcache>

About Default Cache

The defaultCache configuration is applied to any cache that is not explicitly configured. The defaultCache appears in the ehcache-failsafe.xml file by default, and can also be added to any Ehcache configuration file.

While the defaultCache configuration is not required, an error is generated if caches are created by name (programmatically) with no defaultCache loaded.

Dynamically Changing Cache Configuration

While most of the Ehcache configuration is not changeable after startup, since Ehcache 2.0, certain cache configuration parameters can be modified dynamically at runtime. These include the following:

• Expiration settings
  • timeToLive – The maximum number of seconds an element can exist in the cache regardless of access. The element expires at this limit and will no longer be returned from the cache. The default value is 0, which means no TTL eviction takes place (infinite lifetime).
    
  • timeToIdle – The maximum number of seconds an element can exist in the cache without being accessed. The element expires at this limit and will no longer be returned from the cache. The default value is 0, which means no TTI eviction takes place (infinite lifetime).

  Note that the eternal attribute, when set to “true”, overrides timeToLive and timeToIdle so that no expiration can take place.

• Local sizing attributes
  • maxEntriesLocalHeap
    
  • maxBytesLocalHeap
  • maxEntriesLocalDisk
  • maxBytesLocalDisk
• memory-store eviction policy.
• CacheEventListeners can be added and removed dynamically

This example shows how to dynamically modify the cache configuration of a running cache:

Cache cache = manager.getCache("sampleCache"); 
CacheConfiguration config = cache.getCacheConfiguration(); 
config.setTimeToIdleSeconds(60); 
config.setTimeToLiveSeconds(120); 
config.setmaxEntriesLocalHeap(10000); 
config.setmaxEntriesLocalDisk(1000000);

Dynamic cache configurations can also be disabled to prevent future changes:

Cache cache = manager.getCache("sampleCache"); 
cache.disableDynamicFeatures();

In ehcache.xml, you can disable dynamic configuration by setting the <ehcache> element's dynamicConfig attribute to “false”.

Passing Copies Instead of References

By default, a get() operation on a store returns a reference to the requested data, and any changes to that data are immediately reflected in the memory store. In cases where an application requires a copy of data rather than a reference to it, you can configure the store to return a copy. This allows you to change a copy of the data without affecting the original data in the memory store.

This is configured using the copyOnRead and copyOnWrite attributes of the <cache> and <defaultCache> elements in your configuration, or programmatically as follows:

CacheConfiguration config = new CacheConfiguration("copyCache", 1000) 
                                   .copyOnRead(true).copyOnWrite(true); 
Cache copyCache = new Cache(config);

The default configuration is “false” for both options.

To copy elements on put()-like and/or get()-like operations, a copy strategy is used. The default implementation uses serialization to copy elements. You can provide your own implementation of net.sf.ehcache.store.compound.CopyStrategy using the <copyStrategy> element:

<cache name="copyCache" 
    maxEntriesLocalHeap="10" 
    eternal="false" 
    timeToIdleSeconds="5" 
    timeToLiveSeconds="10" 
    copyOnRead="true" 
    copyOnWrite="true"> 
  <copyStrategy class="com.company.ehcache.MyCopyStrategy"/> 
</cache>

A single instance of your CopyStrategy is used per cache. Therefore, in your implementation of CopyStrategy.copy(T), T must be thread-safe.

A copy strategy can be added programmatically in the following way:

CacheConfiguration cacheConfiguration = new CacheConfiguration("copyCache", 10); 
CopyStrategyConfiguration copyStrategyConfiguration = new CopyStrategyConfiguration(); 
copyStrategyConfiguration.setClass("com.company.ehcache.MyCopyStrategy"); 
cacheConfiguration.addCopyStrategy(copyStrategyConfiguration);