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>

By specifying a weblet version, you indicate that the packaged resource is not going to change until the version number changes. Therefore, the version number is included as part of the resource URL determined at runtime by the WebletsViewHandler e.g. /myresources$1.0/myScript.js. When the WebletContainer services this request, it extracts the version number from the URL and determines that the resource should be cached, and never expire. As soon as a new version of the component library is deployed to the web application, the resource URL created at runtime by the WebletsViewHandler changes e.g. /myresources$2.0/myScript.js, thus the browser's cached copy of myScript.js for version 1.0 is no longer valid because the URL is different.

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>

Security
When serving packaged resources from a JAR, extra care must be taken not to make Java Class files or other sensitive information accessible by URL. In desktop Java applications, resource files are often stored in a sub-package called "resources" underneath the Java implementation classes that use the resource files. The same strategy is also appropriate for packaged resources in JavaServer Faces component libraries, and has the security benefit of ensuring that only the resource files are accessible by URL. All other contents of the JAR file, including Java implementation classes, are not URL accessible because no Java classes exist in either the "resources" package, or in any sub-package of "resources."

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.

• AjaxWorld Special: Creating AJAX and Rich Internet Components with JSF