JSF 2.0 New Feature Preview Series (Part 2.1): Resources

This is the second blog in the JSF 2.0 New Feature Preview Series. 
The previous entry covered ProjectStage, now we'll cover Resources.
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.

The term Resources is pretty vague, so let's clarify that first.  Resources are any
artifacts that a component may need in order to be rendered properly to
a user-agent.  So think images, CSS, or JavaScript files. 

Previous versions of JSF had no facility for serving resources, so component
libraries either had to cook up their own mechanism for serving resources
or use something like Weblets so that these resources could be packaged
with their component library.

JSF 2.0 will have support for this functionality out of the box which should
make life easier for custom component developers.


The default implementation will look for resources in two locations
and in the following order:

  1. /resources  this location represents resources in the webapp itself
    and if present, must be in the root of the web application
  2. /META-INF/resources this location represents resources on the

First question that may come to mind is why care about resources in the
docroot of the web application?  Don't worry, that will be touched on soon.

The spec further supplies some options for how to structure content under
these resources directories.  This specification looks like this:

  • [localePrefix/][libraryName/][libraryVersion/]resourceName[/resourceVersion]
    items in [] are optional

Let's break these elements down starting with localePrefix.  This allows the developer
to associate a resource with a particular locale identifiter.  If a developer wishes to
leverage this feature, they must add a key/value pair like:
  • javax.faces.resource.localePrefix=<localePrefix>

The value of localePrefix must match the localePrefix within the resources directory.

Next in the path is libraryName.  This is a logical identifier that may be used to represent
a grouping of resources.  This library may be versioned as indicated by libraryVersion.
Finally we we have resourceName.  This is the name of the physical resource (i.e. mast.jpg
or corp.css or js/ajax.js), which can also be versioned.  

Let's take a closer look at versioning.  Version strings are pretty open ended.  They may be 1_1,  1_1_1, 1_1_2_11 (NOTE the _ for the version delimiter), etc., and if used, the resource handling mechanism must use the latest version available (be it library or resource).  This allows you to update resources at runtime without having to redeploy the application.  

The ability to update resources at runtime touches back on looking for resources within
the docroot of the web application.  Consider the following scenario.  An application
uses a component library with resources included within the JAR, for argument's sake,
let's say that the resource path is /META-INF/resources/compLib/script/compScript.js
A bug is found in this .js file and no new version of the component library is available. 
The bug can be fixed locally and placed in /resources/compLib/1.1/script/compScript.js
while the app is live and the new version will be sent to the client.

The last item I wanted to mention with respect to resource (not library) versioning as,
at first blush, it's a bit strange.  The name of the resource is actually the directory,
and the version is the resource content itself.   As an example:  META-INF/resources/compLib/compScript.js/1_1
or META-INF/resources/compLib/compScript.js/1_1.js (developers can optionally include the extension of the file).

The next blog entry will get into the details of the API, but I want to mention it here
as I feel it's important.  From an API persective, the versioning and localePrefix features
are transparent in the API.  This means when leveraging the API, the only info that is
needed is a library name (if any), and the resource name.  The resource system takes
care of the localePrefix and version resolution automatically.

UPDATED Jan 28, 2009 - updated information pertaining to resource/library versions.


Hi Ryan while I applaud the efforts that JSF finally has a dedicated resource loading, and I also must say, you guys definitely have followed the right path to solve the problem structurewise,
I personally would have loved to see such an implementation done on a lower level than JSF and JSF utilizing the lower base mechanisms! The current implementation seems to be jsf only.

Posted by Werner Punz on February 21, 2008 at 04:49 PM PST #

Yeah, it's about time. Lack of resource handling has got to be the most annoying part of integrating JSF component libraries. Put this as a top priority.

Posted by Dan Allen on May 12, 2008 at 05:37 AM PDT #

Feature is implemented in the SVN head as documented here, so it's ready to go. Feel free to test.

Posted by guest on May 12, 2008 at 11:36 AM PDT #

[Trackback] We all know that Ryan Lubke is a top notch engineer, but did you also know he's a solid technical writer? Ryan has been posting plenty of really useful content on his blog about JSF 2.0, including the series on new features in JSF 2.0. This entry summ...

Posted by Ed Burns's Blog on June 26, 2008 at 07:00 AM PDT #

Hi Ryan,

Looking for your expertise in New Zealand...could you send me phone numbers and times where I might call??

Posted by Cris on September 06, 2008 at 09:54 AM PDT #


Posted by Chulwon Choe on December 09, 2008 at 12:15 PM PST #


Posted by guest on January 01, 2009 at 05:18 PM PST #

Hi Ryan,

I am curious why this mechanism is so dynamic when it comes to version numbers, but it is curiously incompetent when it comes to locale resources. Suppose I have


What I'd like to achieve is that image1.png is picked according to locale but image2.png is used for all locales.

First off, I have to go through the bother of creating mappings such as


in a message bundle, and I have to update the dreaded faces-config.xml and declare that message bundle.

And then I find that the algorithm described in rigidly looks up the value of that key and wants to use it for all resources.

Do you know of a rationale for this? Why don't you just use the same lookup sequence that ResourceBundle would use? (E.g. de_CH/de/default)

Posted by Cay Horstmann on April 27, 2009 at 04:33 AM PDT #

Post a Comment:
Comments are closed for this entry.



« July 2016