Resource Handling

A resource is any file that the Faces runtime finds through a library name and a resource name and serves itself. It is represented by the abstract class jakarta.faces.application.Resource; the object that creates resources and serves their requests is the application’s ResourceHandler (Application.getResourceHandler()). Three things distinguish a resource from a static file:

Source: Jakarta Faces 4.1 specification, 2.6 Resource Handling and Jakarta Faces 4.1 API: ResourceHandler

The default ResourceHandler must look in two places, in this order:

Source: Jakarta Faces 4.1 specification, 2.6.1 Packaging Resources and Jakarta Faces 4.1 API: ResourceHandler

The Jakarta EE Tutorial describes the same two locations in the same order. The final Bookshelf layout from the project setup page, extended with what this page adds, looks like this:

Source: Jakarta EE Tutorial: Web Resources

What the test of this layout showed:

Source: Jakarta Faces 4.1 API: ResourceHandler.WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME

Every resource has a resource identifier, the path below the resources directory:

Source: Jakarta Faces 4.1 specification, 2.6.1.3 Resource Identifiers

Only resourceName is required. The segments appear in this order and the runtime ignores silently an identifier that does not follow the rules. A few rules decide most real cases:

The specification’s own examples, expressed with the Bookshelf names:

Source: Jakarta Faces 4.1 specification, 2.6.1.3 Resource Identifiers

Observations that go beyond the text of the specification:

Three standard components render resources. The library and name attributes of each identify the resource; target (Relocating Resources with target) moves it.

Source: Jakarta Faces 4.1 VDL: h:outputStylesheet, Jakarta Faces 4.1 VDL: h:outputScript and Jakarta Faces 4.1 VDL: h:graphicImage

The type attribute is gone in HTML5 mode. Since Faces 4.0 the link and script elements rendered for h:outputStylesheet and h:outputScript carry no type attribute when the doctype is HTML5 (issue 1565 in the 4.0 change list, "Skip type attribute from link and script when doctype is HTML5"); the browser defaults are text/css and text/javascript. The default Facelets processing mode is html5, which simplifies any doctype to <!DOCTYPE html> (see the doctype section), so the attribute shows only after switching a file extension to process-as xhtml. The same page with an h:outputStylesheet and an h:outputScript gave, on Mojarra 4.1.17 and MyFaces 4.1.4, the same result:

Source: Jakarta Faces 4.1 specification, B.2 Changes between 4.0 and 3.0

The resource also has an EL form. The resource implicit object (resolved by ResourceELResolver, see the implicit objects) turns #{resource['library:name']} into the request path of the resource, so it can go into any attribute or into plain HTML. #{resource['name']} is the form without a library. The specification states that these two render identically:

Source: Jakarta Faces 4.1 specification, 2.6.2 Rendering Resources

A complete Bookshelf view that uses all of them. Library css holds the site style, theme is the versioned library of the tree above, and js the scripts.

Source: Jakarta EE Tutorial: Web Resources

The head produced, on Mojarra:

Source: Jakarta EE Tutorial: Web Resources

MyFaces produced the same markup except that the theme.css link had no v parameter (see Versioning Libraries and Resources) and that a development-stage <div id="jakarta_faces_developmentstage_messages"> was appended to the body.

Three details of this output matter:

A resource tag can be written where it is convenient and rendered somewhere else. The target attribute names the destination: head, body or form. The mechanism is event-based: the renderer of the tag listens for PostAddToViewEvent and, when the component has a target attribute, passes it to UIViewRoot.addComponentResource(), which puts it in the facet of the view root that is named by the target. h:head, h:body and h:form render the resources of their own facet. The Jakarta EE Tutorial lists the three values.

Source: Jakarta EE Tutorial: Relocatable Resources

The output of this page was the same on both implementations, except for the position of the form script relative to the hidden fields:

Source: Jakarta EE Tutorial: Relocatable Resources

On MyFaces the c.js script came after the jakarta.faces.ViewState field, on Mojarra before it.

Source: Jakarta EE Tutorial: Relocatable Resources and Jakarta Faces 4.1 specification, 2.6.2.1 Relocatable Resources

The rules that this and further runs gave:

Moving scripts to the end of the body (the analytics.js of the example) lets the browser paint before it downloads and runs them. Scripts that must run before the page renders belong in the head. faces.js is the one to be careful with: its position is described on the Ajax page (Getting faces.js onto the Page).

