Cache
You can see cache information directly in the JCR and configure what items are cached by setting cache policies.
|
Typically, you would find this at:
|
By default, CSS, JavaScript, and images are cached. Pages are not cached by default. However, you can configure your policy to cache Pages.
See Server cache policy for help with that.
Configuration
Cache configuration is defined in /modules/cache/config/contentCaching/. Within each configuration you can define:
-
What to cache.
-
When to flush the cache.
-
What header data to pass to browsers.
-
Specific implementations of tasks.
| Node name | Value |
|---|---|
π modules |
|
π cache |
|
π config |
|
π contentCaching |
|
βΈ¬ defaultPageCache |
|
βΈ¬ uuid-key-mapping |
|
βΈ¬ compression |
|
βΈ¬ cacheFactory |
|
⬩ cacheResponseThreshold |
1000 |
The default value for cacheResponseThreshold is 500. For more information and configuration details, see the Cache threshold subsection below.
|
To select one of the cache configurations, set the defaultContentCachingConfigurationName 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.
| Node name | Value |
|---|---|
π server |
|
π filters |
|
π cache |
|
⬩ defaultContentCachingConfigurationName |
defaultPageCache |
⬩ class |
info.magnolia.module.cache.filter.CacheFilter |
Policy configuration
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 aren’t 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/contentCaching/defaultPageCache/cachePolicy.
The default implementation (info.magnolia.module.cache.cachepolicy.Default) checks if the content exists in the cache store and requests caching if the content is not found.
The alternative class (info.magnolia.module.cache.cachepolicy.Never) instructs the cache not to store the generated content. Server-side re-caching of no-cache requests (shift reload) is configurable and set to false by default.
| Node name | Value |
|---|---|
βΈ¬ defaultPageCache |
|
βΈ¬ cachePolicy |
|
βΈ¬ shouldBypassVoters |
|
βΈ¬ urls |
|
βΈ¬ deny |
|
βΈ¬ parameters |
|
βΈ¬ whitelist |
|
⬩ 0 |
^utm_.*$ |
βΈ¬ resources |
|
⬩ class |
info.magnolia.module.cache.cachepolicy.Default |
⬩ refreshOnNoCacheRequests |
false |
Whitelisting specific parameters
Since Magnolia 6.2.30, under ../shouldBypassVoters/deny/parameters/whitelist, you can configure a key-value(regex) map of request parameters that should be ignored and hence their requests cached as a result.
As shown in the example above, the map configured there causes caching of all requests containing the utm_* tracking tag(s), which could otherwise generate a high server load, for example when sending marketing mails or other material utilizing the utm_* tracking tag(s).
Cache key generator
You can define a custom cache key generator or configure the default one to meet your needs.
π cache |
|
π config |
|
π contentCaching |
|
βΈ¬ defaultPageCache |
|
βΈ¬ cachePolicy |
|
βΈ¬ shouldBypassVoters |
|
βΈ¬ ttlVoters |
|
βΈ¬ cacheKeyGenerator |
|
⬩ useRequestParameters |
false |
⬩ class |
info.magnolia.module.cache.cachekey.DefaultCacheKeyGenerator |
⬩ class |
info.magnolia.module.cache.cachepolicy.Default |
| Attribute | Default | Description |
|---|---|---|
|
|
Use URI as part of cache key. |
|
|
Use request query as part of cache key. |
|
|
Use request method (GET/POST/HEAD) as part of cache key. |
|
|
Use server name as part of cache key. |
|
|
Save information whether this request was made using a secure channel, such as HTTPS as part of cache key. |
|
|
Use user name as part of cache key. |
|
|
Use locale |
|
|
Use channel |
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.
-
info.magnolia.module.cache.browsercachepolicy.FixedDuration instructs the browser to cache the content for the specified length of time in minutes.
-
info.magnolia.module.cache.browsercachepolicy.Never instructs the browser to do nothing.
Client cache policy is configured in /modules/cache/config/contentCaching/defaultPageCache/browserCachePolicy.
|
Cache-Control directives
Using the directives property, you can also specify standard Cache-Control directives.
The directives property is only applied to info.magnolia.module.cache.browsercachepolicy.FixedDuration.
|
Example configuration
| Node name | Value |
|---|---|
βΈ¬ defaultPageCache |
|
βΈ¬ browserCachePolicy |
|
βΈ¬ policies |
|
βΈ¬ disableBrowserCacheInDevelopMode |
|
βΈ¬ voters |
|
βΈ¬ developMode |
|
⬩ class |
info.magnolia.voting.voters.PropertyVoter |
⬩ property |
magnolia.develop |
⬩ value |
true |
⬩ class |
info.magnolia.module.cache.browsercachepolicy.FixedDuration |
βΈ¬ farFuture |
|
⬩ class |
info.magnolia.module.cache.browsercachepolicy.FixedDuration |
⬩ expirationMinutes |
525600 |
βΈ¬ voters |
|
βΈ¬ resources |
|
⬩ class |
info.magnolia.module.cache.browsercachepolicy.FixedDuration |
⬩ expirationMinutes |
60 |
βΈ¬ voters |
|
⬩ op |
OR |
βΈ¬ dotResources |
|
⬩ class |
info.magnolia.voting.voters.URIStartsWithVoter |
⬩ pattern |
/.resources/ |
βΈ¬ contentType |
|
⬩ class |
info.magnolia.voting.voters.RequestExtensionVoter |
⬩ emptyExtensionVote |
false |
βΈ¬ allowed |
|
⬩ css |
css |
⬩ js |
js |
βΈ¬ dontCachePages |
|
⬩ class |
info.magnolia.module.cache.browsercachepolicy.Never |
βΈ¬ voters |
|
βΈ¬ default |
|
⬩ class |
info.magnolia.module.cache.browsercachepolicy.FixedDuration |
⬩ directives |
public, max-age=604800, immutable |
⬩ expirationMinutes |
10 |
⬩ class |
info.magnolia.module.cache.browsercachepolicy.BrowserCachePolicySet |
|
Since Magnolia 6.2.34, the |
Flush policy
The flush policy defines when to flush the cache. There are three policies, two of which are installed by default.
Flush upon changes from content publication
The default policy is info.magnolia.module.cache.flushpolicy.FlushAllFromPublishingEventPolicy, and you can set it via /modules/cache/config/contentCaching/defaultPageCache/flushPolicy/policies/flushAll@class.
This configuration flushes the cache whenever a publishing event is completely finished.
The cache can only be flushed completely.
Each module can register its own flush policy (or multiple policies) and receive events in each workspace.
Flush policies are informed about notifications from the publication module.
By default, all workspaces are allowed to flush unless they’re listed under the excludedWorkspaces subnode.
Alternatively, you can list the allowed workspaces per policy under the workspaces subnode of each policy.
Flush upon changes in workspaces
This configuration observes changes (content publication, import, edit) in a workspace and flushes the cache if new or modified content is detected.
The cache can be flushed completely, partially or not at all.
Each module can register its own flush policy (or multiple policies) and receive notifications about new or modified content in each workspace.
Flush policies are informed about changes in observed workspaces.
By default, all workspaces trigger a cache flush unless they’re listed under the excludedWorkspaces subnode.
Alternatively, you can list the observed workspaces per policy under the workspaces subnode of each policy.
If your custom workspace doesn’t affect the content of pages, you should register it under excludedWorkspaces, otherwise, a change in that workspace unnecessarily flushes the cache.
To enable this configuration, set /modules/cache/config/contentCaching/defaultPageCache/flushPolicy/policies/flushAll@class to info.magnolia.module.cache.FlushAllListeningPolicy.
Flush upon changes in light modules
|
Magnolia
|
Executors
These are actions taken once a caching decision is 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 can’t or shouldn’t be cached.
Executors can be configured at /modules/cache/config/contentCaching/defaultPageCache/executors.
Each of the executors is also responsible for configuring expiration headers.
|
| Node name | Value |
|---|---|
βΈ¬ defaultPageCache |
|
βΈ¬ executors |
|
βΈ¬ bypass |
|
βΈ¬ store |
|
βΈ¬ useCache |
Cacheable response codes
By default, all cacheable response codes are cached. For a full list, see RFC-7231: Overview of Status Codes and RFC 7233: 206 Partial Content.
Using the cacheableResponseCodes property, you can define exactly which codes you want cached.
...
defaultPageCache:
executors:
store:
cacheContent:
cacheableResponseCodes: 200,300,400 (1)
...| 1 | Where 200, 300, and 400 are cached only. |
Response headers in redirect requests
Setting cacheHeadersInRedirects to true allows headers to be included in the response of the redirect request (302).
...
defaultPageCache:
executors:
store:
cacheContent:
cacheHeadersInRedirects: true (1)
...| 1 | By default, the property is set to false to keep the behavior consistent with the previous versions. |
Whitelisting headers to be included in a cache key
Under allowedRequestHeaders, you can list headers that can be included in a cache key.
...
defaultPageCache:
cachePolicy:
cacheKeyGenerator:
allowedRequestHeaders:
x-my-header: x-my-header (1)
...| 1 | The x-my-header is allowed in this example, but the list is empty by default. |
Compression
Compression is a simple and effective way to save bandwidth and speed up your site. It’s 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’s 20 kB compressed. To improve performance further, zipped content is streamed from the repository to the client rather than read into memory first.
Configuring
You can configure which content types to compress. By default, the gzip filter bypasses compression for HTML, JavaScript and CSS because they’re explicitly selected for compression in the Cache module configuration. These types can be compressed efficiently because they’re text. The decision to compress a particular content type is made with voters. Voters are used whenever configuration values aren’t assigned at startup but depend on rules instead. In the Cache module configuration there are three voting rules based on content type:
-
text/html: HTML. -
application/x-javascript: JavaScript. -
text/css: Cascading Style Sheets.
| Node name | Value |
|---|---|
π cache |
|
π config |
|
βΈ¬ compression |
|
βΈ¬ voters |
|
βΈ¬ contentType |
|
βΈ¬ allowed |
|
⬩ 1 |
text/html |
⬩ 2 |
application/x-javascript |
⬩ 3 |
text/css |
⬩ class |
info.magnolia.voting.voters.RequestExtensionVoter |
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: XHTML. -
text/csv: Comma-separated value. -
text/plain: Textual data. -
text/xml: Extensible Markup Language. -
application/pdf: Portable Document Format.
As a rule, compressing the HTML, JavaScript and CSS is sufficient; it’s not necessary to compress binary content such as images. During the process, the browser sends a header telling the server that it accepts compressed content: Accept-Encoding: gzip. Note that Magnolia doesn’t cache big binaries.
|
Testing compression
To test your compression configuration, use a tool such as Web-Sniffer that allows you to change the
Accept, Encoding and User-Agent sent headers easily.
Here’s what the headers look like when the Magnolia demo site home page is submitted^ to the sniffer.
GET /demo-project.html HTTP/1.1 Host: demopublic.magnolia-cms.com
Connection: close User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1;
de; rv:1.9) Gecko/2008052906 Firefox/3.0 Accept-Encoding: gzip
Accept-Charset: ISO-8859-1,UTF-8;q=0.7,*;q=0.7 Cache-Control: no
Accept-Language: de,en;q=0.7,en-us;q=0.3 Referer: http://web-sniffer.netStatus: HTTP/1.1 200 OK Date: Fri, 23 Jul 2010 07:45:10 GMT Server:
Apache/2.2.9 X-Magnolia-Registration: Registered Cache-Control:
max-age=900 Last-Modified: Thu, 01 Jul 2010 14:03:12 GMT
Content-Encoding: gzip Vary: Accept-Encoding Content-Length: 3852
Connection: close Content-Type: text/html;charset=UTF-8Cache threshold
Cache threshold is used to determine if a response should be cached or not according to its size. Responses greater than the size configured aren’t cached.
Configuring
Since Magnolia 6.2.31, you can configure the threshold value at /modules/cache/config@cacheResponseThreshold. The value must be an integer and represents kilobytes.
The following is an example configuring the threshold to one megabyte.
| Node name | Value |
|---|---|
π modules |
|
π cache |
|
π config |
|
βΈ¬ compression |
|
βΈ¬ cacheFactory |
|
π contentCaching |
|
⬩ cacheResponseThreshold |
1000 |
|
Raising the threshold probably increases the amount of cached content, which uses additional system resources. To control usage, you can configure the cache to use a fixed amount of memory. See the For example, you can set |
|
You can set this value programatically, for example, in your custom renderer which does time-consuming operations: MgnlContext.getWebContext().getRequest().setAttribute(CacheResponseWrapper.ATTRIBUTE_IN_MEMORY_THRESHOLD, CacheResponseWrapper.DEFAULT_THRESHOLD * 2); You need to set this attribute before anything is written to the output. |
Advanced strategies
In DX Core, advanced caching strategies are available in separate Advanced Cache modules.
Flush events
Cache flush events can happen:
-
When publishing events complete, that is, when content is published successfully from the author to the public instance. This is the default behavior.
-
When content is updated. When debugging a custom cache configuration, it can be helpful to have these flushes indicated in the log file. For example, when using advance caching strategies like serving old content while recaching or eager recaching.
To enable the TRACE level logging for flush events, use the Log Tools app or adjust the log4j2 configuration file.
Enable flush debugging
With flush debugging enabled, you see the flush event indicated in the log. This also provides the name of the cache being flushed if you use multiple caches.
-
Open the Log Tools app.
-
Go to the Log Levels tab.
-
At the bottom of the page, enter the Logger name:
info.magnolia.module.cache. -
Click Add logger config and check the entry is added to the list above at
ALLlevel.