21.5 Packaging and Installing a Tag Library

There are basically two ways the files that make up a tag library (the TLD and all the class files) can be made available to a container: packaged in a JAR file or kept as regular files directly in the web application structure in a WAR file (or the filesystem for most containers). On top of this, there are three ways to identify the tag library you use in a JSP page. Let's look at the topics one at a time.

21.5.1 Making the Tag Library Files Available to the Container

During development, you may want to let the tag library classes and the TLD file reside as is in the filesystem, since it makes it easy to change the TLD and modify and recompile the classes. Just make sure the class files are stored in a directory that's part of the classpath for the JSP container, such as the WEB-INF/classes directory for the web application. The TLD must also be available as a file with a .tld extension in a directory where the JSP container can find it. The recommended location is the WEB-INF/tlds directory.

When you're done with the development, you may want to package all class files and the TLD in a JAR file. This makes it easier to install the library in an application. In this case, the TLD must be placed as a file with a .tld extension in the META-INF directory in the JAR file, for instance as META-INF/taglib.tld. Tag files, if any, must be stored under META-INF/tags, and the TLD must point to the exact location.

To create the JAR file, first arrange the files in a directory with a structure like this:

META-INF/
  taglib.tld
  tags/
    mytags/
      copyright.tag
      forEvenAndOdd.tag
com/
  ora/
    jsp/
      tags/
        AddCookieTag.class
        ...
      util/
        StringFormat.class
        ...

The structure for the class files must match the package names for your classes. I've shown a few of the classes in the tag library for this book as an example.

With the file structure in place, use the jar command to create the JAR file:

jar cvf orataglib_3_0.jar META-INF com

This command creates a JAR file named orataglib_3_0.jar containing the files in the META-INF and com directories. Use any JAR filename that makes sense for your own tag library. Including the version number for the library is also a good idea, because it makes it easy for the users to see which version of the library they are using. The JAR file should be placed in the WEB-INF/lib directory for the application.

21.5.2 Identifying the Tag Library in a JSP Page

To identify the library in JSP pages, you use a taglib directive like this:

<%@ taglib prefix="ora" uri="orataglib" %>

The container uses the uri attribute value to locate the TLD file for the tag library. The value must be either a symbolic name or a file path. A symbolic name is any string that is unique in the application. An HTTP URL is often used to be reasonably sure that it's unique in any application. Even when an HTTP URL is used, the container uses it only as a symbolic name; it does not try to get the resource specified by the URL.

If the uri value is a symbolic name, it must be mapped to the actual location of the TLD file somehow. In JSP 1.2, a new auto-discovery mechanism was introduced to make this very easy. Here's how it works. The TLD includes a <uri> element to define the default URI for the library:

<taglib> 
  ... 
  <uri>orataglib</uri> 
  ... 
</taglib>

When the web application is started, the container scans through the WEB-INF directory structure for files with .tld extensions and all JAR files containing files with .tld extensions in their META-INF directory. In other words, locating all TLD files. For each TLD, the container looks for the <uri> element and creates a map from the URI to the TLD that contains it. In your JSP page, you just have to place a taglib directive with a uri attribute value matching the URI in the TLD.

Prior to JSP 1.2, you had to define the mapping manually in the deployment descriptor for the application (WEB-INF/web.xml):

<web-app>
  ...
  <taglib>
    <taglib-uri>
      orataglib
    </taglib-uri>
    <taglib-location>
      /WEB-INF/lib/orataglib_1_0.jar
    </taglib-location>
  </taglib>
  ...
</web-app>

The <taglib-uri> element contains the symbolic name, and the <taglib-location> element contains the path to either the JAR file or the extracted TLD file.

If the uri attribute value doesn't match a known symbolic name, the container assumes that it's a file path:

<%@ taglib prefix="ora" uri="/WEB-INF/lib/orataglib_3_0.jar" %>

If the path starts with a slash, it's interpreted as a context-relative path, otherwise as a path relative to the JSP page. The file can be either the TLD file itself or a JAR file that includes the TLD file as META-INF/taglib.tld.

With the introduction of the auto-discovery feature in JSP 1.2, there's rarely a reason to use any of the other mechanisms for identifying the tag library. The only reason I can think of is if you're unfortunate enough to be faced with two third-party libraries that have the same default URI specified in their TLD files. To avoid the conflict, you can use one of the explicit mapping types to identify one of the libraries.

21.5.3 Packaging Multiple Libraries in One JAR File

A beneficial side effect of the auto-discovery feature is that you can bundle more than one tag library in the same JAR file. In JSP 1.1, a TLD contained in a JAR file had to be named exactly META-INF/taglib.tld, which meant that a JAR file could contain only one TLD.

The auto-discovery feature, however, treats any file with a .tld extension in a JAR file's META-INF directory as a TLD. You can therefore put multiple TLDs (along with the class files for the libraries) in one JAR file. This makes it easier for your users to deploy related tag libraries. Note that you must use the auto-discovery mechanism to deploy multilibrary JAR files, because there's no way to specify the path to an individual TLD in such a JAR file.^[3]

^[3] You can deliver the TLDs separate from the JAR file and require that they be mapped with <taglib> elements in the application deployment descriptor as well, but that defeats the purpose of making deployment easy.