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.


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


Sets the time to live for an element before it expires . i . e .   The maximum time between creation time and when an element expires .

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:

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

<cache name="CustomCache"

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"

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.