Loading Resources with Weblets

Loading Resources
with Weblets
If we have learned one thing from the history of invention and discovery, it is that in
the long run—and often in the short one—the most daring prophecies seem laughably
conservative.
—Arthur C. Clarke (1917–), The Exploration of Space, 1951
Web applications often use many different resource files, such as images, style sheets, or
scripts, to improve the presentation and interactivity of the user interface. JSF component
libraries that want to render attractive user interfaces will also leverage resource files.
The standard approach to providing resource files for a JSF component library is to serve
them directly from the Web application root file system. These resources are usually packaged
in an archive (such as a ZIP file) and are shipped separately from the JSF component library.
This chapter will introduce a new open source project—Weblets. The goal of this project
(located at ) is to provide component writers with the ability to
serve resource files from a Java archive (JAR), rather than serving them from the Web applica-
tion root file system. Unlike traditional Web applications, which have statically configured
URL mappings defined in web.xml, JSF applications need dynamically configured URL map-
pings, based on the presence of a component library JAR file.
After reading this chapter, you should understand what weblets are, how resource loading
with weblets works, and how to leverage weblets in your own JSF component library. We will
show how to package the resources for a custom JSF component library to ensure you provide
application developers with an easy way of successfully installing your custom JSF component
library, including any resources needed by your component library.
Introducing Resource Loading
As you may remember from Chapters 2 and 3, we created two components—ProShowOneDeck
and ProInputDate—that need resources served to the client. We will use both components in
this chapter to illustrate how to use weblets.
213
CHAPTER 5
■ ■ ■
5807ch05.qxd 1/13/06 2:56 PM Page 213

For this example, the HtmlShowOneDeckRenderer component uses a JavaScript file,
showOneDeck.js, to expand a UIShowItem when a user clicks the rendered component. As
described in Chapter 3, this JavaScript file is traditionally served by the Web application via a
relative path that is hard-coded into the actual HtmlShowOneDeckRenderer code. This requires
the application developer to deploy additional resources that are delivered and packaged in
a separate archive file (for example, a ZIP file), often referred to as an installables archive.
■
Note
The JSF HTML Basic
RenderKit
does not have any images, styles, or scripts, so no standard solu-
tion exists for the JSF resource-packaging problem.
Code Sample 5-1 shows the encodeResources() method from the HtmlShowOneDeckRenderer
class, which illustrates that the installable JavaScript resource files—/projsf-ch3/showOneDeck.js
and /projsf-ch3/showOneDeck.css—are served from the Web application root file system.
Code Sample 5-1. The encodeResources() Method in the HtmlShowOneDeckRenderer Code
/**
* Write out the ProShowOneDeck resources.
*
* @param context the Faces context
* @param component the Faces component
*/
protected void encodeResources(
FacesContext context,
UIComponent component) throws IOException
{
writeScriptResource(context, "/projsf-ch3/showOneDeck.js");
writeStyleResource(context, "/projsf-ch3/showOneDeck.css");
}
Although the installable approach is convenient for the JSF component writer, it

increases the installation burden on the application developer, who must remember to extract
the installables archive each time the component library is upgraded to a new version. There-
fore, you need a way to package the additional resources into the same JAR file that contains
the Renderer classes, thus simplifying deployment for application developers using your com-
ponent library.
Using Existing Solutions
Some of the more advanced JSF component libraries available today, such as Apache MyFaces
and Oracle ADF Faces, provide a custom servlet or filter solution for serving the resources
needed by their specific renderers. However, each component library tends to solve the same
problem in a slightly different way. The lack of any official standard solution therefore leads to
an additional configuration and installation burden for each component library.
CHAPTER 5
■
LOADING RESOURCES WITH WEBLETS214
5807ch05.qxd 1/13/06 2:56 PM Page 214
Using Weblets
The open source Weblets project aims to solve the resource-packaging problem in a generic
and extensible way so that all JSF component writers can leverage it, and it places no addi-
tional installation burden on the application developer.
A weblet acts as a mediator that intercepts requests from the client and uses short URLs to
serve resources from a JAR file. Unlike the servlet or filter approach, a weblet can be registered
and configured inside a JAR file, so the component library Renderers, their resource files, and
the weblet configuration file (weblets-config.xml) can all be packaged together in the same
JAR file. You do not need to separately deploy additional installables when the component
libraries are upgraded to new versions. For the application developer, no configuration steps
are needed.
It is important to note that all resources served up by weblets are internal resources,
used only by the Renderer. Any resources, such as images, that are provided by the applica-
tion are supplied as component attribute values and loaded from the context root as external
resources.

