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 and, by implication, one XML file, provides the definition for a CacheManager. With Ehcache 3.0, however, you may create multiple CacheManager instances using the same XML configuration file. Unlike the JSR-107 javax.cache.spi.CachingProvider, Ehcache does not maintain a registry of CacheManager instances.

<service> elements

<service> elements are an extension point for specifying CacheManager managed services.

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 it needs.

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

We’ve setup a complete configuration example to inspire you.

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

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 a XML file, e.g. the /my-config.xml contained 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