JSF 2.2 [usage pitfall] - Resource library meaning

As you probably know, JSF supports dedicated tags for loading resources, such as <h:outputStylesheet> for CSS resources, <h:outputScript> for JavaScript resources and <h:graphicImage> for images. These tags support an attribute named, library. The official documentation is pretty skimped about what the value of this attribute should be: The library name for this resource. Since this is all we have, there are plenty of examples like below:

<h:outputStylesheet library="css" name="style.css" />

<h:outputScript library="js" name="script.js" />

<h:graphicImage library="img" name="image.png" />

Now, the above snippet can be re-written as:

<h:outputStylesheet name="css/style.css" />

<h:outputScript name="js/script.js" />

<h:graphicImage name="img/image.png" />

Both approaches will generate almost the same HTML code. In the first approach, the library name will be rendered as a request parameter, ln=library_name, while in the second approach, the library name will be embed in the resource path as, ...javax.faces.resource/library_name/...

 So, if the generated HTML is almost the same, and in the first approach the library value simply repeats what the tag name already indicates, then how is library useful ?

We can answer to this question by checking some real world examples:

<h:outputScript library="javax.faces" name="jsf.js" />

<h:outputScript library="primefaces" name="jquery/jquery.js" />

<h:outputScript library="omnifaces" name="omnifaces.js" />

<h:outputStylesheet library="primefaces-vader" name="theme.css" />

Notice that the library value represents the common library/module/theme name where all of those resources commonly belong to. This is the correct usage that brings us several advantages:

·         Distinguish where those resources belong to and/or are coming from.

·         In custom ResourceHandlers, you can also apply more finer grained control over resources.

·         You can apply resource library versioning the right way on resources provided by your own webapp

Each of these advantages are detailed by Bauke Scholtz (aka BalusC) at What is the JSF resource library for and how should it be used?.

So, as a conclusion, if your application doesn't need a library then just omit it (e.g. some personal applications). Nevertheless, if you decide to use a library name, but you don't have a clear purpose, then a name as default or common, or your company name may be a good choice.