Tag Library Descriptors - The J2EE 1.4 Tutorial

Tag Library Descriptors

If you want to redistribute your tag files or implement your custom tags with tag handlers written in Java, you must declare the tags in a tag library descriptor (TLD). A tag library descriptor is an XML document that contains information about a library as a whole and about each tag contained in the library. TLDs are used by a web container to validate the tags and by JSP page development tools.

Tag library descriptor file names must have the extension .tld and must be packaged in the /WEB-INF/ directory or subdirectory of the WAR file or in the /META-INF/ directory or subdirectory of a tag library packaged in a JAR. If a tag is implemented as a tag file and is packaged in /WEB-INF/tags/ or a subdirectory, a TLD will be generated automatically by the web container, though you can provide one if you wish.

A TLD must begin with a root taglib element that specifies the schema and required JSP version:

<taglib xmlns="http://java.sun.com/xml/ns/j2ee" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-
jsptaglibrary_2_0.xsd" 
  version="2.0">  

Table 15-6 lists the subelements of the taglib element.

Table 15-6 taglib Subelements 

Element	Description
description	(optional) A string describing the use of the tag library.
display-name	(optional) Name intended to be displayed by tools.
icon	(optional) Icon that can be used by tools.
tlib-version	The tag library's version.
short-name	(optional) Name that could be used by a JSP page-authoring tool to create names with a mnemonic value.
uri	A URI that uniquely identifies the tag library.
validator	See validator Element .
listener	See listener Element .
tag-file | tag	Declares the tag files or tags defined in the tag library. See Declaring Tag Files  and Declaring Tag Handlers. A tag library is considered invalid if a tag-file element has a name subelement with the same content as a name subelement in a tag element.
function	Zero or more EL functions (see Functions) defined in the tag library.
tag-extension	(optional) Extensions that provide extra information about the tag library for tools.

Top-Level Tag Library Descriptor Elements

This section describes some top-level TLD elements. Subsequent sections describe how to declare tags defined in tag files, how to declare tags defined in tag handlers, and how to declare tag attributes and variables.

validator Element

This element defines an optional tag library validator that can be used to validate the conformance of any JSP page importing this tag library to its requirements. Table 15-7 lists the subelements of the validator element.

Table 15-7 validator Subelements 

Element	Description
validator-class	The class implementing javax.servlet.jsp.tagext.TagLibraryValidator
init-param	(optional) Initialization parameters

listener Element

A tag library can specify some classes that are event listeners (see Handling Servlet Life-Cycle Events). The listeners are listed in the TLD as listener elements, and the web container will instantiate the listener classes and register them in a way analogous to that of listeners defined at the WAR level. Unlike WAR-level listeners, the order in which the tag library listeners are registered is undefined. The only subelement of the listener element is the listener-class element, which must contain the fully qualified name of the listener class.

Declaring Tag Files

Although not required for tag files, providing a TLD allows you to share the tag across more than one tag library and lets you import the tag library using a URI instead of the tagdir attribute.

tag-file TLD Element

A tag file is declared in the TLD using a tag-file element. Its subelements are listed in Table 15-8.

Table 15-8 tag-file Subelements 

Element	Description
description	(optional) A description of the tag.
display-name	(optional) Name intended to be displayed by tools.
icon	(optional) Icon that can be used by tools.
name	The unique tag name.
path	Where to find the tag file implementing this tag, relative to the root of the web application or the root of the JAR file for a tag library packaged in a JAR. This must begin with /WEB-INF/tags/ if the tag file resides in the WAR, or /META-INF/tags/ if the tag file resides in a JAR.
example	(optional) Informal description of an example use of the tag.
tag-extension	(optional) Extensions that provide extra information about the tag for tools.

Unpackaged Tag Files

Tag files placed in a subdirectory of /WEB-INF/tags/ do not require a TLD file and don't have to be packaged. Thus, to create reusable JSP code, you simply create a new tag file and place the code inside it.

The web container generates an implicit tag library for each directory under and including /WEB-INF/tags/. There are no special relationships between subdirectories; they are allowed simply for organizational purposes. For example, the following web application contains three tag libraries:

