Module org.omnifaces
Package org.omnifaces.resourcehandler

Class CombinedResourceHandler

java.lang.Object
jakarta.faces.application.ResourceHandler
jakarta.faces.application.ResourceHandlerWrapper
org.omnifaces.resourcehandler.DefaultResourceHandler
org.omnifaces.resourcehandler.CombinedResourceHandler
All Implemented Interfaces:
FacesListener, SystemEventListener, FacesWrapper<ResourceHandler>, EventListener
public class CombinedResourceHandler extends DefaultResourceHandler implements SystemEventListener

This ResourceHandler implementation will remove all separate script and stylesheet resources which have the target attribute set to "head" from the UIViewRoot and create a combined one for all scripts and another combined one for all stylesheets. In most cases your application's pages will load considerably. Optionally, the combined resource files can be cached on the server during non-development stage, giving your application another boost (at the expense of some heap memory on the server side).

Installation

To get it to run, this handler needs be registered as follows in faces-config.xml: 

 <application>
     <resource-handler>org.omnifaces.resourcehandler.CombinedResourceHandler</resource-handler>
 </application>

Usage

Noted should be that the target attribute of <h:outputStylesheet> already defaults to "head" but the one of <h:outputScript> not. So if you have placed this inside the <h:head>, then you would still need to explicitly set its target attribute to "head", otherwise it will be treated as an inline script and not be combined. This is a design limitation. This is not necessary for <o:criticalStylesheet> nor <o:deferredScript>. 

 <h:head>
     ...
     <h:criticalStylesheet name="layout.css" />
     <h:outputStylesheet name="page.css" />
     <h:outputScript name="script.js" target="head" />
     <o:deferredScript name="onload.js" />
 </h:head>

If you want them to appear after any auto-included resources of standard Faces implementation or Faces component libraries, then move the declarations to top of the <h:body>. This is not necessary for <o:criticalStylesheet> nor <o:deferredScript> as they already auto-relocate by themselves. 

 <h:body>
     <h:outputStylesheet name="style.css" />
     <h:outputScript name="script.js" target="head" />
     ...
 </h:body>

The generated combined resource URL also includes the "v" request parameter which is the last modified time of the newest individual resource in minutes, so that the browser will always be forced to request the latest version whenever one of the individual resources has changed.

Since 3.11, <h:outputStylesheet media="print"> will be explicitly excluded from the combined resource.

Caching

Optionally you can activate server-side caching of the combined resource content by specifying the below context parameter in web.xml with the amount of seconds to cache the combined resource content. 

 <context-param>
     <param-name>org.omnifaces.COMBINED_RESOURCE_HANDLER_CACHE_TTL</param-name>
     <param-value>3628800</param-value> <!-- 6 weeks -->
 </context-param>

This is only considered when the Faces project stage is not set to Development as per Faces.isDevelopment().

This can speed up the initial page load considerably. In general, subsequent page loads are served from the browser cache, so caching doesn't make a difference on postbacks, but only on initial requests. The combined resource content is by default cached in an application scoped cache in heap space. This can be customized as per instructions in Cache javadoc. As to the heap space consumption, note that without caching the same amount of heap space is allocated and freed for each request that can't be served from the browser cache, so chances are you won't notice the memory penalty of caching.

Configuration

The following context parameters are available:

All available context parameters
"org.omnifaces.COMBINED_RESOURCE_HANDLER_EXCLUDED_RESOURCES" Comma separated string of resource identifiers of <h:head> resources which needs to be excluded from combining. For example:
<param-value>primefaces:primefaces.css, jakarta.faces:faces.js</param-value>
Any combined resource will be included after any of those excluded resources.
"org.omnifaces.COMBINED_RESOURCE_HANDLER_SUPPRESSED_RESOURCES" Comma separated string of resource identifiers of <h:head> resources which needs to be suppressed and removed. For example:
<param-value>skinning.ecss, primefaces:jquery/jquery.js</param-value>
"org.omnifaces.COMBINED_RESOURCE_HANDLER_INLINE_CSS" Set to true if you want to render the combined CSS resources inline (embedded in HTML) instead of as a resource.
"org.omnifaces.COMBINED_RESOURCE_HANDLER_INLINE_JS" Set to true if you want to render the combined JS resources inline (embedded in HTML) instead of as a resource.
"org.omnifaces.COMBINED_RESOURCE_HANDLER_CACHE_TTL" Set with a value greater than 0 to activate server-side caching of the combined resource files. The value is interpreted as cache TTL (time to live) in seconds and is only effective when the Faces project stage is not set to Development as per Faces.isDevelopment(). Combined resource files are removed from the cache if they are older than this parameter indicates (and regenerated if newly requested). The default value is 0 (i.e. not cached). For global cache settings refer Cache javadoc.

Here, the "resource identifier" is the unique combination of library name and resource name, separated by a colon, exactly the syntax as you would use in #{resource} in EL. If there is no library name, then just omit the colon. Valid examples of resource identifiers are filename.ext, folder/filename.ext, library:filename.ext and library:folder/filename.ext.

