This is the third blog in the JSF 2.0 New Feature Preview Series. The previous entry covered packaging of resources. Now we'll cover the APIs that back this feature. Keep in mind that none of the features described are final, and may change, but this is a good opportunity to show the features as they exist now and illicit feedback.
Two new API classes that are available for Resource handling:
- javax.faces.application.ResourceHandler 
- javax.faces.application.Resource 
The Resource class is pretty straight forward. This class is basically a representation of an actual resource such as an image or style sheet. It also provides methods to help the ResourceHandler serve the underlying resource.
The ResourceHandler class is responsible for both creating Resource instances as well as serving said resources to the user-agent.
So how does a developer leverage these classes? Well, in general, a developer will obtain the ResourceHandler (FacesContext.getApplication().getResourceHandler()) and create one or more Resource instances (ResourceHandler.createResource()). Then the Resource can be encoded Resource.getRequestPath()) that will generate a special URI for serving it.
For example, let's say a Renderer is writing out an HTML img tag. The result of calling Resource.getRequestPath() will be the value of the img tag's src attribute, and when rendered to the browser would look something like:
<img src="<context-root>/javax.faces.resource/<resource-name> + [?ln=<library-name>][&loc=<locale-prefix>][&v=<version>]
Let's break this down. As per the previous blog regarding packaging, there are several bits of meta-data associated with a Resource. These are its library name, locale, and version (all optional). If a Resource has any of these, they will be encoded in the URI. If any of the values change, such as the locale prefix or a version increment, the change will be present in the URI and because the URI differs the user-agent will request the new resource automatically.
One might be wondering how the resources are served. Past attempts as resolving this issue have used a PhaseListener, or a Filter, but the neither are used in this case. The solution, to avoid having to specify additional artifacts in the faces-config or web.xml, is to have the FacesServlet leverage the ResourceHandler directly. Specifically, the FacesServlet will, on each request, ask the ResourceHandler (by invoking ResourceHandler.isResourceRequest()), if the current request is a Resource Request
(i.e. the request URI contains the identifier /javax.faces.resource), and if it is determined to be a Resource Request, the FacesServlet will call handleResourceRequest() on the ResourceHandler to serve the resource. If the request is not a Resource Request, the standard JSF lifecycle processing will occur.
It should be noted that when serving resources, the ResourceHandler will ask the Resource instance if the user-agent requires updating, so that if the resource hasn't changed, a 304 can simply be returned to reduce the load of the network.
Also, the behavior of Mojarra's implementation of ResourceHandler will differ depending on the current value for ProjectStage. If the current stage is Development, any request to the ResourceHandler to create a Resource will result in the system computing the paths and searching for the resource. Since this process is expensive, Mojarra will, when the ProjectStage is Production, cache the resource meta-data to lessen the load on the system. By default changes will be checked for every five minutes and if changes are found, the cache is dumped so that it will be rebuilt with the new changes that are present. I wanted to point out that when developing a project and you want to see any resource additions picked up right away make sure you've set the ProjectStage for Development.
Finally, like other artifacts within JSF, if the default implementation doesn't suit your needs, you can completely replace or decorate the implementation with functionality that meets your requirements.