/WEB-INF/tags/
/WEB-INF/tags/a.tag
/WEB-INF/tags/b.tag
/WEB-INF/tags/foo/
/WEB-INF/tags/foo/c.tag
/WEB-INF/tags/bar/baz/
/WEB-INF/tags/bar/baz/d.tag 

The implicit TLD for each library has the following values:

tlib-version for the tag library. Defaults to 1.0.
short-name is derived from the directory name. If the directory is /WEB-INF/tags/, the short name is simply tags. Otherwise, the full directory path (relative to the web application) is taken, minus the /WEB-INF/tags/ prefix. Then all / characters are replaced with -(hyphen), which yields the short name. Note that short names are not guaranteed to be unique.
A tag-file element is considered to exist for each tag file, with the following subelements:
The name for each is the filename of the tag file, without the .tag extension.
The path for each is the path of the tag file, relative to the root of the web application.

So, for the example, the implicit TLD for the /WEB-INF/tags/bar/baz/ directory would be as follows:

<taglib>
  <tlib-version>1.0</tlib-version>
  <short-name>bar-baz</short-name>
  <tag-file>
    <name>d</name>
    <path>/WEB-INF/tags/bar/baz/d.tag</path>
  </tag-file>
</taglib> 

Despite the existence of an implicit tag library, a TLD in the web application can still create additional tags from the same tag files. To accomplish this, you add a tag-file element with a path that points to the tag file.

Packaged Tag Files

Tag files can be packaged in the /META-INF/tags/ directory in a JAR file installed in the /WEB-INF/lib/ directory of the web application. Tags placed here are typically part of a reusable library of tags that can be used easily in any web application.

Tag files bundled in a JAR require a tag library descriptor. Tag files that appear in a JAR but are not defined in a TLD are ignored by the web container.

When used in a JAR file, the path subelement of the tag-file element specifies the full path of the tag file from the root of the JAR. Therefore, it must always begin with /META-INF/tags/.

Tag files can also be compiled into Java classes and bundled as a tag library. This is useful when you wish to distribute a binary version of the tag library without the original source. If you choose this form of packaging, you must use a tool that produces portable JSP code that uses only standard APIs.

Declaring Tag Handlers

When tags are implemented with tag handlers written in Java, each tag in the library must be declared in the TLD with a tag element. The tag element contains the tag name, the class of its tag handler, information on the tag's attributes, and information on the variables created by the tag (see Tags That Define Variables).

Each attribute declaration contains an indication of whether the attribute is required, whether its value can be determined by request-time expressions, the type of the attribute, and whether the attribute is a fragment. Variable information can be given directly in the TLD or through a tag extra info class. Table 15-9 lists the subelements of the tag element.

Table 15-9 tag Subelements 

Element	Description
description	(optional) A description of the tag.
display-name	(optional) name intended to be displayed by tools.
icon	(optional) Icon that can be used by tools.
name	The unique tag name.
tag-class	The fully qualified name of the tag handler class.
tei-class	(optional) Subclass of javax.servlet.jsp.tagext.TagExtraInfo. See Declaring Tag Variables for Tag Handlers.
body-content	The body content type. See body-content Element .
variable	(optional) Declares an EL variable exposed by the tag to the calling page. See Declaring Tag Variables for Tag Handlers.
attribute	Declares an attribute of the custom tag. See Declaring Tag Attributes for Tag Handlers.
dynamic-attributes	Whether the tag supports additional attributes with dynamic names. Defaults to false. If true, the tag handler class must implement the javax.servlet.jsp.tagext.DynamicAttributes interface.
example	(optional) Informal description of an example use of the tag.
tag-extension	(optional) Extensions that provide extra information about the tag for tools.

body-content Element

You specify the type of body that is valid for a tag by using the body-content element. This element is used by the web container to validate that a tag invocation has the correct body syntax and is used by page-composition tools to assist the page author in providing a valid tag body. There are three possible values:

tagdependent: The body of the tag is interpreted by the tag implementation itself, and is most likely in a different language, for example, embedded SQL statements.
empty: The body must be empty.
scriptless: The body accepts only static text, EL expressions, and custom tags. No scripting elements are allowed.

Declaring Tag Attributes for Tag Handlers

