Module org.omnifaces
Package org.omnifaces.component.output

Class Cache

  • All Implemented Interfaces:
    PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
    public class Cache
extends OutputFamily

    The <o:cache> component allows to cache a fragment of rendered markup. The first request for a page that has this component on it will cause this markup to be put into the cache. Then for subsequent requests the cached content is used directly and none of the components, backing beans and services that were used to generate this content in the first place will be consulted.

    Caching can take place in application scope, or in session scope. For individual fragments a time can be specified for which the cached content is valid. After this time is elapsed, the very first request to the page containing the cache component in question will cause new content to be rendered and put into the cache. A default time can be set per scope in web.xml.

    For each scope a maximum capacity can be set. If the capacity for that scope is exceeded, an element will be removed following a least recently used policy (LRU).

    Via a cache provider mechanism an alternative cache implementation can be configured in web.xml. The default cache is based on LruCache.

    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:

    All available context parameters
    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.
    Since:
    1.1
    Author:
    Arjan Tijms
    See Also:
    Cache, CacheEntry, CacheFactory, CacheInitializer, CacheInstancePerScopeProvider, CacheProvider, DefaultCache, DefaultCacheProvider, LruCache, TimeToLiveCache, CacheValue, CachingValueExpression, OnDemandResponseBufferFilter, BufferedHttpServletResponse, HttpServletResponseOutputWrapper, ResettableBuffer, ResettableBufferedOutputStream, ResettableBufferedWriter, OutputFamily

    • Field Detail

      • COMPONENT_TYPE

        public static final String COMPONENT_TYPE
        The component type, which is "org.omnifaces.component.output.Cache".
        See Also:
        Constant Field Values

    • Constructor Detail

      • Cache

        public Cache()
        Constructs the component.

    • Method Detail

      • getCacheAttribute

        public Serializable getCacheAttribute​(FacesContext context,
                                      String name)
        Gets a named attribute associated with the main cache entry this component is using to store the rendering of its child components.
        Parameters:
        context - the current FacesContext
        name - name of the attribute to retrieve a value for
        Returns:
        value associated with the named attribute
        Since:
        1.2

      • setCacheAttribute

        public void setCacheAttribute​(FacesContext context,
                              String name,
                              Serializable value)
        Sets a named attribute associated with the main cache entry this component is using to store the rendering of its child components.
        Parameters:
        context - the current FacesContext
        name - name of the attribute under which the value is stored
        value - the value that is to be stored
        Since:
        1.2

      • getKey

        public String getKey()
        Returns key used to store content in the cache.
        Returns:
        Key used to store content in the cache.

      • setKey

        public void setKey​(String keyValue)
        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.

        Parameters:
        keyValue - Key used to store content in the cache.

      • getScope

        public String getScope()
        Returns scope identifier used to set the scope in which caching takes place. Default is session.
        Returns:
        Scope identifier used to set the scope in which caching takes place.

      • setScope

        public void setScope​(String scopeValue)
        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.

        Parameters:
        scopeValue - Scope identifier used to set the scope in which caching takes place.

      • getTime

        public Integer getTime()
        Returns amount of time in seconds for which the cached content is valid (TTL). Default is -1.
        Returns:
        Amount of time in seconds for which the cached content is valid (TTL).

      • setTime

        public void setTime​(Integer timeValue)
        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.

        Parameters:
        timeValue - Amount of time in seconds for which the cached content is valid (TTL).

      • isUseBuffer

        public boolean isUseBuffer()
        Returns whether to switch to an alternative method to grab the content generated by the children of this component. Default is false.
        Returns:
        Whether to switch to an alternative method to grab the content generated by the children of this component.

      • setUseBuffer

        public void setUseBuffer​(boolean useBufferValue)
        Switches to an alternative method to grab the content generated by the children of this component.

        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).

        Parameters:
        useBufferValue - Whether to switch to an alternative method to grab the content generated by the children of this component

      • isReset

        public boolean isReset()
        Returns whether to reset this cache. Default is false.
        Returns:
        Whether to reset this cache.

      • setReset

        public void setReset​(boolean resetValue)
        Resets the cache when set to true.

        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.

        Parameters:
        resetValue - Whether to reset this cache.

      • isDisabled

        public boolean isDisabled()
        Returns whether this cache is disabled. Default is false.
        Returns:
        Whether this cache is disabled.
        Since:
        1.8

      • setDisabled

        public void setDisabled​(boolean disabledValue)
        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.

        Parameters:
        disabledValue - Whether this cache is disabled.
        Since:
        1.8