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

Application Caches

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

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 element 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. For example:
  • Windows: file:///C:/path1/path2/path3/test-ehcache-configuration.xml
  • Linux/Mac: file:///path1/path2/path3/production-ehcache-configuration.xml
Note: Additional Slash (/)

The additional slash in file:/// is necessary for Spring.

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

Configuration Sample

Here is a sample configuration file:

Note:

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

<?xml version='1.0' encoding='UTF-8'?>f
<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 all caches, including OpenJPA L2 caches.
   -->

   <!--
      Modified default configuration.
   -->
   <defaultCache
         maxEntriesLocalHeap="10000"
         eternal="false"
         timeToIdleSeconds="150"
         timeToLiveSeconds="300"
         overflowToDisk="false"
         maxElementsOnDisk="10000000"
         diskPersistent="false"
         diskExpiryThreadIntervalSeconds="120"
         memoryStoreEvictionPolicy="LRU"
         statistics="true"
         />

   <!--
      Override ProductImpl JPA L2 cache configuration. 
   -->
    <cache name="com.elasticpath.domain.catalog.impl.ProductImpl"
          maxElementsInMemory="2000"
          timeToIdleSeconds="250"
          timeToLiveSeconds="500"
   </cache>

   <!--
      Override product application cache configuration. 
   -->
    <cache name="productLookupCache"
          maxElementsInMemory="20000"
          timeToIdleSeconds="3600"
          timeToLiveSeconds="7200"
   </cache>

</ehcache>

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:
  • Don't modify the default configuration which is suitable for development and QA. Instead, configure caching for live and performance test environments with an external configuration file.
  • 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.