Each time the browser renders a page, it will ensure that all resources used by that page are available. During the initial rendering of the page, the browser populates its cache with the contents of each resource URL by downloading a fresh copy from the web server. As it does so, the browser records the Last-Modified and Expires timestamps from the response headers. The cached content is said to have expired if the current time is later than the expiration timestamp, or if no expiration timestamp information exists.

On the next render of the same page, the browser checks to see if the locally cached resource has expired. The locally cached copy is reused if it has not expired. Otherwise, a new request is made to the web server, including the last modified information in the If-Modified-Since request header. The web server responds by either indicating that the browser cache is still up-to-date, or by streaming the new resource contents back to the browser with updated Last-Modified and Expires timestamps in the response headers.

Weblets use versioning to leverage the browser cache behavior so that packaged resources can be downloaded and cached as efficiently as possible. The browser only needs to check for new updates when the cache has been emptied or when the component library has been upgraded at the web server.

The following code sample illustrates the Weblets versioning feature by adding a 1.0 version to our org.myapp.html Weblet.

Code Sample 3. Weblets configuration file using 1.0 versioning for production.

<?xml version="1.0" encoding="UTF-8" ?>
<weblets-config xmlns="http://weblets.dev.java.net/config" >
  <weblet>
    <weblet-name>org.myapp.html</weblet-name>
    <weblet-class>net.java.dev.weblets.packaged.PackagedWeblet</weblet-class>
    <weblet-version>1.0</weblet-version>
    <init-param>
      <param-name>package</param-name>
      <param-value>org.myapp.faces.renderer.html.resources</param-value>
    </init-param>
  </weblet>

  <weblet-mapping>
    <weblet-name>org.myapp.html</weblet-name>
    <url-pattern>/myapp/*</url-pattern>
  </weblet-mapping>
</weblets-config>

During development, the contents of packaged resources can change frequently, so it is important for the browser to keep checking back with the web server to detect the latest resource URL contents. This check happens by default every time the main Web page is rendered if the Weblet version is omitted from weblets-config.xml.

Alternatively the Weblet configuration allows component authors to append -SNAPSHOT to the version number. For example, 1.0-SNAPSHOT, as shown in code sample 4, to indicate that this file is under development and should behave as though the version number has been omitted.

Code Sample 4. Weblets configurations file using SNAPSHOT versioning for development

<?xml version="1.0" encoding="UTF-8" ?>
<weblets-config xmlns="http://weblets.dev.java.net/config" >
  <weblet>
    <weblet-name>org.myapp.html</weblet-name>
    <weblet-class>net.java.dev.weblets.packaged.PackagedWeblet
	</weblet-class>
    <weblet-version>1.0-SNAPSHOT</weblet-version>
    ...
  </weblet>
  ...
</weblets-config>

Weblets Protocol
Having covered how to configure Weblets, it is time to look at how we can reference resources defined by the Weblet in our Renderer. The syntax, defined by the Weblet contract, for returning a proper URL to the JSF page is as follows:

<prefix><weblet name><resource>

The prefix indicates that this is a Weblet-managed resource, and this followed by the Weblet name and the resource requested.

Previously, in our Renderer class we passed the URL /myresources/myScript.js as an argument to the ViewHandler's getResourceURL() method. In the code sample below, we amend this to use the Weblet protocol instead.

Code sample 5. Using Weblet "protocol" to serve up resources

ViewHandler handler = context.getApplication().getViewHandler();
String resourceURL = handler.getResourceURL
(context, "weblet://org.myapp.html/myScript.js");
out.startElement("script", null);
out.writeAttribute("type", "text/javascript", null);
out.writeAttribute("src", resourceURL, null);
out.endElement("script");

The Weblet protocol-like syntax is convenient and easy to understand. The syntax starts with weblet:// followed by the Weblet name e.g. org.myapp.html and finally the path info, or resource file, e.g. /myScript.js. Notice that neither the URL mapping nor the version number are included in the weblet resource syntax. The Weblet URL mapping and version number are used by the WebletsViewHandler to create a resource URL that the Weblet will service.

When the component writer is not using Weblets, then they would not be using the weblet:// resource path syntax, and they would distribute a separate installables zip. When the component writer moves to Weblets, they would start using weblet:// resource path syntax in the Renderer, and include the resources in the JAR. There is no benefit to using a mixture of these approaches for resources in the same version of the same component library.

Using Weblets in a JSF application
In order to simplify setup for the application developer, component writers should select a default URL mapping for their component libraries. There is no need for the application developer to add any Weblet-specific configuration to the web.xml file, since the WebletsPhaseListener will be invoked automatically to service incoming requests for Weblet-managed resources.

Summary
As a new open source project, Weblets has tremendous possibilities to provide a defacto generic and configurable resource loading facility for web clients and the JSF component community. The key differentiators are simplified packaging of JSF components and their resources, and a minimized overhead of installing and setting up JSF component libraries for a particular web application project.

This article has explored a new way of packaging resources with JSF components. You should now be able to leverage Weblets in your own component library by including a suitable weblets-config.xml file and using the weblet:// protocol-style syntax to reference Weblet-managed resources.

In our next article in this series of building Rich Internet Components with JavaServer Faces, we are going to look at how we can design JSF components using AJAX and Weblets.