Understanding Velocity Caching Options

$rx.cache Velocity Methods

The $rx.cache Velocity tool provides the Velocity Template developer with the ability to define and manage cache’s for objects or datasets while working within their templates.  

$rx.cache.flush([key], cache)

Remove all entries from the named cache. If key is specified will remove the specified key from the cache.

$rx.cache.get(key, cache)

Retrieves an object from the named cache. If the object is not found, a null or empty object will be returned.

$rx.cache.put(key, object, cache)

Places an object into the named cache, linked to the named key.  Replaces the current value for the key if it already exists in the cache with the object value.

$rx.cache.setTimeToIdle(key,cache,timeInSeconds)

The maximum amount of time between accesses / cache hits before an element expires from cache.

$rx.cache.setTimeToLive(key,cache,timeInSeconds)

System Velocity Caches

The system defines two context based caches that may be used by template developers:

• Preview Velocity Cache - sys_VelocityPreviewCache

• Publish Velocity Cache - sys_VelocityPublishCache

When caching data within templates, it is important understand the Publishing Context / Channel that the template is being rendered for and to use a matching Cache for that context.  This is to prevent scenarios where changes to an item in cache when a template is in a Preview context for example from affecting a running publishing edition. It is recommened to create custom caches for each publishing context and to put and get items from a cache that matches the context.  If the publishing context is 0 for example, you would use the Preview cache.

User Defined Velocity Caches

Template developers can define their own caches by defining the cache in the rx_resources/cache/ehcache.xml file on the server.   A reference on configuring ehcach can be found here: http://www.ehcache.org/documentation/2.8/configuration/configuration.html

For example, the following xml snippet configures a new Cache named CustomCache that can hold up to 2000 objects in memory.

<cache name="CustomCache"
 maxElementsInMemory="2000"
 eternal="true"
 overflowToDisk="false"
 />

Overriding System Caches

 System caches are defined in the <InstallDir>/sys_resources/cache folder.  This file will be overwritten on upgrade.  In order to tune or optimize a system cache with custom setttings for your environment.  System caches may be overriden by adding the system cache to the <installDir>/rx_resources/cache/ehcache.xml file. 

The configuration in /rx_resources/cache/ehcache.xml will override the configuration in sys_resources/cache/ehcache.xml for any caches that have the same name.  

For example, to tune the AssemblyTemplate cache to be optimized for a system that has more than 700 templates, copy the cache definition from sys_resources/cache/ehcache.xml into the rx_resources/cache/ehcache.xml file and up the maxElementsInMemory to 1000.

 <cache name="PSAssemblyTemplate"
 maxElementsInMemory="1000"
 eternal="true"
 overflowToDisk="false"
 />

NOTE: In older versions of Rhythmyx the cache configuration was defined in the WEB-INF/classes folder of the main application.  That file is no longer used after patching to 732_20180314 patch level.