Glossary

  1. Home
  2. reference
  3. glossary
  4. http caching

HTTP Caching

Whenever it can, Berlioz generates entity tags (ETags) so it can take advantage of HTTP caching. This is done automatically.

Is a service cacheable?

Caching Berlioz services requires that all generators in the service use the Cacheable interface to produce an entity tag from the ContentRequest :

String getETag(ContentRequest req);

While the entity tag can be a non-specific value, such as the last modified date of a file, database or index, it must be fast to compute.

Note

Use the Berlioz admin tools to check the processing time of this method. If it isn't comfortably and consistently under 10ms, there may be no point in computing an entity tag.

How Berlioz generates entity tags?

If the service is cacheable, Berlioz will automatically compute an entity tag from the following values:

  • the ETag seed created at startup,
  • the ETag from the XSLT templates when applicable,
  • the list of ETags produced by each Cacheable generator.

This means that the entity tag will change whenever:

  • the application server (Jetty, etc...) is restarted,
  • or the XSLT is modified,
  • or any of the generators return a different ETag.

Note

If the ETag of a generator is null, then this generator is not cacheable. This can be useful in cases when under some conditions, a generator isn't able to return a cacheable response.

How Berlioz sets Cache-Control?

Following is the order of value that Berlioz uses to generate the HTTP Cache-Control HTTP response header. See below for specific detail:

  1. When specified, the value of the cache-control attribute for a service.
  2. Next is the value of the initialisation parameter of the Berlioz servlet.
  3. Without a value at the service-level or servlet-level, the value from the global server configuration will be used.

Note

The cache-control HTTP header response is only sent for a service considered cacheable.

Service configuration

A specific cache-control HTTP response header can be created for any service in the services configuration (services.xml) through the use of the @cache-control attribute. For example:

<service id="example" method="get" cache-control="private, max-age=0">
   ...
</service>

Servlet configuration

Following is an example of how the servlet's initialisation parameter (init-param) is declared in the Web descriptor (/WEB-INF/web.xml):

<servlet>
   <servlet-name>BerliozHTML</servlet-name>
   <servlet-class>org.pageseeder.berlioz.servlet.BerliozServlet</servlet-class>
   <init-param>
      <param-name>cache-control</param-name>
      <param-value>private, max-age=0</param-value>
   </init-param>
   ...
</servlet>

Global configuration

With no other option available, Berlioz drops back to the global cache control value defined in the global configuration (/WEB-INF/config-[mode].xml).

<berlioz>
  <http cache-control="private, max-age=0"/>
                     ...
</berlioz>

If cache control is not explicitely set, Berlioz will try to use the max-age property as "max-age=[maxage], must-revalidate".

<berlioz>
  <http max-age="60"/>
  ...
</berlioz>

If no time is specified, Berlioz will use 60 seconds.

The global configuration is usually the best way to specify the default value for the "Cache-Control" header. However, in development mode, set cache control to "max-age=0". This will ensure that pages are systematically reloaded by the Web browser.

Created on , last edited on