A component or renderer should not require every page that uses it to remember its style sheet. The class-level annotation jakarta.faces.application.ResourceDependency (repeatable, with the container ResourceDependencies) declares it. It has name (required), library and target; all three may be EL expressions that resolve to a string. The annotation can be placed on classes only (@Target(TYPE)): it works on UIComponent and Renderer classes, not on methods or on managed beans. The runtime processes it when an instance of the class is inserted into the view on an initial request: it creates a UIOutput with the renderer type that ResourceHandler.getRendererTypeForResourceName() returns for the name, stores name, library and target as attributes and, with no target, adds it to the head by calling UIViewRoot.addComponentResource().

Source: Jakarta Faces 4.1 API: ResourceDependencies

Source: Jakarta Faces 4.1 API: ResourceDependency

Source: Jakarta Faces 4.1 API: ResourceDependency and Jakarta Faces 4.1 API: ResourceDependencies

Two badges on the page produced one badge.css link, one badge-print.css link in the head and a single badge.js script before </body> on both implementations: the once-per-response rule covers dependencies too. The order of the head links did differ: Mojarra rendered the dependencies of the component (badge.css, badge-print.css) before the palette.css that the page declared first, MyFaces rendered palette.css first. Do not rely on the relative order of a declared style sheet and a dependency; if one overrides the other, give the rule higher specificity or declare both the same way. Custom components and renderers are covered in Resources of a component and composite components in Composite Libraries; a composite component that uses h:outputStylesheet inside its implementation shares the once-per-response rule.

FacesServlet calls ResourceHandler.isResourceRequest() first. The default handler answers true when the request path contains the constant ResourceHandler.RESOURCE_IDENTIFIER, which is /jakarta.faces.resource. The request path that Resource.getRequestPath() produces depends on how the servlet is mapped (see the servlet mapping):