Note that this combined resource handler is not able to combine resources which are not been added as a component resource, but are been hardcoded in some renderer (such as theme.css in case of PrimeFaces), or are been definied using plain HTML <link> or <script> elements.

Conditionally disable combined resource handler

If you'd like to supply a context parameter which conditionally disables the combined resource handler, then set the context parameter "org.omnifaces.COMBINED_RESOURCE_HANDLER_DISABLED" accordingly. 

 <context-param>
     <param-name>org.omnifaces.COMBINED_RESOURCE_HANDLER_DISABLED</param-name>
     <param-value>true</param-value>
 </context-param>
 <!-- or -->
 <context-param>
     <param-name>org.omnifaces.COMBINED_RESOURCE_HANDLER_DISABLED</param-name>
     <param-value>#{facesContext.application.projectStage eq 'Development'}</param-value>
 </context-param>
 <!-- or -->
 <context-param>
     <param-name>org.omnifaces.COMBINED_RESOURCE_HANDLER_DISABLED</param-name>
     <param-value>#{someApplicationScopedBean.someBooleanProperty}</param-value>
 </context-param>

The EL expression is resolved on a per-request basis.

CDNResourceHandler

If you're also using the CDNResourceHandler or, at least, have configured its context parameter "org.omnifaces.CDN_RESOURCE_HANDLER_URLS", then those CDN resources will automatically be added to the set of excluded resources.

CDNResource

Since 2.7, if you have configured a custom ResourceHandler (not CDNResourceHandler) which automatically uploads the resources to a CDN host, including the combined resources, and you want to be able to have a fallback to local host URL when the CDN host is unreachable, then you can let your custom ResourceHandler return a CDNResource which wraps the original resource and the CDN URL. The combined resource handler will make sure that the appropriate onerror attributes are added to the component resources which initiates the fallback resource in case the CDN request errors out.

Historical note: before 5.0, the CombinedResourceHandler also added crossorigin and integrity attributes to every combined resource, but it also unnecessarily did that when the resource is not a CDN resource, and all non-combined resources were ignored. Hence this task has since 5.0 been split into CorsAwareResourceRenderer on which the job was improved.

Author:
Bauke Scholtz, Stephan Rauh <www.beyondjava.net>
See Also:

  • Field Details

    • LIBRARY_NAME

      public static final String LIBRARY_NAME
      The default library name of a combined resource. Make sure that this is never used for other libraries.
      See Also:

    • PARAM_NAME_DISABLED

      public static final String PARAM_NAME_DISABLED
      The context parameter name to conditionally disable combined resource handler. @since 2.0
      See Also:

    • PARAM_NAME_EXCLUDED_RESOURCES

      public static final String PARAM_NAME_EXCLUDED_RESOURCES
      The context parameter name to specify resource identifiers which needs to be excluded from combining.
      See Also:

    • PARAM_NAME_SUPPRESSED_RESOURCES

      public static final String PARAM_NAME_SUPPRESSED_RESOURCES
      The context parameter name to specify resource identifiers which needs to be suppressed and removed.
      See Also:

    • PARAM_NAME_INLINE_CSS

      public static final String PARAM_NAME_INLINE_CSS
      The context parameter name to enable rendering CSS inline instead of as resource link.
      See Also:

    • PARAM_NAME_INLINE_JS

      public static final String PARAM_NAME_INLINE_JS
      The context parameter name to enable rendering JS inline instead of as resource link.
      See Also:

    • PARAM_NAME_CACHE_TTL

      public static final String PARAM_NAME_CACHE_TTL
      The context parameter name to specify cache TTL of combined resources. @since 2.1
      See Also:

  • Constructor Details

    • CombinedResourceHandler

      public CombinedResourceHandler(ResourceHandler wrapped)
      Creates a new instance of this combined resource handler which wraps the given resource handler. This will also register this resource handler as a pre render view event listener, so that it can do the job of removing the CSS/JS resources and adding combined ones.
      Parameters:
      wrapped - The resource handler to be wrapped.

  • Method Details

    • isListenerForSource

      public boolean isListenerForSource(Object source)
      Returns true if the source is an instance of UIViewRoot.
      Specified by:
      isListenerForSource in interface SystemEventListener

    • processEvent

      public void processEvent(SystemEvent event)
      Before rendering of a freshly created view, perform the following actions:
      • Collect all component resources from the head.
      • Check and collect the script and stylesheet resources separately and remove them from the head.
      • If there are any resources in the collection of script and/or stylesheet resources, then create a component resource component pointing to the combined resource info and add it to the head at the location of the first resource.
      Specified by:
      processEvent in interface SystemEventListener

    • getLibraryName

      public String getLibraryName()
      Returns LIBRARY_NAME.
      Overrides:
      getLibraryName in class DefaultResourceHandler
      Returns:
      The library name on which this resource handler implementation should listen.

    • createResourceFromLibrary

      public Resource createResourceFromLibrary(String resourceName, String contentType)
      Returns a new CombinedResource.
      Overrides:
      createResourceFromLibrary in class DefaultResourceHandler
      Parameters:
      resourceName - The resource name.
      contentType - The content type.
      Returns:
      The library-specific resource.