Introduction

Using an XML file you can configure a CacheManager at creation time, according to this schema definition.

<config> root element

The root element of our XML configuration. One <config> element in an XML file provides the definition for a CacheManager.

Ehcache allows for creating multiple CacheManager instances using the same XML configuration file. In contrast to the JSR-107 javax.cache.spi.CachingProvider, Ehcache does not maintain a registry of CacheManager instances.

<service> elements

<service> elements are extension points for specifying services managed by the CacheManager.

Each Service defined in this way is managed with the same lifecycle as the CacheManager — for each Service defined for a CacheManager, the Service.start is called during CacheManager.init processing and the Service.stop method is called during CacheManager.close processing.

These Service instances can then be used by Cache instances managed by the CacheManager.

JSR-107 uses this extension point of the XML configuration (and Ehcache 3’s modular architecture), as explained in the JSR-107 configuration section.

<default-serializers> element

A <default-serializers> element represents Serializers configured at CacheManager level. It is a collection of <serializer> elements that require a type and a fully qualified class name of the Serializer.

<default-copiers> element

A <default-copiers> element represents Copiers configured at CacheManager level. It is a collection of <copier> elements that requires a type and a fully qualified class name of the Copier.

<persistence> element

A <persistence> element represents Persistence, to be used when creating a PersistentCacheManager. It requires the directory location where data needs be stored on disk.

<cache> elements

A <cache> element represent a Cache instance that will be created and managed by the CacheManager. Each <cache> requires the alias attribute, used at runtime to retrieve the corresponding Cache<K, V> instance using the org.ehcache.CacheManager.getCache(String, Class<K>, Class<V>) method. The optional uses-template attribute lets you reference a <cache-template> element’s name attribute. See the cache-template section for further details on using them.

Supported nested elements are optional:

  1. <key-type>: the fully qualified class name (FQCN) of the keys (<K>) held in the Cache<K, V>; defaults to java.lang.Object

  2. <value-type>: FQCN of the values (<V>) held in the Cache; defaults to java.lang.Object

  3. <expiry>: control the expiry type and its parameters

  4. <eviction-advisor>: FQCN of a org.ehcache.config.EvictionAdvisor<K, V> implementation, defaults to null, i.e. none

  5. <integration>: configure a CacheLoaderWriter for a cache-through pattern

  6. <resources>: configure the tiers and their capacity. When using on-heap only, you can replace this element by the <heap> one.

<cache-template> elements

<cache-template> elements represent a uniquely named (specified using the mandatory name attribute) template for <cache> elements to inherit from. A <cache> element that references a <cache-template> by its name using the uses-template attribute, will inherit all properties of the <cache-template>. A <cache> can override these properties as required.

A <cache-template> element may contain all the same child elements as a <cache> element.

We’ve set up a complete configuration example to inspire you.

Property replacement in XML configuration files

Java system properties can be referenced inside XML configuration files. The property value will replace the property reference during the configuration parsing.

This is done by using the ${prop.name} syntax. It is supported in all attributes and elements values that accept the ${} characters as legal characters. This currently rules out all numbers, mostly used in sizing things, and identifiers, such as cache and template names.

If the system property does not exist, this will make the configuration parsing fail.

A classical use case for this feature is for disk files location inside the directory attribute of the persistence tag:

<persistence directory="${user.home}/cache-data"/> (1)
1 Here user.home will be replaced by the value of the system property, something like /home/user

XML programmatic parsing

If you are obtaining your CacheManager through the JSR-107 API, what follows is done automatically when invoking javax.cache.spi.CachingProvider.getCacheManager(java.net.URI, java.lang.ClassLoader). 
final URL myUrl = getClass().getResource("/configs/docs/getting-started.xml"); (1)
XmlConfiguration xmlConfig = new XmlConfiguration(myUrl); (2)
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); (3)
myCacheManager.init();  (4)
1 Obtain a URL to your XML file’s location
2 Instantiate an XmlConfiguration passing the XML file’s URL to it
3 Using the static org.ehcache.config.builders.CacheManagerBuilder.newCacheManager(org.ehcache.config.Configuration) allows you to create your CacheManager instance using the Configuration from the XmlConfiguration.
4 Initialize the cacheManager before it is used.

We can also use <cache-template> declared in the XML file to seed instances of CacheConfigurationBuilder. In order to use a <cache-template> element from an XML file, e.g. the /my-config.xml contains this XML fragment:

<cache-template name="example">
  <key-type>java.lang.Long</key-type>
  <value-type>java.lang.String</value-type>
  <heap unit="entries">200</heap>
</cache-template>

Creating a CacheConfigurationBuilder of that example <cache-template> element, would be done as follows:

XmlConfiguration xmlConfiguration = new XmlConfiguration(getClass().getResource("/configs/docs/template-sample.xml"));
CacheConfigurationBuilder<Long, String> configurationBuilder = xmlConfiguration.newCacheConfigurationBuilderFromTemplate("example", Long.class, String.class); (1)
configurationBuilder = configurationBuilder.withResourcePools(ResourcePoolsBuilder.heap(1000)); (2)
1 Creates a builder, inheriting the capacity constraint of 200 entries
2 The inherent properties can be overridden by simply providing a different value prior to building the CacheConfiguration