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.

Most containers set the JSP version of this automatically generated TLD (called an implicit TLD) to 2.0. Therefore, in order to take advantage of JSP 2.1 features, you must provide a TLD that sets the JSP version to 2.1 if you don't have a TLD already. This TLD must be named implicit.tld and placed into the same directory as the tag files.

You set the JSP version using the version attribute of the root taglib element that of the TLD, as shown here:

   <taglib      xsi:schemaLocation=      "http://java.sun.com/xml/ns/javaee web-        jsptaglibrary_2_1.xsd"      xmlns="http://java.sun.com/xml/ns/javaee"|      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      version="2.1">


Table 76 lists the subelements of the taglib element.

Table 76. 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 (page 231).

listener

See listener Element (page 231).

tag-file | tag

Declares the tag files or tags defined in the tag library. See Declaring Tag Files (page 231) and Declaring Tag Handlers (page 234). 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, page 134) 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 77 lists the subelements of the validator element.

Table 77. 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, page 63). 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 78.

Table 78. 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, page 211).

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 79 lists the subelements of the tag element.

Table 79. 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 (page 238).

body-content

The body content type. See body-content Element (page 235).

variable

(optional) Declares an EL variable exposed by the tag to the calling page. See Declaring Tag Variables for Tag Handlers (page 238).

attribute

Declares an attribute of the custom tag. See Declaring Tag Attributes for Tag Handlers (page 236).

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 710 lists the subelements of the attribute element.

Table 710. 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. When this element is set to true and the attribute definition also includes either a deferred-value or deferred-method element then the attribute accepts both dynamic and deferred expressions.

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.

deferred-value

(optional) Indicates that the tag attribute accepts deferred value expressions. This element includes an optional type child element, which indicates the type of object to which the expression resolves. If no type element is included, the type is java.lang.Object. Either the deferred-value or deferred-method element (but not both) can be defined for the same attribute.

deferred-method

(optional) Indicates that the tag attribute accepts deferred method expressions. This element includes an optional method-signature child element, which indicates the signature of the method that the expression invokes. If no method signature is defined, the method signature default is void methodName(). Either the deferred-value or deferred-method element (but not both) can be defined for the same attribute.


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 (page 211) 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, page 248). 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 711 lists the subelements of the variable element.

Table 711. 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 712). Defaults to NESTED.


Table 712 summarizes a variable's availability according to its declared scope.

Table 712. 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>




The JavaT EE 5 Tutorial
The JavaT EE 5 Tutorial
ISBN: N/A
EAN: N/A
Year: 2004
Pages: 309

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net