Declaring a Custom Tag Library

In order for the JSP container to use actions from a tag library, it must be able to do two things: recognize that an element represents a custom action from a specific library, and find the Java class or tag file that implements the custom action logic.

The first requirement—figuring out which library an action belongs to—is satisfied by the taglib directive's prefix attribute; all elements in the page that use the specified prefix belong to this custom tag library. A custom tag library defines a default prefix, used in the library's documentation and possibly by page-authoring tools that insert custom action elements in a page. You can, however, use any prefix you like except jsp, jspx, java, javax, servlet, sun, or sunw (those are reserved by the JSP specification).

The uri attribute satisfies the second requirement: finding the class or tag file for each custom action. The attribute contains a string the container uses to locate the TLD for the library, where it finds the Java class or tag file names for all actions in the library. The value can identify the TLD file in a number of ways, but if you use a container that implements the 1.2 (or later) version of the JSP specification, there's really just one way that you need to care about: use the default URI for the library. The default URI is included in the TLD and should also be part of the documentation for the library. It's orataglib for the custom tag library described in this book.

When the web application is started, the container scans through the WEB-INF directory structure for files with .tld extensions (the mandatory extension for a TLD file) and all JAR files containing files with .tld extensions in their META-INF directory. In other words, the container locates all TLD files. For each TLD, the container gets the library's default URI from the TLD and creates a map from the URI to the TLD that contains it. In your JSP page, you just have to use a taglib directive with a uri attribute value that matches the default URI.

For this to work in an environment where custom tag libraries can come from multiple vendors as well as from in-house staff, the default URI value must be a globally unique string. A common convention is to use an HTTP URL, such as http://ora.com/jsptags. This is one way to be reasonably sure that the value is unique, and it's the choice made for all JSTL tag library URIs. Note that the URL doesn't have to refer to an existing web page; it's just an identifier, and the container doesn't try to access it over the Internet. Others prefer a shorter string, such as orataglib or com.ora.jsptags. This works equally well as long as the strings are unique in the application.

With the URI and the prefix for the library defined, the container has all it needs to find the custom action implementation. As shown in Figure, when the container finds an element with a prefix matching a prefix defined by a taglib directive, it uses the uri attribute value to locate the TLD. In the TLD, it finds a mapping between the action element name and the class or tag file implementation.

Relation between the taglib directive, the TLD, and the implementation (tag handler) for the custom actions

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

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