For each tag attribute, you must specify whether the attribute is required, whether the value can be determined by an expression, the type of the attribute in an attribute element (optional), and whether the attribute is a fragment. If the rtexprvalue element is true or yes, then the type element defines the return type expected from any expression specified as the value of the attribute. For static values, the type is always java.lang.String. An attribute is specified in a TLD in an attribute element. Table 15-10 lists the subelements of the attribute element.

Table 15-10 attribute Subelements 

Element	Description
description	(optional) A description of the attribute.
name	The unique name of the attribute being declared. A translation error results if more than one attribute element appears in the same tag with the same name.
required	(optional) Whether the attribute is required. The default is false.
rtexprvalue	(optional) Whether the attribute's value can be dynamically calculated at runtime by an EL expression. The default is false.
type	(optional) The runtime type of the attribute's value. Defaults to java.lang.String if not specified.
fragment	(optional) Whether this attribute is a fragment to be evaluated by the tag handler (true) or a normal attribute to be evaluated by the container before being passed to the tag handler.   If this attribute is true: You do not specify the rtexprvalue attribute. The container fixes the rtexprvalue attribute at true. You do not specify the type attribute. The container fixes the type attribute at javax.servlet.jsp.tagext.JspFragment.   Defaults to false.

If a tag attribute is not required, a tag handler should provide a default value.

The tag element for a tag that outputs its body if a test evaluates to true declares that the test attribute is required and that its value can be set by a runtime expression.

<tag>
  <name>present</name>
     <tag-class>condpkg.IfSimpleTag</tag-class>
  <body-content>scriptless</body-content>
  ...
  <attribute>
    <name>test</name>
    <required>true</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>
  ...
</tag> 

Declaring Tag Variables for Tag Handlers

The example described in Tags That Define Variables defines an EL variable departmentName:

  <tlt:iterator var="departmentName" type="java.lang.String"
      group="${myorg.departmentNames}">
    <tr>
      <td><a href="list.jsp?deptName=${departmentName}">
        ${departmentName}</a></td>
    </tr>
  </tlt:iterator> 

When the JSP page containing this tag is translated, the web container generates code to synchronize the variable with the object referenced by the variable. To generate the code, the web container requires certain information about the variable:

Variable name
Variable class
Whether the variable refers to a new or an existing object
The availability of the variable

There are two ways to provide this information: by specifying the variable TLD subelement or by defining a tag extra info class and including the tei-class element in the TLD (see TagExtraInfo Class). Using the variable element is simpler but less dynamic. With the variable element, the only aspect of the variable that you can specify at runtime is its name (via the name-from-attribute element). If you provide this information in a tag extra info class, you can also specify the type of the variable at runtime.

Table 15-11 lists the subelements of the variable element.

Table 15-11 variable Subelements 

Element	Description
description	(optional) A description of the variable.
name-given | name-from-attribute	Defines an EL variable to be used in the page invoking this tag. Either name-given or name-from-attribute must be specified. If name-given is specified, the value is the name of the variable. If name-from-attribute is specified, the value is the name of an attribute whose (translation-time) value at the start of the tag invocation will give the name of the variable. Translation errors arise in the following circumstances:   1. Specifying neither name-given nor name-from-attribute or both. 2. If two variable elements have the same name-given.
variable-class	(optional) The fully qualified name of the class of the object. java.lang.String is the default.
declare	(optional) Whether or not the object is declared. True is the default. A translation error results if both declare and fragment are specified.
scope	(optional) The scope of the variable defined. Can be either AT_BEGIN, AT_END, or NESTED (see Table 15-12). Defaults to NESTED.

Table 15-12 summarizes a variable's availability according to its declared scope.

Table 15-12 Variable Availability 

Value	Availability
NESTED	Between the start tag and the end tag.
AT_BEGIN	From the start tag until the scope of any enclosing tag. If there's no enclosing tag, then to the end of the page.
AT_END	After the end tag until the scope of any enclosing tag. If there's no enclosing tag, then to the end of the page.

You can define the following variable element for the tlt:iterator tag:

<tag>
  <variable>
    <name-given>var</name-given>
    <variable-class>java.lang.String</variable-class>
    <declare>true</declare>
    <scope>NESTED</scope>
  </variable>
</tag> 

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.