Document Information

Preface

Part I Introduction

1.  Overview

2.  Using the Tutorial Examples

Part II The Web Tier

3.  Getting Started with Web Applications

4.  Java Servlet Technology

5.  JavaServer Pages Technology

6.  JavaServer Pages Documents

7.  JavaServer Pages Standard Tag Library

8.  Custom Tags in JSP Pages

What Is a Custom Tag?

The Example JSP Pages

Types of Tags

Tags with Attributes

Simple Attributes

Fragment Attributes

Dynamic Attributes

Deferred Value

Deferred Method

Dynamic Attribute or Deferred Expression

jsp:attribute Element

Tags with Bodies

jsp:body Element

Tags That Define Variables

Communication between Tags

Encapsulating Reusable Content Using Tag Files

Tag File Location

Tag File Directives

Declaring Tags

body-content Attribute

Declaring Tag Attributes in Tag Files

Declaring Tag Variables in Tag Files

Evaluating Fragments Passed to Tag Files

Custom Tag Examples

Simple Attribute Example

Simple and Fragment Attribute and Variable Example

Dynamic Attribute Example

Programming Simple Tag Handlers

Including Tag Handlers in Web Applications

How Is a Simple Tag Handler Invoked?

Tag Handlers for Basic Tags

Tag Handlers for Tags with Attributes

Defining Attributes in a Tag Handler

Attribute Validation

Setting Dynamic Attributes

Setting Deferred Value Attributes and Deferred Method Attributes

Tag Handlers for Tags with Bodies

Tag Handler Does Not Manipulate the Body

Tag Handlers for Tags That Define Variables

TagExtraInfo Class

Cooperating Tags

Tag Handler Examples

An Iteration Tag

A Template Tag Library

9.  Scripting in JSP Pages

10.  JavaServer Faces Technology

11.  Using JavaServer Faces Technology in JSP Pages

12.  Developing with JavaServer Faces Technology

13.  Creating Custom UI Components

14.  Configuring JavaServer Faces Applications

15.  Internationalizing and Localizing Web Applications

Part III Web Services

16.  Building Web Services with JAX-WS

17.  Binding between XML Schema and Java Classes

18.  Streaming API for XML

19.  SOAP with Attachments API for Java

Part IV Enterprise Beans

20.  Enterprise Beans

21.  Getting Started with Enterprise Beans

22.  Session Bean Examples

23.  A Message-Driven Bean Example

Part V Persistence

24.  Introduction to the Java Persistence API

25.  Persistence in the Web Tier

26.  Persistence in the EJB Tier

27.  The Java Persistence Query Language

Part VI Services

28.  Introduction to Security in the Java EE Platform

29.  Securing Java EE Applications

30.  Securing Web Applications

31.  The Java Message Service API

32.  Java EE Examples Using the JMS API

33.  Transactions

34.  Resource Connections

35.  Connector Architecture

Part VII Case Studies

36.  The Coffee Break Application

37.  The Duke's Bank Application

Part VIII Appendixes

A.  Java Encoding Schemes

B.  About the Authors

Index

 

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 8-6 lists the subelements of the taglib element.

Table 8-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 8-7 lists the subelements of the validator element.

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

Table 8-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 8-9 lists the subelements of the tag element.

Table 8-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 8-10 lists the subelements of the attribute element.

Table 8-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. 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 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 (with 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 8-11 lists the subelements of the variable element.

Table 8-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:

  • Specifying neither name-given nor name-from-attribute or both.

  • 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 8-12). Defaults to NESTED.

Table 8-12 summarizes a variable’s availability according to its declared scope.

Table 8-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>