cache (OmniFaces VDL Documentation - Generated Documentation)

Description:

Cache is a component that initially renders the output of its children into a buffer instead of to the response. This output is then inserted into a cache and on subsequent requests the content retrieved from the cache is used.

By default the viewid concatenated to the component id via an underscore is used as the cache key.

Note that this component does not support a cache loader and locking mechanism. This mean several simultaenous page requests may render the same content and it's undetermined which of those will end up being cached.

An optional caching provider (see below) can be set to control the caching implementation that is used for the actual caching. If no such provider is installed, a default caching implementation is used that's based on LruCache in case a maximum cache capacity is set, or on a plain ConcurrentHashMap if no capacity is set.

Setting a custom caching provider

A custom caching provider can be set by using the org.omnifaces.CACHE_PROVIDER context parameter in web.xml to point to an implementation of org.omnifaces.component.output.cache.CacheProvider. For example:

<context-param>
    <param-name>org.omnifaces.CACHE_PROVIDER</param-name>
    <param-value>com.example.MyProvider</param-value>
</context-param>

The default provider, org.omnifaces.component.output.cache.DefaultCacheProvider can be used as an example.

Global settings

For the default provider, the maximum capacity and the default time to live can be specified for the supported scopes "session" and "application". If the maximum capacity is reached, an entry will be evicted following a least recently used policy. The default time to live specifies for how long entries are considered to be valid. A value for the time attribute on this component will override this global default time to live. The following context parameters can be used in web.xml:

`org.omnifaces.CACHE_SETTING_APPLICATION_MAX_CAPACITY`	Sets the maximum number of elements that will be stored per web module (application scope). Default: no limit
`org.omnifaces.CACHE_SETTING_SESSION_MAX_CAPACITY`	Sets the maximum number of elements that will be stored per session. Default: no limit
`org.omnifaces.CACHE_SETTING_APPLICATION_TTL`	Sets the maximum amount of time in seconds that cached content is valid for the application scope. Can be overriden by individal cache components. Default: no limit
`org.omnifaces.CACHE_SETTING_SESSION_TTL`	Sets the maximum amount of time in seconds that cached content is valid for the session scope. Can be overriden by individal cache components. Default: no limit
`org.omnifaces.CACHE_INSTALL_BUFFER_FILTER`	Boolean that when true installs a Servlet Filter (Servlet 3.0+ only) that works in conjunction with the `useBuffer` attribute of the Cache component to enable an alternative way to grab the content that needs to be cached. This is a convenience setting that is a short-cut for installing the `org.omnifaces.servlet.BufferedHttpServletResponse` filter manually. If more finegrained control is needed regarding which place in the filter chain the filter appears and which resources it exactly filters, this setting should not be used and the mentioned filter should be manually configured. Default: `false`)

Component Information
Info	Value
Component Type	`org.omnifaces.component.output.Cache`
Handler Class	None
Renderer Type	None
Description	None

Attributes
Name	Required	Type	Description
`disabled`	`false`	`jakarta.el.ValueExpression` (must evaluate to `boolean`)	Disables the cache when set to `true`. Default is `false`. This attribute can be used to disable the cache (temporarily). In disabled state the children will be rendered directly and cached content (if any) will not be used, nor will the rendering outcome of the children be cached. When the attribute is set to `false` again any content that was cached before the cache was disabled will be shown again if said content is still available in the cache. The content that was rendered when the cache was disabled has no effect on any such previously cached content.
`key`	`false`	`jakarta.el.ValueExpression` (must evaluate to `java.lang.String`)	Optional key used to store content in the cache. If no key is specified, a key is calculated based on the client Id of this component. While auto-generated keys can be convenient, note that in the face of dynamic behavior on a view the id of a component and thus the cache key can change in ways that are difficult to predict. Keys are relative to the scope for which they are defined, meaning a key "foo" for the a session scoped cache will not conflict with a key of the same name for an application scoped cache.
`reset`	`false`	`jakarta.el.ValueExpression` (must evaluate to `boolean`)	Resets the cache when set to `true`. Default is `false`. This attribute can be used to reset the cache, meaning that the first time the cache component is rendered again, it will re-render its children and will cause any cached value expressions (via `o:cacheValue`) to be re-evaluated when its next referenced. Note that this value has to remain true until the cache component is rendered, after that it should be set to false again otherwise the cached content will be reset again at the next rendering.
`scope`	`false`	`jakarta.el.ValueExpression` (must evaluate to `java.lang.String`)	Optional scope identifier used to set the scope in which caching takes place. If no scope is specified, the default scope "session" will be used. The supported scopes depent on the caching provider that is installed via the `org.omnifaces.CACHE_PROVIDER`. If no such provider is installed, a default one is used that supports scopes "session" and "application". A runtime exception will be thrown if an unsupported value for scope is used.
`time`	`false`	`jakarta.el.ValueExpression` (must evaluate to `java.lang.String`)	Optional amount of time in seconds for which the cached content is valid (TTL). This is counted from the moment content is actually added to the cache. If no time is provided the content will be subject to the global cache settings, and in absence of these are subject to the behavior of the cache implementation that is used. The default cache implementation will simply cache indefinitely. Whether the content is actually removed from the cache (to preserve memory) after the given time has elapsed is dependend on the actual cache implementation that is used. The default cache implementation will NOT do this automatically, but will instead remove it only when the cache item is being accessed again. Following the above, new content will only be inserted into the cache following a page request. A time of e.g. `30` will not cause new content to be inserted into the cache at `30` seconds intervals. Note that this component does not support a cache loader and locking mechanism. This means after content times out, several simultaneous page requests may render the same content and it's undetermined which of those will end up being cached.
`useBuffer`	`false`	`jakarta.el.ValueExpression` (must evaluate to `boolean`)	Switches to an alternative method to grab the content generated by the children of this component. Default is `false`. Normally this content is obtained by replacing the so-called response writer when the parent Cache component delegates rendering to its children. However, in some cases (like `h:form`) there is an amount of post-processing being done on the response outside the context of this parent - child delegation. Via this switch, the full response is buffered if the cache doesn't contain content for this component and special markers are inserted surrounding the children's rendering. Afterwards, the content between the markers (if any) is extracted and inserted into the cache. Note that the full response is only buffered incase there's no value in the cache. For all other requests this buffering will not happen. Since this is clearly a more resource intensive and invasive method to grab content, it's not enabled by default. In addition to setting this attribute to `true`, the `org.omnifaces.servlet.BufferedHttpServletResponse` Servlet Filter needs to be configured to filter the Faces Servlet (or alternatively just the pages for which the buffering method should be used).

o

Tag cache

Setting a custom caching provider

Global settings