OpenCms Documentation

The Flex Cache

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 6.0 Documented since: 9.0 Latest revision for: 9.0 Valid for OpenCms: 13.0

The flex cache is used to improve performance of your website. In OpenCms pages are typically built on-the-fly when requested. This involves many costly steps, e.g., database queries. To obtain a performant web site, caching is essential.

Not every resource's output HTML should be cached the same way. E.g., navigation content's HTML output used on many pages should be rendered and cached for each page separately, a function that outputs date and time should be rendered on every request, a completely static content item should be rendered only once, equally at which page it is used, etc. The flex cache is the tool to configure caching in a resource specific way.

Configuration options

The FlexCache is enabled or disabled in the configuration file /WEB-INF/config/opencms-system.xml of your OpenCms web application. There are two options to set the FlexCache:

  1. Enable or disable the cache completely and
  2. enable or disable caching of resources in the offline projects (i.e. resources which are not yet published).

Here's the default configuration in /WEB-INF/config/opencms-system.xml:

Configuration nodes

Enables or disables the FlexCache. If you disable the FlexCache, you do not need to bother about the settings of the other Flex cache values.
The following values are possible:
true (default): The FlexCache is enabled.
false: The FlexCache is disabled.


In a development environment, we recommend to set the value of the cache-offline node to true so that you can test out the caching behaviour of the application without publishing. In a production environment you should set cache-offline node to false. The following values are supported:
true: The FlexCache for offline projects is enabled.
false (default): The FlexCache for offline projects is disabled.


The maximum amount of server memory used by the FlexCache in bytes. The amount of available server memory is the critical factor here and has to be considered carefully.


The average amount of server memory used by the FlexCache in bytes.


The maximum size of a single cache entry in bytes.


The maximum number of cached page variations in the FlexCache.

The default settings of the FlexCache parameters after installing OpenCms are:

  1. The FlexCache is enabled
  2. The cache for offline projects is disabled
  3. The FlexCache uses 8mb memory for the cached pages or a maximum of 2000 cached page variations in total.
The caching of offline resources is highly useful in the development process, because you can directly check how your application caching behaves after publishing. Make sure you know the FlexCache request parameters so that you can easily clear the cache after you change something in your offline project.

Flex cache directives

The following table lists all possible FlexCache directives. These directives must be attached to a specific page using the cache property. In case you want to set more than one directive, use a semicolon ";" to separate them.

Settings for FlexCache directives are not case sensitive.
The flex cache directives
never (default)

This resource is not cachable. Nothing will be cached under any circumstance. This overrides all other directives that might also be given.


Synonym for never.


This resource is cachable and there will always be the same result generated for all requests, i.e., only one variation entry for the page will be saved in the cache. This overrides all other directives (other than never and no-params) that might also be given.


Synonym for always.


One variation entry of this resource is generated for every different user. Please keep in mind that this might lead to a great number of entries in the cache in case you have a website with many different users. You should know that any client not authorized is treated in OpenCms as user "Guest", so all requests always belong to a specific user.


One variation entry of this resource is generated for every "top level" URI that is requested. This is useful for navigation elements that are included as a sub-element on a page, where usually the URI of the requested page decides which entries have to be displayed in the navigation.


This directive sets a timeout at which a cached resource will be invalidated. The given integer represents a minute - interval which starts at 0.00h of the day the cache key gets calculated. A value of 60 would indicate that this entry will reach its timeout at the beginning of every full hour. A timeout of 20 indicates that the entry is invalidated at x.00, x.20 and x.40 of every hour etc. A "timed out" resource will stay in the cache but will be re-calculated the next time it gets requested.

attrs or attrs=(param1, param2, ...)

If you use attrs=(attr1, attr2,...) there will be one variation entry generated for every value of all listed request attributes (or combination thereof). If you use attrs there will be one variation entry of this resource generated for every different attribute value of every different attribute.

no-attrs or no-attrs=(no-attr1, no-attr2)

This directive prevents the caching of a resource. If you use no-attrs the occurrence of any attribute in the request will prevent caching of the resource. If you use no-attrs=(no-attr1, no-attr2,...), the occurrence of any of the listed parameters will prevent caching of the resource. Note that these "blocking" directives always overrule all other directives.

params or params=(param1, param2, ...)

If you use params=(param1, param2,...) there will be one variation entry generated for every value of all listed parameters (or combination thereof). If you use params there will be one variation entry of this resource generated for every different parameter value of every different parameter. This directive is useful if you have something like a "show article" page that gets dynamically calculated from a database with something like an "id" parameter that selects the article to be displayed. So if you have a page showarticle.jsp that gets usually called like showarticle.jsp?article_id=123, you could just set the caching properties of this page to params=(article_id) and thus cache every single article page.

no-params or no-params=(no-param1, no-param2)

