20.7 Creating the Tag Library Descriptor

Now you have a good idea about what the code for a tag handler looks like. But when the JSP container converts custom action elements into code that creates and calls the correct tag handler, it needs information about which tag handler implements which custom action element. It gets this information from the Tag Library Descriptor (TLD). As you will see in Chapter 21, the JSP container also uses the TLD information to verify that the attribute list for an action element is correct.

The TLD is an XML file with information about all custom actions in one library. A JSP page that uses custom actions must identify the corresponding TLD and the namespace prefix used for the actions in the page with the taglib directive:

<%@ taglib prefix="ora" uri="orataglib" %>
...
<ora:redirect page="main.jsp" />

The uri attribute identifies the TLD, in one of several ways that I describe later in this section. The prefix attribute assigns a prefix to use for the action elements included in the library.

The JSP container then uses the TLD to find the information it needs to generate code for invoking the correct tag handler class when it encounters an action element with a matching prefix.

Example 20-5 shows a part of the JSP 1.2 version of the TLD for the custom actions in this book. Some changes were made to the format of the TLD between JSP 1.1 and 1.2; I describe the differences at the end of this section. A JSP 1.2 container is required to accept a TLD in the JSP 1.1 format as well.

Example 20-5. Tag Library Descriptor (TLD)

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
  PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
  "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
  
<taglib>
  <tlib-version>2.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  <short-name>ora</short-name>
  <uri>orataglib</uri>
  <description>
    A tag library for the examples in the O'Reilly JSP book
  </description>
  
  <tag>
    <name>forward</name>
    <tag-class>com.ora.jsp.tags.ForwardTag</tag-class>
    <body-content>JSP</body-content>
    <description>
      Encodes possible param tags in the body, adds them as a
      query string to the URI defined by the page attribute
      and forwards to the specified page. 
    </description>
    <attribute>
      <name>page</name>
      <required>true</required>
      <rtexprvalue>false</rtexprvalue>
      <description>
        The target URI, as a page- or context-relative path, either
        as a static text value or an EL expression.
      </description>
    </attribute>
  </tag>
  ...
</taglib>

At the top of the TLD file, you find a standard XML declaration and a DOCTYPE declaration, specifying the Document Type Definition (DTD) for this file. A DTD defines the rules for how elements in an XML file must be used, such as the order of the elements, which elements are mandatory and which are optional, if an element can be included multiple times, etc. If you're not familiar with XML, don't worry about this. Just accept the fact that you need to copy the first two elements in Example 20-5 faithfully into your own TLD files. With regards to the order of the elements, just define them in the order in which they are described here. Whether an element is mandatory or optional is also spelled out in the description of each element that follows. If you're curious about the formal DTD, it's available online at http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd.

After the two declarations, the first element in the TLD file must be the <taglib> element. This is the main element for the TLD, enclosing all more specific elements that describe the library as such, as well as each individual tag handler.

20.7.1 General Library Elements

Let's start with the elements that describe the library itself:

• The <tlib-version> element is mandatory and specifies the tag library version. The version should be specified as a series of numbers separated by dots. In other words, the normal conventions for software version numbers, such as 1.1 or 2.0.3, should be used.

• The <jsp-version> element, specifying the version of the JSP specification that the library depends on, is also mandatory.

• The <short-name> element is intended for use by page-authoring tools. It's a mandatory element that should contain the default prefix for the action elements. In Example 20-5, the value is ora, meaning that an authoring tool by default generates custom action elements using the ora prefix, for instance <ora:forward page="main.jsp">. A tool may also use the element value as the value of the prefix attribute if it generates the taglib directive in the JSP page. The element value must not include whitespace characters or other special characters, or start with a digit or underscore.

• The <uri> element value can be used as the default for the uri attribute in a taglib directive generated by an authoring tool. It's an optional element, following the same character rules as the <shortname> element. While the element is optional according to the DTD, it's required for the auto-discovery feature for tag libraries introduced in JSP 1.2. More about this feature later, but because of this, I recommend you always include this element.

• The <display-name> element is an optional element, containing a name of the library suitable for display by an authoring tool.

• A <small-icon> and <large-icon> element can optionally be used to name image files containing icons for the library, again something a page-authoring tool may use. The values are file paths for files containing either GIF or JPEG images, interpreted as relative to the TLD file. The small icon should be 16 by 16 pixels, and the large 32 by 32 pixels.

• The last element that describes the library as such is the optional <description> element. It can provide a short description of the library, perhaps something a tool may display to help users decide if the library is what they are looking for.

20.7.2 Validator and Listener Elements

Next comes an optional <validator> element, with nested <validator-class>, <init-param>, and <description> elements. I describe how to use these elements in Chapter 21.

