XML Configuration

Let’s you configure a CacheManager at creation time, using a XML file, according to this schema definition, namely:

<config> root element

The root element of our XML configuration. One <config> element, and as such one XML file, corresponds to a CacheManager. From Ehcache’s perspective though, nothing prohibits from creating multiple CacheManager instances off one XML configuration file. Ehcache does not act as a repository of CacheManager, unlike JSR-107’s javax.cache.spi.CachingProvider.

<service> elements

Currently, no built-in services are provided. But <service> elements are, and will remain, an extension point for CacheManager lifecycled services, i.e. Service instances that will be .start() and .stop() 'ed by the CacheManager during its own lifecycle state transitions.

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.

<cache> elements

<cache> elements each represent a Cache that will be created, and then on 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 usesTemplate attribute, let’s 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. <capacity>: a positive numerical value, defaults to null, i.e. unconstrained

4. <expiry>: lets you control the expiry type and its parameters

5. <eviction-veto>: FQCN of a org.ehcache.config.EvictionVeto<K, V> implementation, defaults to null, i.e. none

6. <integration>: lets you configure a CacheLoaderWriter for a cache-through pattern

<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-template>. A <cache> element that references a <cache-template> by its name using the usesTemplate attribute, will inherit all of the <cache-template> 's properties. Every <cache> can override these properties as it needs.

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

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

XML programmatic parsing

Note	If you are obtaining your CacheManager through the JSR-107 API, what follows below is automatically done for you when invoking javax.cache.spi.CachingProvider.getCacheManager(java.net.URI, java.lang.ClassLoader), so you probably don’t have to worry about any of this…​

final URL myUrl = this.getClass().getResource("/my-config.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 a XmlConfiguration passing the XML file’s URL to it

3. Using the static org.ehcache.CacheManagerBuilder.newCacheManager(org.ehcache.config.Configuration) lets you 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:

<ehcache:cache-template name="example">
  <ehcache:capacity>120</ehcache:capacity>
</ehcache:cache-template>

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

CacheConfigurationBuilder<String, Object> cacheBuilder = xmlConfig.newCacheConfigurationBuilderFromTemplate("example", String.class, Object.class); // (1)
cacheBuilder.capacityConstraint(100L); // (2)

1. Creates a builder, inheriting the capacity constraint of 120 entries, specializing the key type to java.lang.String

2. But you can obviously override the inherited properties, by simply providing a different value prior to building the CacheConfiguration