Enable and Configure HST Enterprise Caching

Info: HST Enterprise Caching requires a standard or premium Bloomreach Content license. Contact Bloomreach for details.

The Second Level Page Cache and Cluster-Wide Caching features (both using Redis) were deprecated in version 14 and removed in version 15.0. The Stale Page Caching feature was also removed, but reintroduced in versions 15.7 and 16.1.

Overview

This page explains how to enable and configure enterprise caching features in the Bloomreach Content delivery tier.

Enterprise Caching extends the community edition's page caching with additional performance and scalability options. It enables cache sharing across delivery tier cluster nodes and supports domain-specific cache optimization.

For details on how Enterprise Caching works and its benefits compared to community caching, see Understand HST Enterprise Caching.

For information about logging and monitoring with JMX, see Monitor HST Enterprise Caching.

HST Enterprise Caching Features

Enterprise Caching provides three cache types for the delivery tier:

  1. Stale Page Caching (available in versions 14.x, 15.7, 16.1 and later)
  2. Second Level Page Caching (available in 14.x; deprecated)
  3. Generic Cluster-Wide Caching (available in 14.x; deprecated)

Each cache operates independently.

Requirements

  • Stale Page Cache: Only the enterprise caching add-on is required. No additional infrastructure is needed.
  • Second Level Cache and Cluster-Wide Generic Cache: A Redis instance is required. For high availability, only Redis Clustering is supported. Redis Sentinel is not supported. The Redis cluster must be compatible with the jedis 2.9.0 client.

If your project runs in Bloomreach Cloud, you cannot use Second Level Cache or Cluster-Wide Generic Cache because Redis is reserved for internal use. For more information, see Restrictions and Limitations.

Add HST Enterprise Caching (14.x, 15.7, 16.1)

To include enterprise caching in your implementation project, add the following dependency to site/pom.xml:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-caching-hst</artifactId>
</dependency>

This dependency includes all required JAR files. Adding the dependency does not activate any caches. You must enable each cache type as described below.

Enable Stale Page Caching (14.x, 15.7, 16.1)

To enable Stale Page Caching, add the following JNDI variable to your HST web application's context.xml file, typically located at:

/site/webapp/src/main/webapp/META-INF/context.xml

<Environment name="stalePageCache" type="java.lang.String" value=""/>

This enables Stale Page Caching with default settings. To customize the configuration, specify attributes as shown below:

<Environment name="stalePageCache" type="java.lang.String"
                 value="{'maxEntriesLocalHeap' : 10000,
                 'maxEntriesLocalDisk' : 0,
                 'eternal' : false,
                 'timeToLiveSeconds' : 86400,
                 'timeToIdleSeconds' : 86400,
                 'diskExpiryThreadIntervalSeconds' : 120,
                 'stats' : true}" />

These values match the defaults.

Info: When Stale Page Caching is enabled, users may see stale content after a change until the page is regenerated by a new request.

Enable Second Level Page Caching (14.x only, deprecated)

To enable Second Level Page Caching, add the following JNDI variable to your HST web application's context.xml file:

site/webapp/src/main/webapp/META-INF/context.xml

<Environment name="secondLevelPageCache" type="java.lang.String" value=""/>

This enables Second Level Page Caching with default settings. To adjust the configuration, specify attributes as follows:

<Environment name="secondLevelPageCache" type="java.lang.String"
                 value="{
                  'ttlSeconds':300,
                  'profiling' : true,
                  'stats' : true,
                  'quiet' : true,
                  'async' : true}" />

These values are the defaults. Attribute descriptions:

  • profiling: When true, exposes profiling data over JMX for cache operations.
  • stats: When true, exposes cache statistics (hits, misses, puts, ratios) over JMX.
  • quiet: When true, suppresses exceptions from org.springframework.cache.Cache methods (such as timeouts). If quiet is false and async is true (default), exceptions are not thrown for puts, as these are asynchronous. Exceptions may be thrown for gets. If both quiet and async are false, runtime exceptions from the backing cache are propagated for both puts and gets.
  • async: When true, all void methods (notably put) on org.springframework.cache.Cache are executed asynchronously. This prevents request processing from blocking during cache storage.

Info: With Second Level Page Caching, changes may take up to ttlSeconds to appear on the live site. The Experience Manager preview always reflects changes immediately.

Enable Cluster-Wide Generic Cache (14.x only, deprecated)

To enable Cluster-Wide Generic Caching, add the following JNDI variable to your HST web application's context.xml file:

site/webapp/src/main/webapp/META-INF/context.xml

<Environment name="clusterCache" type="java.lang.String" value=""/>

This enables Cluster-Wide Generic Caching with default settings. To customize, specify attributes as shown:

<Environment name="clusterCache" type="java.lang.String"
                 value="{
                  'ttlSeconds':300,
                  'profiling' : true,
                  'stats' : true,
                  'quiet' : true,
                  'async' : true}" />

These attributes have the same meaning as for secondLevelPageCache.

Use Cluster-Wide Generic Cache (14.x only, deprecated)

After configuring clusterCache, you can access and use it in HST code as follows:

HippoRedisCacheManager cacheManager = HstServices
                .getComponentManager()
                .getComponent(HippoRedisCacheManager.class.getName(), 
                              "com.onehippo.cms.spring.cache");
                  
Cache cache = cacheManager.getCache("clusterCache");

Visitor visitor = cache.get(visit_id, Visitor.class);
if (visitor == null) {
   visitor = expensiveGet(visit_id);
   cache.put(visit_id, visitor);
}

The Visitor object must be serializable. If you configure the cache with

'quiet' : true

(the default), exceptions are suppressed and only warning logs are generated. If 'quiet' : false and 'async' : true (default), exceptions are not thrown for puts (as they are asynchronous), but may be thrown for gets. If both 'async' : false and 'quiet' : false, runtime exceptions from the backing cache are thrown for both puts and gets.

Configure Redis Connection Settings (14.x only, deprecated)

By default, the connection factory uses the following settings:

hostname = localhost  
port = 6379
connectionTimeoutMs = 1000
timeoutMs = 10

To override these defaults, add a JNDI environment variable with your desired settings in the global conf/context.xml file. For example:

<Environment name="redis/hippoJedisConnectionFactory" type="java.lang.String"
                 value="{'hostname':'localhost',
                 'port':6379,
                 'connectionTimeoutMs' : 1000,
                 'timeoutMs' : 10}" />

Do not set timeoutMs much higher than 10 ms, as higher values can increase cache lookup latency. For optimal performance, run Redis nodes on the same servers as your application containers.

Place the <Environment /> variable for Redis connection in the global conf/context.xml. Place cache-specific configuration (Second Level Page Cache, Stale Page Cache, Cluster-Wide Cache) in the site web application's context.xml.

Redis Cache Key Prefixing (14.x only, deprecated)

To avoid cache key collisions when multiple applications use the same Redis instance, configure cache key prefixing in the global conf/context.xml:

<Environment name="env" type="java.lang.String" value="foo" />
<Environment name="stack" type="java.lang.String" value="bar"/>

With these settings, Redis cache keys are prefixed with <env>-<stack>:hippo: (for example, foo-bar:hippo:). This is useful when sharing Redis instances across environments (such as test, acceptance, production) or between different stacks (such as customers).

Share Feedback
Page: /build/request-handling/enable-and-configure-hst-enterprise-caching
Section: Build
Category *