Another optional element is the <listener> element, with a mandatory <listener-class> element. These elements are also described in detail in Chapter 21.

20.7.3 Tag Elements

Besides these general elements, the TLD must include at least one <tag> element. The <tag> element contains other elements that describe different aspects of the custom action. In order, they are <name>, <tag-class>, <tei-class>, <body-content>, <display-name>, <small-icon>, <large-icon>, <description>, <variable>, <attribute>, and <example>.

20.7.3.1 General tag elements

The <name> element is mandatory and contains the name for the corresponding custom action element in the JSP pages. It must be a name that is unique within the tag library.

The <tag-class> element, also mandatory, contains the fully qualified class name for the tag handler class.

For some actions that introduce variables or do special syntax validation as described in Chapter 21, a TagExtraInfo subclass is needed in addition to the tag handler class. The optional <tei-class> element specifies the fully qualified class name for the TagExtraInfo subclass. In JSP 1.2, this class is rarely used.

Another optional element is <body-content>. It can contain one of three values. A value of empty means that the action body must be empty. If the body can contain JSP elements, such as standard or custom actions or scripting elements, the JSP value should be used. All JSP elements in the body are processed and the result is handled as specified by the tag handler (processed by the tag handler or sent through to the response body). This is also the default value, in case you omit the <body-content> element. The third alternative is tagdependent; this value means that possible JSP elements in the body aren't processed. Typically, this value is used when the body is processed by the tag handler, and the content may contain characters that could be confused with JSP elements, such as:

SELECT * FROM MyTable WHERE Name LIKE '<%>'. 

If a tag that expects this kind of body content is declared as JSP, the <%> is likely to confuse the JSP container. The tagdependent value can avoid this risk for confusion, but note that it also disables the processing of valid JSP elements.

The <display-name>, <small-icon>, <large-icon>, and <description> elements are all optional, used in the same way as for the library itself.

20.7.3.2 Variable elements

The <variable> element, with its nested <name-given>, <name-from-attribute>, <variable-class>, <declare>, <scope>, and <description> elements, can provide information about variables a custom action exposes as scripting variables. I describe this in detail in Chapter 21.

20.7.3.3 Attribute elements

The <tag> element must also contain an <attribute> element for each action attribute. Each <attribute> element in turn contains nested elements that describe the attribute: <name>, <required>, <rtexprvalue>, <type> and <description>:

• The mandatory <name> element specifies the attribute name.

• The optional <required> element tells if the attribute is required or not. The values true, false, yes, and no are valid, with false being the default.

• The <rtexprvalue> element is an optional element that can have the same values as the <required> element. If it's true or yes, a request-time expression can specify the attribute value, for instance:

  attr='<%= request.getParameter("par") %>' 

  (see Chapter 15 for details). The default value is false.

• The optional <type> element can specify the attribute's Java type for attributes that allow a request-time expression as its value. The value must be the fully qualified name of the Java class or interface for the corresponding setter method in the tag handler class. This element is intended to be used only by authoring tools and documentation generating tools in JSP 1.2; the container doesn't have to use it, but may report an error if the specified type doesn't match the type of the attribute in the tag handler class.

• The <description> element can describe the purpose and use of the attribute, the same as for all other places where this element may appear in the TLD.

20.7.3.4 Example element

The final subelement for the <tag> element is the optional <example> element. As the name implies, it can provide an example of how the custom action can be used. This information can then be used by tools to either display it as part of a tool tip for the action or to include it in automatically generated documentation.

20.7.4 Differences Between a JSP 1.1 and a JSP 1.2 TLD

If you're updating a JSP 1.1 tag library to take advantage of the new JSP 1.2 features, you may also want to convert the JSP 1.1 TLD to the new JSP 1.2 format. A JSP 1.2 container is required to accept a TLD in the JSP 1.1 format as well, but you may still want to use the new format. For instance, in most cases you can replace your TagExtraInfo subclasses and instead use the new <variable> element to declare the variables exposed by the action (described in Chapter 21).

Most of the differences are name changes for some elements for consistency with the naming conventions used in other J2EE descriptor files. More precisely, hyphens are now used to separate words in element names, and the <info> element has been replaced with the <description> element that is used for the same purpose in other descriptors. The following table summarizes these name changes:

JSP 1.1	JSP 1.2
<tlibversion>	<tlib-version>
<jspversion>	<jsp-version>
<shortname>	<short-name>
<info>	<description>
<tagclass>	<tag-class>
<teiclass>	<tei-class>
<bodycontent>	<body-content>

A number of new elements have also been added to allow more descriptive information in the TLD. This information may be used by page-authoring tools and also by tools that generate user documentation from the TLD: <display-name>, <small-icon>, <large-icon>, <example>, <type>, and <variable>. How to use these new elements is described earlier in this section.