HST Binary Content Resource Serving (BinariesServlet)

1. Overview

The BinariesServlet serves binary resources, such as images and files, from the Java Content Repository (JCR). Binary resources are stored in repository nodes. The servlet provides options to control HTTP headers and cache behavior.

By default, when a request URI matches /site/binaries/content/gallery/images/screenshot_cms_small.jpg (where /site is the context path, /binaries is the servlet path, and the remainder is the path info), the BinariesServlet retrieves the binary content from the node at /content/gallery/images/screenshot_cms_small.jpg in the repository and streams it to the client.

  • In preview mode, binaries are fetched using the preview site user. In CMS preview, a security delegate is used between the site preview user and the logged-in CMS user.
  • On the live website, binaries are fetched by the live site user. If subject-based rendering is enabled, the authenticated user is used.
  • The user ID is included in the cache key for internal binary caching.

2. Configuration

Configure the BinariesServlet in your web.xml as shown below:

<servlet>
  <servlet-name>BinariesServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.servlet.BinariesServlet</servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>BinariesServlet</servlet-name>
  <url-pattern>/binaries/*</url-pattern>
</servlet-mapping>

The BinariesServlet supports the following initialization parameters:

Init parameter nameExample valueDefault valueDescription
baseBinariesContentPath/binarycontentsPrepends this value to the node path when locating binary content.
binaryDataPropNamejcr:dataName of the JCR property containing the binary data.
binaryMimeTypePropNamejcr:mimeTypeName of the JCR property containing the MIME type.
binaryLastModifiedPropNamejcr:lastModifiedName of the JCR property containing the last modified date.
binaryResourceNodeTypehippo:resourcePrimary node type for the binary content node.
contentDispositionContentTypesapplication/pdf, application/rtf, application/excel or application/*Specifies which MIME types should trigger a Content-Disposition header. Use * for wildcards.
contentDispositionFilenamePropertydemosite:filenameName of the JCR property containing the filename for the binary node. If set, the filename is included in the Content-Disposition header.
contentDispositionFilenameEncodinguser-agent-specificuser-agent-agnosticDetermines encoding strategy for the filename in the Content-Disposition header. user-agent-specific encodes based on the user agent; user-agent-agnostic uses US-ASCII only.
cache-namedefaultBinariesCacheName of the internal cache bean. The default is defined in SpringComponentManager-cache.xml in the hst-core library.
cache-max-object-size-bytes262144Maximum size (in bytes) for a binary object to be cached. Larger binaries are not cached. Default is 262144 bytes (256 KB).
validity-check-interval-seconds180Interval (in seconds) for validating cached items against the last modified property. Default is 180 seconds.
set-expires-headerstrueIf true, sets the Expires and Cache-Control HTTP headers.
expires-headers-max-age
since 15.7.3 and 16.4.0		36002592000 (30 days)Value (in seconds) for the max-age directive in the Cache-Control header and for calculating the Expires header.
set-content-length-headertrueIf true, sets the Content-Length HTTP header.

3. Cache Component Configuration (brXM 16)

In brXM 16, the default cache bean defaultBinariesCache is defined as follows:

<bean id="caffeineCacheManager"     class="org.springframework.cache.caffeine.CaffeineCacheManager"/>

<bean id="caffeineCacheInstanceFactory" class="org.hippoecm.hst.cache.caffeine.CaffeineCacheInstanceFactory">
  <constructor-arg ref="caffeineCacheManager" />
</bean>

<bean id="defaultBinariesCache" class="org.hippoecm.hst.cache.CompositeHstCache">
 <constructor-arg>
   <bean class="com.github.benmanes.caffeine.cache.Cache" factory-bean="caffeineCacheInstanceFactory" factory-method="createInstance">
      <constructor-arg value="binariesCache" />
      <constructor-arg value="initialCapacity=10,maximumSize=256,expireAfterWrite=24h,expireAfterAccess=24h" />
    </bean>
  </constructor-arg>
  <property name="cacheStats" ref="org.hippoecm.hst.cache.jmx.BinariesCacheStats"/>
</bean>

Customizing the Cache Configuration (brXM 16)

You can override the default cache bean by adding a bean definition XML file to classpath:/META-INF/hst-assembly/overrides/.

Define a Custom Cache Bean

Create a file named binaries-cache.xml (the name is arbitrary) in your project at site/components/src/main/resources/META-INF/hst-assembly/overrides.

Example content:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

  <import resource=
"classpath:/org/hippoecm/hst/site/container/SpringComponentManager-cache.xml"/>

  <bean id="customBinariesCache" class="org.hippoecm.hst.cache.CompositeHstCache">
   <constructor-arg>
     <bean class="com.github.benmanes.caffeine.cache.Cache" factory-bean="caffeineCacheInstanceFactory" factory-method="createInstance">
       <constructor-arg value="binariesCache" />
       <constructor-arg value="initialCapacity=10,maximumSize=1000,expireAfterWrite=24h,expireAfterAccess=24h" />
     </bean>
   </constructor-arg>
   <property name="cacheStats" ref="org.hippoecm.hst.cache.jmx.BinariesCacheStats"/>
  </bean>
</beans>

To use the custom cache, configure the servlet as follows:

<servlet>
  <servlet-name>BinariesServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.servlet.BinariesServlet</servlet-class>
  <init-param>
    <param-name>cache-name</param-name>
    <param-value>customBinariesCache</param-value>
  </init-param>
</servlet>

4. Cache Component Configuration (brXM 14 & 15)

In brXM 14 and 15, the default defaultBinariesCache bean is defined as follows:

  <!-- By default, this component will try to read ehcache.xml from the 
       classpath. -->
  <bean id="ehCacheManager"
       class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean">
  </bean>

  <!-- abstract base cache component bean definition with default property
       configuration -->
  <bean id="abstractEhCacheBase" abstract="true">
    <property name="cacheManager" ref="ehCacheManager" />
    <property name="maxEntriesLocalHeap" value="256" />
    <property name="maxElementsOnDisk" value="0" />
    <property name="eternal" value="false" />
    <property name="overflowToDisk" value="false" />
    <!-- time to live in seconds. default 1 day -->
    <property name="timeToLive" value="86400" />
    <!-- time to idle in seconds. default 1 day -->
    <property name="timeToIdle" value="86400" />
    <property name="diskPersistent" value="false" />
    <property name="diskExpiryThreadIntervalSeconds" value="120" />
  </bean>

  <!-- abstract non-blocking cache component bean definition -->
  <bean id="abstractEhCache" abstract="true" parent="abstractEhCacheBase"
        class="org.springframework.cache.ehcache.EhCacheFactoryBean">
  </bean>

  <!-- abstract blocking cache component bean definition -->
  <bean id="abstractBlockingEhCache" abstract="true"
        parent="abstractEhCacheBase"
        class="org.hippoecm.hst.site.container.BlockingEhCacheFactoryBean">
  </bean>

  <!-- the default cache component bean definition for BinariesServlet -->
  <bean id="defaultBinariesCache"
        class="org.hippoecm.hst.cache.CompositeHstCache">
    <constructor-arg>
      <bean parent="abstractBlockingEhCache">
        <property name="cacheName" value="binariesCache" />
        <!-- time to idle in seconds. default 1 day -->
        <property name="timeToLive" value="86400" />
        <!-- To avoid concurrency issues, use blocking cache -->
        <property name="blocking" value="true" />
      </bean>
    </constructor-arg>
  </bean>

Customizing the Cache Configuration (brXM 14 & 15)

You can override the default cache bean by adding a bean definition XML file to classpath:/META-INF/hst-assembly/overrides/.

There are two primary approaches for custom cache configuration:

Option 1: Define a Custom Cache Bean in Spring

Create a file named binaries-cache.xml (the name is arbitrary) in your project at site/components/src/main/resources/META-INF/hst-assembly/overrides.

Example content:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

  <import resource=
"classpath:/org/hippoecm/hst/site/container/SpringComponentManager-cache.xml"/>

  <bean id="customBinariesCache"
        class="org.hippoecm.hst.cache.CompositeHstCache">
    <constructor-arg>
      <bean parent="abstractBlockingEhCache">
        <property name="cacheName" value="customBinariesCache" />
        <property name="maxEntriesLocalHeap" value="1024"/>
        <property name="overflowToDisk" value="true"/>
        <!-- time to idle in seconds. default 1 day -->
        <property name="timeToLive" value="86400" />
        <property name="blocking" value="true" />
      </bean>
    </constructor-arg>
    <property name="statisticsEnabled"
              value="${default.binaries.cache.statistics.enabled}"/>
  </bean>
</beans>

To use the custom cache, configure the servlet as follows:

<servlet>
  <servlet-name>BinariesServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.servlet.BinariesServlet</servlet-class>
  <init-param>
    <param-name>cache-name</param-name>
    <param-value>customBinariesCache</param-value>
  </init-param>
</servlet>

Option 2: Externalize the Cache Configuration

By default, the cache configuration is packaged in the deployed WAR file. To externalize the cache configuration and allow changes without redeploying, update the configLocation property of the ehCacheManager bean.

You can redefine the ehCacheManager bean in your override file (e.g., binaries-cache.xml):

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

  <import resource=
          "classpath:/org/hippoecm/hst/site/container/SpringComponentManager-cache.xml" />

  <bean id="ehCacheManager"
        class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean">
    <property name="configLocation"
              value="file:${catalina.base}/conf/ehcache.xml"/>
  </bean>
</beans>

In this example, the ehcache.xml file is stored in the conf directory of the application container.

A sample ehcache.xml file reflecting the default binariesCache configuration:

<ehcache updateCheck="false">
  <diskStore path="java.io.tmpdir"/>

  <defaultCache
    maxElementsInMemory="10000"
    eternal="false"
    timeToIdleSeconds="120"
    timeToLiveSeconds="120"
    overflowToDisk="true"
    maxElementsOnDisk="10000000"
    diskPersistent="false"
    diskExpiryThreadIntervalSeconds="120"
    memoryStoreEvictionPolicy="LRU"
    />

  <!-- default settings copied from abstractEhCacheBase -->
  <!-- time to live in seconds. default 1 day -->
  <cache name="binariesCache"
    maxElementsInMemory="256"
    maxElementsOnDisk="0"
    eternal="false"
    overflowToDisk="false"
    timeToIdleSeconds="86400"
    timeToLiveSeconds="86400"
    diskPersistent="false"
    diskExpiryThreadIntervalSeconds="120">
  </cache>
</ehcache>

Info: If a named cache instance is defined in ehcache.xml, the properties set by Spring are ignored. The cache instance is retrieved from the external CacheManager.

Share Feedback
Page: /build/images-assets/hst-2-binary-content-resource-serving-binariesservlet
Section: Build
Category *