11.1. Using the New Tag Library Descriptor Format

Tag libraries that make use of any new JSP 1.2 capabilities must use a new format for their tag library descriptor (TLD) files. However, libraries that are compatible with JSP 1.1 are allowed to use the JSP 1.1 TLD format.

TLD files in JSP 1.2 differ in the following ways from JSP 1.1 TLD files:

• The DOCTYPE declaration has changed.

• Several elements have been renamed.

• New elements have been added.

Each of these changes is described in one of the following subsections. The final subsection gives a side-by-side comparison of the JSP 1.2 and 1.1 TLD file formats.

New DOCTYPE Declaration

Tag library descriptor files start with an XML header, then have a DOCTYPE declaration and a taglib element. The XML header is unchanged from JSP 1.1 to 1.2, but for the DOCTYPE declaration, you now use:

<!DOCTYPE taglib 
 PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" 
 "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd"> 

In JSP 1.1 you used:

<!DOCTYPE taglib 
 PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN" 
 "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd"> 

Listing 11.1 briefly outlines the resultant file.

Listing 11.1. JSP 1.2 TLD File (Excerpt 1)

<?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> 
  <!-- ... --> 
</taglib> 

Renamed Elements

Within the taglib element in JSP 1.2, dashes were added to the tlibversion, jspversion, and shortname elements, yielding tlib-version, jsp-version, and short-name, respectively. The tlib-version element indicates the version number of the tag library (an arbitrary number), jsp-version indicates the JSP version needed (1.2), and short-name defines a name that IDEs can use to refer to the library (no spaces are allowed because IDEs might use short-name as the default tag prefix). The JSP 1.1 info element (used for documentation) was renamed to description.

Within the tag element, dashes were added to tagclass, teiclass, and bodycontent elements, yielding tag-class, tei-class, and body-content, respectively. The tag-class element gives the fully qualified name of the tag implementation class, tei-class defines a TagExtraInfo class for validation (this is optional; see Section 11.3 for a new and better alternative), and bodycontent provides IDEs a hint as to whether the tag is empty (i.e., uses no separate end tag) or uses a tag body between its start and end tags. The JSP 1.1 info element (used for documentation) was renamed to description.

Listing 11.2 gives a brief outline of a typical TLD file. Remember that the order of elements within XML files is not arbitrary. You must use the elements in the order shown here.

Listing 11.2. JSP 1.2 TLD File (Excerpt 2)

<?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>some-number</tlib-version> 
  <jsp-version>1.2</jsp-version> 
  <short-name>some-name</short-name> 
  <description>Tag library documentation.</description> 

  <tag> 
    <name>tag-name</name> 
    <tag-class>somePackage.SomeTag</tag-class> 
    <body-content>empty, JSP, or tagdependent</body-content> 
    <description>Tag documentation.</description> 
  </tag> 

  <!-- Other tag elements, if any. --> 
</taglib> 

New Elements

Within the taglib element, five new elements were added: display-name, small-icon, large-icon, validator, and listener. All are optional.

The first three of these supply information for IDEs and other authoring tools. If used, they must appear in the order listed here and must be placed immediately before the description element within taglib. The display-name element gives a short name that the IDEs can present to the author; it differs from short-name in that it can contain white space (short-name cannot) and is used only for identification, not as a preferred prefix in a taglib directive (as short-name could be). The small-icon element gives the location of a 16 × 16 GIF or JPEG image that can be used by the IDE. The large-icon element gives the location of a 32 × 32 image, also in GIF or JPEG format.

The validator element declares a TagLibraryValidator class to be used for page translation-time syntax checking. Its use is discussed in Section 11.3. This element, if used, must appear in the taglib element after description but before listener (if used) and tag.

The listener element declares an application life-cycle event listener that will be loaded when the Web application is loaded (not when the tag library is first used!). Use of the listener element is discussed in Section 11.2; use of life-cycle listeners in general is described in Chapter 10. The listener element, if used, must be the last element before tag.

There were also five new elements that can appear within the tag element: display-name, small-icon, large-icon, variable, and example. All are optional. The first three (display-name, small-icon, and large-icon) are used for IDE documentation in the same way as just described for the taglib element. The elements, if used, must appear after body-content but before description. The variable element is used to introduce scripting variables. It must appear after description but before attribute; its use is described in Section 11.8. Finally, the example element gives a simple textual example of the use of the tag. If used, the example element must be the last subelement within tag.

Summary

Table 11.1 summarizes the first-, second-, and third-level elements in tag library descriptor files, listed in the order in which they must be used. Items in bold indicate changes from JSP 1.1. Elements marked with an asterisk are optional.

<?xml version="1.0" 
      encoding="ISO-8859-1" ?> 

<?xml version="1.0" 
      encoding="ISO-8859-1" ?> 

taglib 

  tlib-version
											jsp-version
											short-name 

  uri* 

  display-name* 

  small-icon* 

  large-icon* 

  description* 

  validator* 
    validator-class
											init-param* 
    description*

taglib 

  tlibversion 

  jspversion 

  shortname 

  uri* 







  info* 

											listener* 
    listener-class 

  tag 
    name 
    tag-class
											tei-class* 
    body-content* 
    display-name* 
    small-icon* 
    large-icon* 
    description* 
    variable* 
    attribute* 
    example*

  tag 
    name 
    tagclass 
    teiclass* 
    bodycontent* 



    info* 

    attribute*