Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Configuring Ehcache

Configuring Ehcache

Ehcache is an open source caching system that handles application caching.

Advantages

Using Ehcache gives Elastic Path the following benefits:

  • JMX Support
  • Unified run-time configuration for application and OpenJPA L2 caches
  • Improved cache visibility and control

Default Configuration

Default Configuration File

Elastic Path provides a default Ehcache configuration file in the extensions/database module's /ext-data/environments/ directory.

It is recommended that you copy this default configuration file to your local file system using the following instructions:

  1. In the command line, navigate to the extensions/database module.
  2. In the extensions/database module, run the following command: 
    mvn clean install -Preset-conf

This command wipes your current local home directory's configuration files (if they exist), copies out of the box Cortex and Ehcache configuration files from the database/ext-data/environments/local/ directory to your file system's ${user.home}/ep/conf/ directory.

Application Caches

The application level caches sit above the data access layer and are used by Elastic Path to cache longer lived application data. Their default configuration is defined either through Spring or the Elastic Path settings framework. See Application Data Caching a for a list of caches.

OpenJPA Caches

Ehcache integrates with OpenJPA to provide caches for performance enhancement.

Default Cache

The default Ehcache OpenJPA cache configuration is defined in ehcache.xml in the commerce-engine/core/openjpa-osgi-wrapper module. 
<defaultCache
                        maxEntriesLocalHeap="10000"
                        eternal="false"
                        timeToIdleSeconds="1"
                        timeToLiveSeconds="1"
                        overflowToDisk="false"
                        maxElementsOnDisk="10000000"
                        diskPersistent="false"
                        diskExpiryThreadIntervalSeconds="120"
                        memoryStoreEvictionPolicy="LRU"
                        statistics="true"
                        />

L2 Data Cache

A L2 data cache is created for each domain entity with a cache name of the fully qualified class name (e.g. com.elasticpath.domain.catalog.impl.ProductImpl). You can configure the Ehcache DB entities by creating a new cache element in ehcache.xml and specifying its properties. If no explicit configuration is provided for a domain entity, then the defaultCache attribute is used.

Query Cache

The query cache saves OpenJPA query resultes. It is disabled by default to prevent stale query results during transaction processing, but enabled in the Search server to improve indexing performance.

The JPA query cache is configured by the following element: 
<cache name="openjpa-querycache"
                     maxEntriesLocalHeap="10000"
                     eternal="false"
                     timeToIdleSeconds="5"
                     timeToLiveSeconds="5"
                     overflowToDisk="false"
                     statistics="true"
                     />

Runtime Configuration

Ehcache configuration can be overridden at run time by providing an external Ehcache configuration file. The location of the configuration file is specified using the ep.external.ehcache.xml.path property in the ep.properties file.

The file path in ep.external.ehcache.xml.path must be absolute. There are three supported formats as shown in the following examples:
  • ${user.home}/ep/conf/cache/ehcache.xml (Linux and Windows)
  • /ep/conf/cache/ehcache.xml (Linux) or c:/ep/conf/cache/ehcache.xml (Windows)
  • file:///ep/conf/cache/ehcache.xml (Linux) or file:///c:/ep/conf/cache/ehcache.xml (Windows)
Note: Additional Slash

The additional slash in file:/// is required by Spring.

An application restart is required for configuration changes to take effect.

Configuration Example

Here is a sample configuration override file:

Note:

For information on Ehcache's configurable properties, see Ehcache's Cache Configuration guide.

<?xml version='1.0' encoding='UTF-8'?>
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ehcache.xsd"
		 name="ep-default-cache"
		 updateCheck="false">

	<!--
	   Read the Ehcache documentation for help on configuring this file.
	   The <defaultCache> configuration is used as the default for programmatically created caches.
	   <cache> entries will not inherit configuration from <defaultCache>.
	-->
	<defaultCache
			timeToIdleSeconds="1"
			timeToLiveSeconds="1"
			maxEntriesLocalHeap="10000"
			eternal="false"
			overflowToDisk="false"
			diskPersistent="false"
			diskExpiryThreadIntervalSeconds="120"
			memoryStoreEvictionPolicy="LRU"
			statistics="true"
	/>

	<cache name="openjpa-querycache"
		   timeToIdleSeconds="5"
		   timeToLiveSeconds="5"
		   maxEntriesLocalHeap="10000"
		   eternal="false"
		   overflowToDisk="false"
		   statistics="true"
	/>

	<!--
	   Override application cache configuration.
	-->
	<cache name="baseAmountCache"
		   timeToIdleSeconds="3600"
		   timeToLiveSeconds="3600"
		   maxEntriesLocalHeap="10000"
		   maxElementsOnDisk="10000"
		   statistics="true"
	/>

</ehcache>

An example of overriding all caches can be found in the ehcache-5-seconds.xml file in the extensions/database/ext-data/src/main/resources/environments/dev/files/conf/cache/ directory.

Recommended Practices

Every commerce implementation is unique. No one configuration fits all. You will need to discover the configurations that work for your implementation. Keep in mind:
  • Configure lower cache timeouts in development, QA and authoring environments where users want to see changes quickly and performance isn't a primary consideration.
  • Configure much higher timeouts for production and performance test live environments.
  • Stress your application while using JMX console to monitor the number of cache requests. This will help you determine if the DB entities needs to be cached and for how long.
  • Be cautious about increasing L2 cache timeouts. Complex domain object graphs, such a products or categories, can get out of sync when L2 objects are refreshed independently of each other.
  • Keep conducting performance tests until the optimal results are achieved.
  • Ehcache documentation contains comprehensive information about sizing caches.