Exploring the Weblet Architecture
Although weblets were designed to be used by any Web client, the weblet implementation has
been integrated with JSF using a custom ViewHandler, called WebletsViewHandler, as shown in
Figure 5-1. During the rendering of the main JSF page, the WebletsViewHandler is responsible
for converting weblet-specific resource URLs into the actual URLs used by a browser to request
weblet-managed resources.
Figure 5-1. High-level overview of weblet architecture
CHAPTER 5
■
LOADING RESOURCES WITH WEBLETS 215
5807ch05.qxd 1/13/06 2:56 PM Page 215
After receiving the rendered markup for the main page, the browser downloads each
additional resource using a separate request. Each request for a weblet-managed resource is
intercepted by the WebletsPhaseListener, which then asks the WebletContainer to stream the
weblet-managed resource file from the component library JAR file.
The weblet container is designed to leverage the browser cache where possible. This
improves the overall rendering performance by minimizing the total number of requests
made for weblet-managed resource files.
To ensure flexibility, ensure optimization, and avoid collisions with existing web applica-
tion resources, application developers can configure weblets to override any default settings
provided by the component writer.
Using Weblets in Your Component Library
You can configure weblets using a weblets-config.xml file, which must be stored in the
/META-INF directory of the component library JAR file. Configuring a weblet is similar to con-
figuring a servlet or a filter. Each weblet entry in the weblets-config.xml file has a weblet
name, an implementation class, and initialization parameters. The weblet mapping associates
a particular URL pattern with a specific weblet name, such as com.apress.projsf.ch5. The
weblet name and default URL pattern define the public API for the weblet-managed resources
and should not be modified between releases of the component library in order to maintain
backward compatibility.

As shown in Code Sample 5-2, the example component library packages resources in the
com.apress.projsf.ch5.renderer.html.basic.resources Java package and makes them avail-
able to the browser using the default URL mapping of /projsf-ch5/*.
Code Sample 5-2. Weblets Configuration File—weblets-config.xml
<?xml version="1.0" encoding="UTF-8" ?>
<weblets-config xmlns=" >
<weblet>
<weblet-name>com.apress.projsf.ch5</weblet-name>
<weblet-class>
net.java.dev.weblets.packaged.PackagedWeblet
</weblet-class>
<init-param>
<param-name>package</param-name>
<param-value>com.apress.projsf.ch5.render.html.basic.resources</param-value>
</init-param>
</weblet>
<weblet-mapping>
<weblet-name>com.apress.projsf.ch5</weblet-name>
<url-pattern>/projsf-ch5/*</url-pattern>
</weblet-mapping>
</weblets-config>
The PackagedWeblet is a built-in weblet implementation that can read from a particular
Java package using the ClassLoader and then stream the result to the browser. The package
CHAPTER 5
■
LOADING RESOURCES WITH WEBLETS216
5807ch05.qxd 1/13/06 2:56 PM Page 216
initialization parameter tells the PackagedWeblet which Java package to use as a root when
resolving weblet-managed resource requests.
Specifying Weblet MIME Types

When weblets are used to serve a JSF component resource file, it is important that the browser
is correctly informed of the corresponding MIME type so the resource file can be processed
correctly. By default, weblets have built-in knowledge of many common MIME types, such as
text/plain, for common filename extensions, such as .txt. However, in some cases, a JSF
component might need to package resources that either are not previously known by weblets
or must be served using a different extension, preventing weblets from automatically recog-
nizing the correct MIME type to use.
Code Sample 5-3 shows how to define a custom MIME type mapping for resources served
by a weblet.
Code Sample 5-3. Weblets Configuration File Defining a Custom MIME Type
<?xml version="1.0" encoding="UTF-8" ?>
<weblets-config xmlns=" >
<weblet>
<weblet-name>com.apress.projsf.ch5</weblet-name>
<weblet-class>
net.java.dev.weblets.packaged.PackagedWeblet
</weblet-class>
<init-param>
<param-name>package</param-name>
<param-value>com.apress.projsf.ch5.render.html.basic.resources</param-value>
</init-param>
<mime-mapping>
<extension>htc</extension>
<mime-type>text/x-component</mime-type>
</mime-mapping>
</weblet>
<weblet-mapping>
<weblet-name>com.apress.projsf.ch5</weblet-name>
<url-pattern>/projsf-ch5/*</url-pattern>
</weblet-mapping>

</weblets-config>
Code Sample 5-3 defines a custom MIME type mapping of text/x-component for all
resources with the .htc extension served by this weblet.
Specifying Weblet Versioning
Weblets also has built-in support for versioning of the component library. This allows the
browser to cache packaged resources such as showOneDeck.js when possible, preventing
unnecessary round-trips to the web server.
CHAPTER 5
■
LOADING RESOURCES WITH WEBLETS 217
5807ch05.qxd 1/13/06 2:56 PM Page 217