This directive prevents the caching of a resource. If you use no-params the occurrence of any parameter in the request will prevent caching of the resource. If you use no-params=(no-param1, no-param2,...), the occurrence of any of the listed parameters will prevent caching of the resource. This directive is useful on simple forms. Usually (esp. using JSPs) you will have only one URI for all requests to the form, i.e., the form is posted to its own URL and the JSP behind it handles the form validation. With the no-params directive you can cache the "first", empty view of the form, while any requests with data in the form will cause the page to be generated dynamically. Note that these "blocking" directives always overrule all other directives.


This cache directives creates one variation of a page for every element. This important directive is required if multiple xmlpage elements are included from the same URI. It ensures that changes in the listed sub-elements will result in an update of the including page.


This directive creates one variation entry of the resource for every locale value. This cache directive is nescessary, if locale-based localization is used for elements that are used in different language variations.


One variation entry of the resource is created for every encoding value. If a sub-element is used with different encodings in different parts of a site, the caching must be encoding dependent.

schemes=(scheme1, scheme2, ...)

This directive causes a variation to be generated for every (or every listed) request scheme. The most often used request schemes are currently "http" or "https".

ports=(port1, port2, ...)

This directive causes a variation to be generated for every listed server TCP port of the request. This might come handy in complex OpenCms setup scenarios where a server is addressed by multiple ports.

session=(attribute1, attribute2, ...)

If you use session=(attribute1, attribute2,...) there will be one variation entry generated for every value of all listed session attributes  (or combination thereof). You must at least use one attribute value.

If you are using the session cache directive in combination with the user directive, your browser might not be able to distinguish between the different versions delivered by OpenCms because of its own internal browser caching. In such an scenario, you must disable the browser caching by setting correct http headers in your OpenCms application.

If you use site there will be one variation entry generated for every OpenCms site. This can be used to cache site-specific elements, e.g., template heads with logos, etc.


This directive causes a variation to be generated for every client ip addresses of the request. This enables a caching based on different client locations.


To be used together with formatter JSPs. Use this directive to ensure that an element is rendered correctly inside a container, if it occurs several times on a single page inside different containers.


To be used when JSPs render device specifically, either by evaluating the template context via the provider or the <cms:device> tag. The directive causes the flex cache to cache different versions of HTML output for different contexts.


If the cache directive bypass is set, the flex cache will be by passed, i.e., compared to false or never, the request is processed without entering the cache at all.


If the cache directive stream is set, OpenCms will not buffer JSP output first.

Flex cache buckets

Flex cache buckets were introduced in OpenCms 11 to improve the performance of the flex cache. The motivation is as follows: In the default scenario without buckets, the flex cache is completely flushed on each publish event. It does not matter if the published resources will change the cached JSP output or not. To reduce the need of rendering all JSPs again after a publish event, it would be great to selectively flush only parts of the flex cache, depending on the resources that are published.

Unfortunately, it is not possible to calculate which change at which resource influences the output of which JSP in general. But, to some extend we can assume what changes cannot influence the output of what JSPs. In the bucket scenario, we explore the caching directives set at the JSPs for the assumptions.

Buckets are in particular designed to omit complete flushing the flex cache if there are changes in only one or some sites.

Bucket configuration example

Buckets, introduced in OpenCms 11, are configured by placing the file under /system/config/. The file holds the bucket configuration as key-value pairs. Typically, you configure one bucket per site, e.g.:


In the example, we make up three buckets and assign a list of VFS root paths to each of them. Here, the path to a site ("bar", "baz" and "foo") and the path to the shared folder is added to each of them. Implicitly, the configuration holds as well:

  • a bucket OTHER that is configured for all VFS root paths not in any other bucket, i.e., not a (sub-)path of the paths configured for any other bucket
  • a clearAll=/system/modules entry - which can be overwritten by an explicit configuration.

Flushing behavior of buckets

When a publish event occurs, the flex cache entries are flushed depending on the buckets they belong to. In particular, an entry is deleted if:

  • a resource is published that is in one of the configured root paths of a bucket assigned to the entry.
  • a resource under one of the VFS root paths configured as clearAll is published.
  • no bucket is assigned to the entry.

In our example configuration this means in particular, that publishing changes in site "baz" will not flush the buckets for sites "bar" and "foo".

What is cached in which bucket?

Which flex cache entry goes to which bucket(s) is determined by the cache directives set at the JSP whose output is cached. In particular, path information contained in the flex directive is explored. The scenario is as follows:

  • If there are path information in the cache directives, the JSP output is cached in all buckets the path belongs to (i.e., buckets where the path itself or a root folder is configured for).
  • If there is no path information in the cache directive, the JSP output is added to no bucket at all.

Path information is contained in multiple flex cache directives, e.g., uri or container-element. But there are also directives that contain no path information, e.g. always. For such, the flex cache entries are added to no bucket at all and thus they are removed from the cache on each publish event.

You should keep in mind that the cache directives do not necessarily tell the dependencies of the JSPs output. Hence, be careful when using the flex cache buckets. Even if the assumptions made are kind of conservative, you should know your JSPs when configuring the buckets.