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 at http://www.ehcache.org/apidocs/2.10.1/.

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

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.

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.