Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
Magnolia employs a web cache to store server responses so that future requests for the same content can be served faster. The chief benefit of using cache is a reduction in information load on the network, meaning:
The Magnolia cache module is based on Ehcache, an open source Java distributed cache. All cache data is stored in the filesystem. Note that the Ehcache filesystem can be local to the server or network, depending on configuration.
Cache is a community module bundled with Community and Enterprise Editions and is installed by default. To restore the default configuration, delete the
/modules/cache node and restart your server.
Although the Cache module is bundled as a separate module, it is essential to Magnolia and many other modules depend on it. Don't uninstall the Cache module. If necessary, disable caching by adding an
enabled node in
/server/filters/cache and set its value to
Caching is performed by the Cache filter, which is part of the standard Magnolia . When a request arrives to the Cache filter, the filter passes it to the browser cache policy.
Cache configurations are defined in
/modules/cache/config/configurations/. Within each configuration you can define:
Specific implementations of tasks.
To select one of the cache configurations, set the
cacheConfigurationName parameter in the Cache filter. The chosen configuration is read into a JavaBean using the Node2Bean mechanism, making it dynamically available to your own module code.
Caching behavior for each configuration is defined with policies.
Server cache policy: This policy defines whether the requested content should be cached or not. The decision to cache relies on voters, which are used whenever configuration values are not assigned at startup but depend on rules. Voters evaluate a rule such as "should content residing at this URL be cached" and return a positive or negative response. By default, all content on public instances is cached except the AdminCentral UI at
/.magnolia. Server cache policy is configured in
/modules/cache/config/configurations/default/cachePolicy. The default implementation (
Default) checks if the content exists in the Ehcache store and requests caching if the content is not found. The alternative class,
Client (browser) cache policy allows for different policies for different content types. Voters are used to define the caching rules. These policies define how long the browser may cache each content type. The time is passed to the browser in the response header. The
FixedDuration option instructs the browser to cache the content for the specified length of time in minutes.
Never instructs the browser to do nothing. Client cache policy is configured in
Flush policy: The Flush policy defines when to flush the cache. The default configuration observes changes (activation, import, edit) in a repository and flushes the cache if new or modified content is detected. Cache can be flushed completely, partially or not at all. Each module can register its own flush policy (or multiple policies) and receive notification about new or modified content in each repository. Flush policies are informed about changes in observed workspaces. The list of observed workspaces can be defined per policy under the
repositories sub node of each policy.
The Cache module provides a
RegisterWorkspaceForCacheFlushingTask install task that custom modules can use to register their workspace default
FlushAll policy. When registered, any cached content originating from this repository will be flushed from the cache when a change to any content anywhere in the repository is detected. By default the configuration repository is not observed. This means that activated changes to configuration elements will not always be served in the public instance. This can be overcome by manually flushing the cache in Cache tools. Alternatively, you can add this repository.
These are actions taken once a caching decision has been made. There are three possible actions:
useCache: Retrieves the cached item from the cache and streams it to the client.
store: Stores the response in the cache for future use.
bypass: Skips caching. This is useful for content that cannot or should not be cached.
Executors can be configured at
/modules/cache/config/configurations/executors. Each of the executors is also responsible for configuring expiration headers.
Magnolia uses Ehcache for its back-end cache functionality. Ehcache is a robust, proven and full-featured cache product which has made it the most widely-used Java cache. Ehcache has its own configuration options that can be set in
You can use a different cache library as long as you implement Java interfaces that allow you to configure caching behavior in the Configuration app. The library can be changed by implementing
CacheFactory. A cache factory is an interface that wraps the functionality and hides the configuration mechanism of the library you choose.
|Instructs Ehcache to wait the specified time in milliseconds before attempting to cache the request. Create the |
|Number of seconds between runs of the disk expiry thread.|
|Determines if disk store persists between restarts of the Virtual Machine.|
|Size to allocate to DiskStore for a spool buffer. Writes are made to this area and then asynchronously written to disk. Default: 30MB. Each spool buffer is used only by its cache. If OutOfMemory errors, you may need to lower this value. To improve DiskStore performance consider increasing it. Trace level logging in the DiskStore will show if put back ups are occurring.|
|If elements are set to eternal, timeouts are ignored and the element is never expired.|
|Sets maximum number of objects that will be created in memory. |
|Sets maximum number of objects maintained in the DiskStore. The default value of zero means unlimited.|
Policy is enforced upon reaching the maxElementsInMemory limit. Available policies:
|Permits elements to overflow to disk when the memory store has reached the maxInMemory limit.|
|Optional attribute. Sets max idle time between accesses for an element before it expires. Only used if the element is not eternal. A value of |
|Sets lifespan for an element. Only used if the element is not eternal. Optional attribute. A value of |
Compression is a simple and effective way to save bandwidth and speed up your site. It is a common practice used by Google and Yahoo! for example. (How to Optimize Your Site with GZIP Compression is a great general introduction to the topic.) Compression is performed in the gzip filter, configured in
/server/filters/gzip}. When a client requests a resource such as
index.html, Magnolia delivers it zipped. A typical HTML page is compressed to 20% of its original size. So if your page is 100 kB uncompressed, it is 20 kB compressed. To improve performance further, zipped content is streamed from the repository to the client rather than read into memory first.
text/css: Cascading Style Sheets.
To add more content types, such as XML, create a numbered property under
allowed. Use the Internet media type (MIME type) as value. Here are some common media types:
application/xhtml+xml: XHTM L.
text/csv: Comma-separated value.
text/plain: Textual data.
text/xml: Extensible Markup Languag.
application/pdf: Portable Document Format.
Accept-Encoding: gzip. Note that Magnolia does not cache big binaries.
While all modern browsers support compression, some older browsers do not, notably Internet Explorer 6 before Service Pack 2. To get around this, Magnolia uses a
userAgent voter that rejects compression and delivers uncompressed content if the browser identifies itself as IE6 in the
User-Agent field in request headers.
To test your compression configuration, use a tool such as Web-Sniffer that allows you to change the
User-Agent sent headers easily. Here's what the headers look like when the Magnolia demo site home page is submitted to the sniffer.
Cache related commands are in the
flushAll: Completely flushes all caches that are configured in
/modules/cache/config/configurations/default/flushPolicy/policies/flushAll/repositories. Note that the
imagingworkspace is not included in the flush by default.
flushByUUID: Completely flushes all entries related to given a UUID from all available caches. This command expects
flushNamedCache: Completely flushes a cache by name. Default cache names are
Tools > Cache tools provides the following operations:
The Cache tools page is installed as part of the Cache module.
By default, the following URLs are cached:
/.magnolia/*which is AdminCentral.
magnolia.developproperty is set to
magnolia.develop property to
true in the default
magnolia.properties file. For more complex configurations, you need to adjust the configuration under the
cachedirectory and restart.
jconsoleor use your server's own JMX administration interface if provided. Locate the
net.sf.ehcache.CacheManagerbean and invoke the
flush()operation of the default instance of the cache.
Note that the cache is not aware of the web application context; if you are changing the context of a previously deployed application, you need to flush the cache to make sure served pages do not contain absolute links still pointing to old context path.
There are various reasons why you may wish to exclude content from cache. For example, you may have components that query an external data source dynamically. The rendered HTML changes even if the content of the Magnolia page has not changed. When we say cached content we mean the rendered output generated by Magnolia itself, the actual content of the page. When you exclude a page from cache you tell Magnolia that it should re-render that content every time the page is requested by a user.
The first option for excluding content from cache is to configure an exclusion in the cache policy. The example below excludes all pages whose URL starts with
/.magnolia. This means that AdminCentral pages are not cached.
To implement a custom cache policy, implement the
CachePolicy interface and override the methods you wish to customize. The default policy:
...determines if a requested page should be cached, retrieved from the cache or not cached at all. It is called for every request and takes care of any expiration policy, that is if the page should be re-cached. The CacheFilter (or any other client component) can determine its behavior based on the return CachePolicyResult, which holds both the behavior to take and the cache key to use when appropriate.
Configure your custom cache policy class in
Cache header negotiation is a mechanism that allows templates and components to influence whether the content should be cached and for how long. This mechanism can be used when it is too late to configure an exclude, but you do not wish for a page to be cached. Excludes are typically configured before it is clear what kinds of pages editors will add and what kind of content those pages will have. Cache header negotiation allows page components to influence whether the page should be cached. You can use cache header negotiation for:
The following options are not best practices but they may help you during testing. Don't use them as a long-term production strategy.
. A more subtle solution is to add
bypassto the cache filter. This ensures that no cache filter is executed on particular URLs.
denylist of the cachePolicy. Entries on the
denylist are not cached by Magnolia but are taken through the entire filter chain, meaning that other policies such as
BrowserCachePolicycan still be applied. In effect this solution, 'switches off' caching for the URL in question.
Cache header negotiation uses standard cache response headers. Cache needs to be enabled for the site or cache headers have no effect on the server side cache. The mechanism is built into the Cache module and requires no extra modules. Cache header negotiation is being introduced to Magnolia in two phases:
In code, developers set the cache headers in the rendering model of a component or a template. This is the current implementation.
Example 1: Setting a cache header in Java code, snippet from
Example 2: Setting a cache header in a JSP template script.
This implementation causes contention on the cache. Other requests to the same page are blocked while one request is processed.
Administrators will be able to configure the caching behavior in renderable definitions such as in a template definition. This feature will be available in an upcoming release. Follow MAGNOLIA-3902 - Getting issue details... STATUS to stay updated.