The Java EE 5 Tutorial

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:

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>