The query string carries the metadata: ln is the library name, loc the locale prefix and con the name of the resource library contract (resource library contracts have a page of their own: Resource Library Contracts). On Mojarra a versioned library or resource also adds a v parameter (Versioning Libraries and Resources). In the test with extension mapping a request without the mapped extension (/jakarta.faces.resource/bookshelf.css?ln=css) answered 404 from the container, because the FacesServlet was not involved; with the prefix mapping /faces/* the URL with the prefix answered 200 and the extension URL 404.

handleResourceRequest() then follows an algorithm that the specification fixes:

Source: Jakarta Faces 4.1 API: ResourceHandler.handleResourceRequest and Jakarta Faces 4.1 API: Resource

The excluded types default to .class .jsp .jspx .properties .xhtml .groovy (ResourceHandler.RESOURCE_EXCLUDES_DEFAULT_VALUE). A value that you configure replaces the default entirely instead of adding to it. This was run:

Source: Jakarta Faces 4.1 API: ResourceHandler.RESOURCE_EXCLUDES_PARAM_NAME

If you need a different list, repeat the default entries and add yours. The configuration above exists to show the replacement rule, not as a recommendation.

Versions exist so that a browser can cache a resource for a long time and still fetch the new one after a release. The specification’s rule is simple: if several versions of a library or a resource exist and none is asked for, the highest is used. Versions are directories in the library (theme/1_0_0, theme/1_1_0) or files in a folder named after the resource (print.css/1_0.css, print.css/1_2.css).

Source: Jakarta Faces 4.1 specification, 2.6.1.4 Libraries of Localized and Versioned Resources

The test showed three things that the text does not say:

Because the version is not portable, the reliable way to refresh a long-cached resource on every implementation is to put a changing token in the URL yourself. That is the first example of A Custom ResourceHandler.

A locale prefix puts a language-specific variant in front of the library: resources/es/img/logo.svg is the Spanish img/logo.svg. The prefix is read from the application message bundle declared in faces-config.xml, under the key jakarta.faces.resource.localePrefix (ResourceHandler.LOCALE_PREFIX), so the bundle for each locale defines which prefix applies. When the localized file does not exist, the handler falls back to the unprefixed one (specified, not run).

Source: Jakarta Faces 4.1 API: ResourceHandler.LOCALE_PREFIX and Jakarta Faces 4.1 API: ResourceHandlerWrapper

Source: Jakarta Faces 4.1 API: ResourceHandler.LOCALE_PREFIX and Jakarta Faces 4.1 specification, 2.6.1.4

A request with Accept-Language: es rendered logo.svg.xhtml?ln=img&loc=es and that URL returned the Spanish SVG; an English request rendered the URL without loc and received the English one, on both implementations. This is a different mechanism from the resource bundles used for text (Messages and Internationalization); the bundle here is only the place where the prefix is looked up. The default bundle file of the example holds a dummy entry so that the bundle exists for locales that have no prefix (an empty default file was not tried).

The bytes of a resource are not sent as they are. the API documentation of Resource.getInputStream() requires every Jakarta Expression Language expression in the resource to be evaluated before the bytes are served. This is how a style sheet refers to images that live in the same resource library structure without hard-coding the URL:

Source: Jakarta Faces 4.1 API: Resource.getInputStream

Fetched through the resource handler, the line became background: url(/bookshelf/jakarta.faces.resource/logo.svg.xhtml?ln=img) no-repeat top right; on both implementations. That is the reason to keep a style sheet’s images in resources instead of using relative paths such as ../img/logo.svg, which would break because the style sheet is not served from /css/ (reasoned from the URL, not run).

The same Javadoc warns that, because of browser and server caching, an expression is in practice evaluated once, when the resource is first served, so an expression that refers to per-request or per-user data goes stale. Use EL in resources for stable values (other resources, constants, context path), not for the user name or a token. The fetch through the web root bypasses the evaluation altogether (see Where Resources Live): the style sheet fetched directly from /bookshelf/resources/css/bookshelf.css still contained #{resource['img:logo.svg']} as text.

Resource requests are the part of an application whose headers matter most, because they are repeated for every page. What the two implementations sent, on bookshelf.css and logo.svg, depends on the project stage (see the context parameters and what the stage changes):

Neither implementation sent an Expires header in this run. The seven days are the default of both (604800000 milliseconds). They are configurable, with implementation parameters:

Source: Eclipse Mojarra 4.1 context parameters and Apache MyFaces Core 4.1 configuration

The behaviour on an edited file is the one to know in practice. In Development, a changed file was served with new bytes and a new Last-Modified a few seconds later (the container’s own static-file cache holds a file for a short time). In Production the new bytes were served as well, but both implementations kept reporting the Last-Modified of the first request; combined with max-age=604800, a browser does not even ask again within the week. Treat a production resource as immutable and change its URL when its content changes. A browser fetches a file again before its max-age has passed only when the URL is different; the first example of the next section produces such a URL.

The handler is replaceable: the specification’s decorator pattern lets you wrap the existing one. Extend ResourceHandlerWrapper and pass the wrapped handler to the constructor (the no-argument constructor is deprecated), then register the class in faces-config.xml with <resource-handler> inside <application> (the file shown in Localized Resources does so for both examples). The implementation instantiates the class with the handler built so far as the constructor argument.

Both implementations agree on the specified behaviour. The differences found:

Source: Eclipse Mojarra 4.1 context parameters and Apache MyFaces Core 4.1 configuration

Source: Jakarta Faces 4.1 specification, Appendix B (changes between versions) and Jakarta Faces 4.1 API: ResourceHandler

Pro JSF and Ajax (2006) was written for JSF 1.1 and 1.2, which had no resource concept. Its answer to "how does a component library ship its style sheet and script inside a JAR" is the third-party Weblets project: a weblets-config.xml file in the JAR’s META-INF, a servlet-like "weblet" with a name, a class that reads a Java package from the classpath, a URL pattern and a version, and an address syntax of the form weblet://<name>/<path> that a custom view handler rewrites into the real URL and a phase listener serves. Almost every part has a standard replacement:

The book’s XUL and HTC render kits depend on resources of that era (an .htc behaviour file is an Internet Explorer mechanism) and are historical.

Other examples show a wiring that no longer works. The JSF 2.0 Cookbook loads the Ajax script with <h:outputScript name="jsf.js" library="javax.faces" target="head"/>; in Faces 4.x the library is jakarta.faces and the file faces.js (a request for the old names returned 404, see Getting faces.js onto the Page). JavaServer Faces 2.0: The Complete Reference explains the decorator pattern with a ResourceHandlerWrapper and the javax.faces.application imports, and says that the implementation first looks for a public one-argument constructor and falls back to a no-argument one; in 4.1 the no-argument constructor of the wrapper is deprecated and the one-argument constructor is the way (as in the examples above). Its examples of h:outputStylesheet with library and name and of #{resource['style:logo.jpg']} still work unchanged.