8 JSP Tag Libraries

Overview of a Custom Tag Library Implementation

A custom tag library is made accessible to a JSP page through a taglib directive of the following general form:

<%@ taglib uri="URI" prefix="prefix" %>

Note the following points about implementation and usage of a tag library:

• The tags of a library are defined in a tag library descriptor (TLD) file, as "Tag Library Descriptor Files" describes.

• The URI in the taglib directive is a pointer to the TLD file, as "Overview: Specifying a Tag Library with the taglib Directive" discusses. It is possible to use URI shortcuts, as "Use of web.xml for Tag Libraries" explains.

• The prefix in the taglib directive is a string of your choosing that you use in your JSP page with any tag from the library.

  Assume that the taglib directive specifies a prefix oracust:

  <%@ taglib uri="URI" prefix="oracust" %>
  
  

  Further assume that there is a tag, mytag, in the library. You might use mytag as follows:

  <oracust:mytag attr1="...", attr2="..." />
  
  

  Using the oracust prefix informs the JSP translator that mytag is defined in the TLD file that can be found through the URI specified in the above taglib directive.

• The entry for a tag in the TLD file provides specifications about use of the tag, including whether the tag uses attributes (as mytag does), and the names of those attributes.

• The semantics of a tag—the actions that occur as the result of using the tag—are defined in a tag handler class, as "Tag Handlers" describes. Each tag has its own tag handler class, and the class name is specified in the TLD file.

• A tag attribute can be of any standard Java type or an object type—either the generic java.lang.Object or a user-defined type.

  You typically set an attribute of a standard Java type as a string value. The appropriate conversion is handled automatically.

  You can also set an attribute of type Object with a string value. The string is converted to an Object instance and passed in to the corresponding setter method in the tag handler instance. This feature complies with the JSP specification.

  An attribute of a user-defined type must be set using a request-time expression that returns an instance of the type.

• The TLD file indicates whether a tag uses a body.

  A tag without a body is used as in the following example:

  <oracust:mytag attr1="...", attr2="..." />
  
  

  By contrast, a tag with a body is used as in the following example:

  <oracust:mytag attr1="...", attr2="..." >
     ...body...
  </oracust:mytag>
  
  

• A custom tag action can create one or more server-side objects that are available for use by the tag itself or by other JSP scripting elements, such as scriptlets. These objects are known as scripting variables.

  You can declare a scripting variable through a <variable> element in the TLD file or through a tag-extra-info class. See "Scripting Variables, Declarations, and Tag-Extra-Info Classes" for more information.

  A tag can create and use scripting variables with syntax such as in the following example, which creates the object myobj:

  <oracust:mytag id="myobj" attr1="...", attr2="..." />
  
  

• The TLD file can optionally declare a tag-library-validator class for use with the tag library. This class would have logic to validate any JSP page that uses the tag library, according to specified constraints. See "Validation and Tag-Library-Validator Classes".

• The TLD file can optionally declare one or more event listeners for use with the tag library. This functionality is offered as a convenient alternative to declaring listeners in the application web.xml file. See "Tag Library Event Listeners".

• The tag handler of a nested tag can access the tag handler of an outer tag, in case this is required for any of the processing or state management of the nested tag. See "Access to Outer Tag Handler Instances".

The remainder of this chapter provides details about these topics.

Overview of Tag Library Changes Between the JSP 1.1 and 1.2 Specifications

The JSP 1.2 specification introduced features for improved tag library support in the following areas:

• Tag library descriptor features

  Features are outlined in the next section, "Summary of TLD File Changes Between the JSP 1.1 and 1.2 Specifications". "Tag Library Descriptor Files" describes TLD features in detail.

• Support for multiple tag libraries and their TLD files in a single JAR file

  According to the JSP 1.1 specification, you could not have multiple TLD files packaged in a single JAR file. The JSP 1.2 specification supports this, however. See "Tag Handlers".

• Tag handler features

  Features are summarized in "Summary of Tag Handler Changes Between the JSP 1.1 and 1.2 Specifications". Tag handler features are described in detail in "Tag Handlers".

• Tag library validators

  This feature was introduced in the JSP 1.2 specification. See "Validation and Tag-Library-Validator Classes".

• Tag library event listeners

  This feature was also introduced in the JSP 1.2 specification. See "Tag Library Event Listeners".

• Support for tag attributes of type Object

  The JSP 1.2 specification introduced support for tag attributes of type java.lang.Object. The OC4J JSP container supports this feature, as described in the previous section, "Overview of a Custom Tag Library Implementation".

Overview of TLD File Validation and Features

The OC4J JSP container uses the DOCTYPE declaration of a TLD file to determine which TLD DTD version to validate against, unless TLD validation has been disabled. By default in Oracle Application Server 10g Release 2 (10.1.2), the JSP container assumes the JSP 1.1 TLD DTD. To use the JSP 1.2 TLD DTD, list the following as the system ID (DTD location):

http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd

Here is an example:

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

When TLD validation is enabled, the XML parser must be able to reference the appropriate DTD, which it can do with the above DOCTYPE declaration for JSP 1.2. TLD validation is enabled if the JSP no_tld_xml_validate parameter has its default false setting, or, for pretranslation, if the ojspc -noTldXmlValidation flag is not used.

A TLD file provides definitions for the tag library as a whole as well as for each individual tag. For each tag, it defines the tag name, its attributes (if any), its scripting variables (if any), and the name of the class that handles tag semantics. See "Use of the tag Element".

For the library as a whole, TLD definitions can include a tag-library-validator class and event listeners. See "Other Key Elements and Their Subelements: validator and listener".

A TLD file also provides additional definitions for the library as a whole, as follows.

• The required <tlib-version> element specifies the version number of the tag library (whatever version number you want to give it).

• The required <jsp-version> element specifies the JSP version upon which this tag library depends (such as 1.2).

• The <uri> element can specify a string value that uniquely identifies this tag library. In particular, this is useful in situations where multiple tag libraries and their TLD files are packaged in a single JAR file. See "Packaging and Accessing Multiple Tag Libraries in a JAR File".

• The required <short-name> element specifies a convenient default name for the library, for possible use by authoring tools. You could also use the short name as a preferred tag prefix for the library, for use in the taglib directive.

• There are also additional elements that you can use, typically for authoring tools: the <display-name> element for a display name of the tag library, and the <large-icon> and <small-icon> elements for the file names (.jpg or .gif) of a large icon, a small icon, or both. Icon file locations are relative to the TLD file.

• The <description> element can provide a description of the tag library.

  
  

  Note: Several descriptive elements were added to the JSP 1.2 TLD DTD. In addition to the <description> element directly under the root <taglib> element, there are <description> subelements under the <tag>, <variable>, and <attribute> elements. There is also an <example> subelement under the <tag> element. These subelements can provide information for developers who wish to use the tag library. In particular, a TLD can be processed, such as through an XSLT style sheet, to provide developer documentation from the material in the descriptive elements. This information can be displayed in the help windows of tools such as Oracle JDeveloper, for example.

  
  

Use of the tag Element

Each tag of a tag library is specified in a <tag> element under the root <taglib> element of the TLD file. There must be at least one <tag> element in a TLD file. This section describes its usage and subelements.

<tag>
  <name>myaction</name>
  <tag-class>examples.MyactionTag</tag-class>
  <tei-class>examples.MyactionTagExtraInfo</tei-class>
  <body-content>JSP</body-content>
  <attribute>
    <name>attr1</name>
    <required>true</required>
  </attribute>
  <attribute>
    <name>attr2</name>
    <required>false</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>
</tag>

<foo:bar>
   <%=blah%>
</foo:bar>

<foosql:query ... >
   select ... where salary > 1000
</foosql:query>

<foosql:query ... >
   <![CDATA[select ... where salary > 1000]]>
</foosql:query>

<![CDATA[select ... where salary > 1000]]>

select ... where salary > 1000

Other Key Elements and Their Subelements: validator and listener

The TLD <validator> and <listener> elements were introduced in the JSP 1.2 specification.

A <validator> element and its subelements specify information about a tag-library-validator (TLV) class that can validate JSP pages that use this tag library. The <validator> element has three subelements: <validator-class>, <description>, and <init-param>. The <init-param> subelement has the same functionality as <init-param> subelements within <servlet> elements in the web.xml file. It has <param-name> and <param-value> subelements to specify each parameter. See "Validation and Tag-Library-Validator Classes" for more information.

A <listener> element and its <listener-class> subelement specify an event listener for use with the tag library, such as in creating and destroying resource pools used by the library. See "Tag Library Event Listeners" for more information.

Overview: Specifying a Tag Library with the taglib Directive

This section summarizes the use of taglib directives, comparing functionality under the JSP 1.1 specification to functionality under the JSP 1.2 and later specifications.

Import a custom library into a JSP page by using a taglib directive of the following general form:

<%@ taglib uri="URI" prefix="prefix" %>

The prefix setting specifies a string of characters that stipulates when tags from this library are being used. For example, if mytag is in a library that has a specified prefix of oracust, use mytag as follows:

<oracust:mytag attr1="..." attr2="..." >
...
</oracust:mytag>

The JSP 1.1 specification stated that the uri setting can indicate a file location as in either of the following scenarios, either directly or through a "shortcut" URI:

• It can indicate the physical location, within a WAR file structure, of the TLD file that defines the desired tag library.

• It can indicate the physical location of the JAR file that contains the components and TLD file of the desired tag library. Under the JSP 1.1 specification, there can be only one tag library and only one TLD file in the JAR file.

See "Specifying a Tag Library by Physical Location" for more information.

Beginning with the JSP 1.2 specification, the uri setting can still indicate the physical location of a TLD file or the location of a JAR file containing one tag library and its TLD file, but it can also be used as follows:

• It can specify one of multiple tag libraries packaged in a single JAR file, by specifying a value that matches the <uri> element value in one of the TLD files in the JAR file. In this case, the uri setting is intended to be a unique key, not a pointer to a physical location.

As under JSP 1.1, you can also use a shortcut URI.

See "Packaging and Accessing Multiple Tag Libraries in a JAR File" for more information. For information about shortcut URIs, see "Use of web.xml for Tag Libraries".

Specifying a Tag Library by Physical Location

As first defined in the JSP 1.1 specification, the taglib directive of a JSP page can fully specify the name and physical location, within a WAR file structure, of the TLD file that defines a particular tag library, as in the following example:

<%@ taglib uri="/WEB-INF/oracustomtags/tlds/mytld.tld" prefix="oracust" %>

Specify the location as application-relative by starting with "/" as in this example. See "Requesting a JSP Page" for discussion of application-relative syntax.

Be aware that the TLD file should be in the /WEB-INF directory or a subdirectory.

Alternatively, as also defined since the JSP 1.1 specification, the taglib directive can specify the name and application-relative physical location of a JAR file instead of a TLD file, where the JAR file contains a single tag library and the TLD file that defines it. In this scenario, the JSP 1.1 specification mandated that the TLD file must be located and named as follows in the JAR file:

META-INF/taglib.tld

The JSP 1.1 specification also mandated that the JAR file must be located in the /WEB-INF/lib directory.

Here is an example of a taglib directive that specifies a tag library JAR file:

<%@ taglib uri="/WEB-INF/lib/mytaglib.jar" prefix="oracust" %>

Also see "Packaging and Accessing Multiple Tag Libraries in a JAR File", following, which describes a scenario introduced in the JSP 1.2 specification.

Packaging and Accessing Multiple Tag Libraries in a JAR File

The preceding section, "Specifying a Tag Library by Physical Location", discusses the JSP 1.1 scenarios of using a taglib directive to specify a TLD file by physical location, or to specify a JAR file that contains a single tag library and its TLD file.

Adding to these scenarios, the JSP 1.2 specification introduced the packaging of multiple tag libraries, and the TLD files that define them, in a single JAR file. Inside the JAR file, these TLD files must be located under the /META-INF directory or a subdirectory.

A single TLD file in a JAR file can be packaged as /META-INF/taglib.tld, or you can use another name as desired. (In JSP 1.1, the taglib.tld naming convention was a requirement.)

In a JAR file with multiple TLD files, the TLD files must be uniquely named or be in different subdirectories under META-INF.

Here are a couple of possibilities, for example, for packaging three TLD files in a JAR file:

META-INF/abctags.tld
META-INF/deftags.tld
META-INF/ghitags.tld

or:

META-INF/abc/taglib.tld
META-INF/def/taglib.tld
META-INF/ghi/taglib.tld

In each TLD file, there is a <uri> element under the root <taglib> element. Use this feature as follows:

• The <uri> element must specify a value that is to be matched by the uri setting of a taglib directive in any JSP page that wants to use the corresponding tag library.

• To avoid unintended results, each <uri> value should be unique across all <uri> values in all TLD files on the server.

The value of the <uri> element can be arbitrary. It is simply used as a key and does not indicate a physical location. By convention, however, its value is of the form of a physical location, such as in the following example:

<uri>http://www.mycompany.com/j2ee/jsp/tld/myproduct/mytags.tld</uri>

A <uri> value must follow the XML namespace convention.

A JAR file with multiple TLD files must be placed in the /WEB-INF/lib directory or in an OC4J "well-known" tag library location as described in "Oracle Extensions for Tag Library Sharing and Persistent TLD Caching". During translation, the JSP container searches these two locations for JAR files, searches each JAR file for TLD files, and accesses each TLD file to find its <uri> element.

META-INF/mytaglib1.tld
META-INF/mytaglib2.tld

<taglib> 
   <tlib-version>1.0</tlib-version> 
   <jsp-version>1.2</jsp-version> 
   <short-name>shorty</short-name>
   <uri>http://www.foo.com/jsp/mytaglib1</uri>
   <description>example TLD</description>
   <tag>
      <name>mytag1</name>
      ...
   </tag>
   ...
</taglib>

<%@ taglib uri="http://www.foo.com/jsp/mytaglib1" prefix="myprefix1" %>

Use of web.xml for Tag Libraries

The Sun Microsystems Java Servlet Specification describes a standard deployment descriptor for servlets: the web.xml file. JSP pages can use this file in specifying the location or URI identifier of a JSP TLD file.

For JSP tag libraries, the web.xml file can include <taglib> elements and two subelements:

• <taglib-uri>

• <taglib-location>

For the scenario of an individual TLD file, or the scenario of a JAR file that contains a single tag library and its TLD file, the <taglib-location> subelement indicates the application-relative physical location (by starting with "/") of the TLD file or tag library JAR file. See "Specifying a Tag Library by Physical Location" for related information.

For the scenario of a JAR file that contains multiple tag libraries and their TLD files, a <taglib-location> subelement indicates the unique identifier of a tag library. In this case, the <taglib-location> value actually indicates a key, not a location, and corresponds to the <uri> value in the TLD file of the desired tag library. See "Packaging and Accessing Multiple Tag Libraries in a JAR File" for related information.

The <taglib-uri> subelement indicates a shortcut URI to use in taglib directives in your JSP pages, with this URI being mapped to the physical location or URI identifier specified in the accompanying <taglib-location> subelement.

Following is a sample web.xml entry for a TLD file:

<taglib>
   <taglib-uri>/oracustomtags</taglib-uri>
   <taglib-location>/WEB-INF/oracustomtags/tlds/mytld.tld</taglib-location>
</taglib>

This entry makes /oracustomtags equivalent to /WEB-INF/oracustomtags/tlds/mytld.tld in taglib directives in your JSP pages.

Given this example, the following directive in your JSP page results in the JSP container finding the /oracustomtags URI in web.xml and, therefore, finding the accompanying name and location of the TLD file (mytld.tld):

<%@ taglib uri="/oracustomtags" prefix="oracust" %>

This statement enables you to use any of the tags of this custom tag library in a JSP page.

See the Sun Microsystems Java Servlet Specification and the Sun Microsystems JavaServer Pages Specification for more information about the web.xml deployment descriptor.

Oracle Extensions for Tag Library Sharing and Persistent TLD Caching

As an extension of standard JSP "well-known URI" functionality described in the JSP specification, the OC4J JSP container supports the use of one or more directories, known as well-known tag library locations, where you can place tag library JAR files to be shared across multiple Web applications.

There is also a persistent caching feature for TLD files, with a global cache for TLD files in any well-known tag library locations, as well as an application-level cache for any application that uses TLD caching.

The use of TLD caching speeds performance at application startup and during JSP page translation. You might typically turn it off, however, under either of the following circumstances:

• Your application does not use tag libraries.

or:

• You have pretranslated the JSP pages and none of the TLD files use <listener> elements for tag library event listeners. (See "Tag Library Event Listeners".)

The following sections provide additional information:

• TLD Caching and Well-Known Tag Library Locations

• TLD Cache Features and Files

Example: Multiple Tag Libraries and TLD Files in a JAR File

This section presents an example of tag library packaging. This is a situation where multiple tag libraries are packaged in a single JAR file. The JAR file includes tag handler classes, tag-library-validator classes, and TLD files for multiple libraries. The following shows the contents and structure of the JAR file:

examples/BasicTagParent.class
examples/ExampleLoopTag.class
examples/BasicTagChild.class
examples/BasicTagTLV.class
examples/TagElemFilter.class
examples/XMLViewTagTLV.class
examples/TagFilter.class
examples/XMLViewTag.class
META-INF/xmlview.tld
META-INF/exampletag.tld
META-INF/basic.tld
META-INF/MANIFEST.MF

<taglib>

  <tlib-version>1.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  <short-name>basic</short-name>
  <uri>http://xmlns.oracle.com/j2ee/jsp/tld/demos/basic.tld</uri>

  ...

</taglib>

<taglib xmlns="http://java.sun.com/JSP/TagLibraryDescriptor">

  <tlib-version>1.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  <short-name>example</short-name>
  <uri>http://xmlns.oracle.com/j2ee/jsp/tld/demos/exampletag.tld</uri>

  ...

</taglib>

<taglib>

  <tlib-version>1.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  <short-name>demo</short-name>
  <uri>http://xmlns.oracle.com/j2ee/jsp/tld/demos/xmlview.tld</uri>

  ...

</taglib>

...
<taglib>
  <taglib-uri>/oraloop</taglib-uri> 
  <taglib-location>http://xmlns.oracle.com/j2ee/jsp/tld/demos/exampletag.tld
  </taglib-location> 
</taglib>
<taglib>
  <taglib-uri>/orabasic</taglib-uri> 
  <taglib-location>http://xmlns.oracle.com/j2ee/jsp/tld/demos/basic.tld
  </taglib-location> 
</taglib>
<taglib>
  <taglib-uri>/oraxmlview</taglib-uri> 
  <taglib-location>http://xmlns.oracle.com/j2ee/jsp/tld/demos/xmlview.tld
  </taglib-location> 
</taglib>
...

<%@ taglib prefix="basic" uri="/orabasic" %>

<%@ taglib prefix="example" uri="/oraloop" %>

<%@ taglib prefix="demo" uri="/oraxmlview" %>

Overview of Tag Handlers

A tag handler is an instance of a Java class that directly or indirectly implements the standard javax.servlet.jsp.tagext.Tag interface. Depending on whether there is a tag body and how that body is to be processed, the tag handler implements one of the following interfaces, in the javax.servlet.jsp.tagext package:

• Tag: This interface defines the basic methods for all tag processing, but does not include tag body processing.

• IterationTag: This interface extends Tag and is for iterating through a tag body.

• BodyTag: This interface extends IterationTag and is for accessing the tag body content itself.

A tag handler class might implement one of these interfaces directly, or might extend a class (such as one of the support classes provided by Sun Microsystems) that implements one of them.

Each custom tag has its own handler class. By convention, the name of the tag handler class for a tag abc, for example, is AbcTag.

The TLD file of a tag library specifies the name of the tag handler class for each tag in the library. See "Tag Library Descriptor Files".

A tag handler instance is typically created by the JSP page implementation instance, by use of a zero-argument constructor, and is a server-side object used at request-time. The tag handler has properties that are set by the JSP container, including the page context object for the JSP page that uses the custom tag, and a parent tag handler object if the use of this tag is nested within an outer tag. A tag handler, as applicable, supports parameter-passing, evaluation of the tag body, and access to other objects in the JSP page, including other tag handlers.

"Example: Using the IterationTag Interface and a Tag-Extra-Info Class" includes code for a sample tag handler class.

Attribute Handling, Conversions from String Values

A tag handler class has an underlying property for each attribute of the custom tag. These properties are somewhat like JavaBean properties, with at least a setter method.

Recall that there are two approaches in setting a tag attribute:

• The first approach is where the attribute is a non-request-time attribute, set using a string literal value:

  nrtattr="string"
  
  

  For a non-request-time attribute, if the underlying tag handler property is not of type String, the JSP container will try to convert the string value to a value of the appropriate type.

  Because tag attributes correspond to bean-like properties, their processing, such as for these type conversions from string values, is similar to that of bean properties. See "Bean Property Conversions from String Values".

• The second approach is where the attribute is a request-time attribute that is set using a request-time expression:

  rtattr="<%=expression%>"
  
  

  For request-time attributes, there is no conversion. A request-time expression can be assigned to the attribute, and to its corresponding tag handler property, for any property type. This would apply to a tag attribute whose type is user-defined, for example.

Custom Tag Processing, with or without Tag Bodies

A custom tag, as with a standard JSP tag, might or might not have a body. In the case of a custom tag, even when there is a body, its content might not have to be accessed by the tag handler.

There are four scenarios:

1. There is no body.

   In this case you need only a single tag, not a start-tag and end-tag. Following is a general example:

   <oracust:mytag attr1="...", attr2="..." />
   
   

   This is equivalent to the following, which is also permissible:

   <oracust:mytag attr1="...", attr2="..." ></oracust:abcdef>
   
   

   In this case, the tag handler should implement the Tag interface.

   The <body-content> setting for this tag in the TLD file should be empty.

2. There is a body; access of the body content by the tag handler is not required; the body is executed no more than once.

   In this case, there is a start-tag and an end-tag with a body of statements in between, but the tag handler does not process the body. Body statements are passed through for normal JSP processing only. Following is a general example of this scenario:

   <foo:if cond="<%= ... %>" >
   ...body executed if cond is true, but body content not accessed by tag handler...
   </foo:if>
   
   

   In this case, the tag handler should implement the Tag interface.

   The <body-content> setting for this tag in the TLD file should be JSP (the default) or tagdependent, depending on whether the body content should be translated or treated as template data, respectively.

3. There is a body; access of the body content by the tag handler is not required; the body is executed multiple times (iterated).

   This is the same as the second scenario, except there is iterative processing of the tag body.

   <foo:myiteratetag ... >
   ...body executed multiple times, according to attribute or other settings,
   but body content not accessed by tag handler...
   </foo:myiteratetag>
   
   

   In this case, the tag handler should implement the IterationTag interface.

   The <body-content> setting for this tag in the TLD file should be JSP (the default) or tagdependent, depending on whether the body content should be translated or treated as template data, respectively.

4. There is a body that must be processed by the tag handler.

   Again, there is a start-tag and an end-tag with a body of statements in between; however, the tag handler must access the body content.

   <oracust:mybodytag attr1="...", attr2="..." >
   ...body accessed and processed by tag handler...
   </oracust:mybodytag>
   
   

   In this case, the tag handler should implement the BodyTag interface.

   The <body-content> setting for this tag in the TLD file should be JSP (the default) or tagdependent, depending on whether the body content should be translated or treated as template data, respectively.

   
   

   Notes: In the first scenario, where there is no body, the action is known as an empty action. In the second, third, and fourth scenarios, where there is a body, the action is known as a non-empty action. In the first, second, and third scenarios, where no body content processing is required by the tag handler, the handler is known as a simple tag handler. For additional information about the <body-content> element, see "Use of the tag Element".

   
   

Summary of Integer Constants for Body Processing

The tag handler interfaces that are described in the following sections specify methods that you must implement, as applicable, to return appropriate int constants, depending on the situation.

The possible return values from the doStartTag() method, which is defined in the Tag interface and inherited by the IterationTag and BodyTag interfaces, are as follows:

• SKIP_BODY: Use this value if there is no body or if evaluation of the body should be skipped.

• EVAL_BODY_INCLUDE: Use this value to evaluate the body and pass it through to the current JSP out object. There is no special processing of the body content; no body content object is created.

• EVAL_BODY_BUFFERED (for BodyTag classes only): Use this value to create a BodyContent object for the content of the tag body, used for evaluation and processing of the content.

• EVAL_BODY_TAG: This is deprecated (formerly used if there is a body that requires special processing by the tag handler). Use EVAL_BODY_AGAIN or EVAL_BODY_BUFFERED, which both have the same int value as EVAL_BODY_TAG.

The possible return values from the doAfterBody() method, defined in the IterationTag interface and inherited by the BodyTag interface, are as follows:

• SKIP_BODY: Use this value to skip evaluation of the body or, when iterating through the body, to stop iterating.

• EVAL_BODY_AGAIN: Use this value to continue iterating through the body.

The possible return values from the doEndTag() method, defined in the Tag interface and inherited by the IterationTag and BodyTag interfaces, are as follows:

• SKIP_PAGE: Use this value to skip the rest of the page after the tag. This completes the request.

• EVAL_PAGE: Use this value to evaluate the remainder of the page after the tag.

Simple Tag Handlers without Iteration

For a custom tag that does not have a body, or has a body whose content does not require access and special processing by the tag handler, the tag handler is referred to as a simple tag handler. The tag handler class can implement the following standard interface:

• javax.servlet.jsp.tagext.Tag

However, if there is a tag body that is to be iterated, then the tag handler should implement the IterationTag interface instead. See "Simple Tag Handlers with Iteration".

The standard javax.servlet.jsp.tagext.TagSupport class implements the Tag interface, but also implements the IterationTag interface. Because of this, it is inefficient to use the TagSupport class for a tag that does not iterate through the tag body. This is especially important to consider when migrating code from a JSP 1.1 environment to a JSP 1.2 environment, in case you created tag handlers that extended TagSupport under JSP 1.1. For simple tag handlers not requiring body iteration, it is best to implement the Tag interface from scratch.

The Tag interface defines methods for the following key functions:

• Set up the JSP page context object (pageContext property).

• Set or get the parent tag handler—the handler for the closest enclosing tag, if applicable (parent property).

• Set up the tag attributes.

• Conditionally process the tag body, as appropriate, according to the return value of the doStartTag() method. (See immediately following.)

• Conditionally process the remainder of the JSP page after the tag, as appropriate, according to the return value of the doEndTag() method. (See immediately following.)

• Release state information.

For complete information, see the Sun Microsystems Tag interface Javadoc at:

http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/jsp/tagext/Tag.html

In particular, the Tag interface specifies the following key methods:

• doStartTag()

• doEndTag()

The tag developer provides code for these methods in the tag handler class, as appropriate, to be executed as the start-tag and end-tag, respectively, are encountered. The JSP page implementation class generated by the JSP translator includes appropriate calls to these methods.

Implement action processing—whatever you want the action tag to accomplish—in the doStartTag() method. The doEndTag() method implements any appropriate post-processing. In the case of a tag without a body, essentially nothing happens between the execution of these two methods.

The Tag interface also specifies getter and setter methods for the pageContext and parent properties. The JSP page implementation instance invokes the setPageContext() and setParent() methods before invoking the doStartTag() and doEndTag() methods.

The doStartTag() method returns an int value. For a tag handler class implementing the Tag interface, this value is one of the following:

• SKIP_BODY: Do not evaluate the body, if any. This is the only option if the TLD file specifies a <body-content> setting of empty for the tag associated with this handler.

• EVAL_BODY_INCLUDE: Evaluate the body and pass it through to the current JSP out object.

The doEndTag() method also returns an int value, one of the following:

• SKIP_PAGE: Skip the rest of the page after the tag. If the request was originally from another page, from which the current page was forwarded to or included, only the remainder of the current page evaluation is skipped.

• EVAL_PAGE: Evaluate the remainder of the page after the tag.

Simple Tag Handlers with Iteration

For a custom tag that has a body that does not require access and special processing by the tag handler, but does require repeated reevaluation such as for iteration, the tag handler class can implement the following standard interface:

• javax.servlet.jsp.tagext.IterationTag

The IterationTag interface extends the Tag interface. A class that implements the IterationTag interface is still known as a simple tag handler.

The following standard support class implements the IterationTag interface, as well as the java.io.Serializable interface, and can be used as a base class:

• javax.servlet.jsp.tagext.TagSupport

In addition to implementing appropriate methods from the Tag and IterationTag interfaces, the TagSupport class includes a convenience method, findAncestorWithClass(), that calls the getParent() method defined in the Tag interface.

The IterationTag interface inherits basic tag-handling functionality, including the doStartTag() and doEndTag() methods, from the Tag interface. See "Simple Tag Handlers without Iteration".

The IterationTag interface also defines the following additional key method:

• doAfterBody()

This method is called after each evaluation of the tag body, to see if the body should be evaluated again. It returns one of the following int values:

• SKIP_BODY: Stop iterating; do not reevaluate the tag body. Call doEndTag() instead. The SKIP_BODY setting is also used when the body is not to be evaluated in the first place, and is the only option if the TLD file specifies a <body-content> setting of empty for the tag associated with this handler.

• EVAL_BODY_AGAIN: Continue iterating; reevaluate the tag body. After the body is evaluated, the doAfterBody() method is called again.

Tag Handlers That Access Body Content

For a custom tag with body content that the tag handler must be able to access, the tag handler class can implement the following standard interface:

• javax.servlet.jsp.tagext.BodyTag

The following standard support class implements the BodyTag interface, as well as the java.io.Serializable interface, and can be used as a base class:

• javax.servlet.jsp.tagext.BodyTagSupport

This class implements appropriate methods from the Tag, IterationTag, and BodyTag interfaces.

TryCatchFinally Interface

For data integrity and resource management when exceptions occur during tag processing, the JSP 1.2 specification introduced the javax.servlet.jsp.tagext.TryCatchFinally interface. Implementing this interface in your tag handlers is particularly useful for tags that must handle errors and for ensuring the proper release of resources.

The TryCatchFinally interface specifies the following methods:

• void doCatch(java.lang.Throwable throw)

  This method can be invoked on a tag handler when a Throwable error occurs during evaluation of a tag body or during a call to the doStartTag(), doEndTag(), doAfterBody(), or doInitBody() method. The Throwable object that was encountered is taken as input by the doCatch() method. This method would not be invoked if the Throwable error occurs during a call to a setter method.

  The doCatch() method can throw an exception (the original Throwable exception or a new exception) to be propagated through an error chain.

• void doFinally()

  This method is invoked regardless of whether a Throwable error, as discussed for the doCatch() method, occurs. It would not be invoked, however, if a Throwable error occurs during a call to a setter method.

  The doFinally() method should not throw an exception.

Following is a typical TryCatchFinally invocation (from the Sun Microsystems JavaServer Pages Specification, Version 1.2):

 h = get a Tag();  // get a tag handler, perhaps from pool

 h.setPageContext(pc);  // initialize as desired
 h.setParent(null);
 h.setFoo("foo");
 
 // tag invocation protocol; see Tag.java
 try {
   h.doStartTag()...
   ....
   h.doEndTag()...
 } catch (Throwable t) {
   /* React to exceptional condition; invoked if exception occurs between
      doStartTag() and doEndTag(). */
   h.doCatch(t);
 } finally {
   // restore data invariants and release pre-invocation resources
   h.doFinally();
   /* doFinally() is almost always called, unless Throwable error occurs
      during setter method, or Java thread terminates. */
 }

Access to Outer Tag Handler Instances

Where nested custom tags are used, the tag handler instance of the nested tag has access to the tag handler instance of the outer tag, which might be useful in any processing and state management performed by the nested tag.

This functionality is supported through the static findAncestorWithClass() method of the javax.servlet.jsp.tagext.TagSupport class. Even though the outer tag handler instance is not named in the JSP page context, it is accessible because it is the closest enclosing instance of a given tag handler class.

Consider the following JSP code example:

<foo:bar1 attr="abc" >
   <foo:bar2 />
</foo:bar1>

Within the code of the bar2 tag handler class (class Bar2Tag, by convention), you can have a statement such as the following:

Tag bar1tag = TagSupport.findAncestorWithClass(this, Bar1Tag.class);

The findAncestorWithClass() method takes the following as input:

• The this object that is the class handler instance from which findAncestorWithClass() was called (a Bar2Tag instance in the example)

• The name of the bar1 tag handler class (presumed to be Bar1Tag in the example), as a java.lang.Class instance

The findAncestorWithClass() method returns an instance of the appropriate tag handler class, in this case Bar1Tag, as a javax.servlet.jsp.tagext.Tag instance.

It is useful for a Bar2Tag instance to have access to the outer Bar1Tag instance in case the Bar2Tag needs the value of a bar1 tag attribute or needs to call a method on the Bar1Tag instance.

Disabling or Enabling Runtime or Compile-Time Tag Handler Reuse

To improve performance, you can specify that tag handler instances be reused within each JSP page. This is sometimes referred to as tag handler instance pooling. As of Oracle Application Server 10g Release 2 (10.1.2), there are two models for this:

• Runtime model: The logic and patterns of tag handler reuse is determined at runtime, during execution of the JSP pages. Tag handler reuse is within application scope.

• Compile-time model: The logic and patterns of tag handler reuse is determined at compile-time, during translation of the JSP pages. This is an effective way to improve performance for an application with very large numbers of tags within the same page (hundreds of tags, for example).

The JSP tags_reuse_default configuration parameter is relevant in either case. See "JSP Configuration Parameters" for further information about this parameter and how to set it.

Tag Handler Code Generation

The Oracle JSP implementation reduces the code generation size for custom tag usage. In addition, there is a JSP configuration flag, reduce_tag_code, that you can set to true for even further size reduction.

Be aware, however, that when this flag is enabled, the code generation pattern does not maximize tag handler reuse. Although you can still improve performance by setting tags_reuse_default to true as described in "Disabling or Enabling Runtime or Compile-Time Tag Handler Reuse", the effect is not maximized when reduce_tag_code is also true.

See "JSP Configuration Parameters" for further information about these parameters and how to set them.

Using Scripting Variables

Objects that are defined explicitly in a custom tag can be referenced in other actions through the JSP page context, using the object ID as a handle. Consider the following example:

<oracust:foo id="myobj" attr1="..." attr2="..." />

This statement results in the object myobj being available to scripting elements in the page, according to the declared scope of myobj. (See "Scripting Variable Scopes".) The id attribute is a translation-time attribute. You can specify a variable in one of two ways:

• Provide a <variable> element for the variable in the TLD file, to specify the name and type of the variable along with additional information. See "Variable Declaration Through TLD variable Elements".

• Create a tag-extra-info class, to specify the name and type of the variable along with additional information and related logic. Specify the tag-extra-info class name in a <tei-class> element in the TLD file. See "Variable Declaration Through Tag-Extra-Info Classes".

Generally, the more convenient <variable> mechanism will suffice.

The JSP container enters myobj into the page context, where it can later be obtained by other tags or scripting elements using syntax such as the following:

<oracust:bar ref="myobj" />

The myobj object is passed through the tag handler instances for the foo and bar tags. All that is required is knowledge of the name of the object (myobj).

Scripting Variable Scopes

Specify the scope of a scripting variable in the <variable> element or tag-extra-info class of the tag that creates the variable. It can be one of the following int constants:

• NESTED: Use this setting for the scripting variable to be available between the start-tag and end-tag of the action that defines it.

• AT_BEGIN: Use this setting for the scripting variable to be available from the start-tag to the end of the page.

• AT_END: Use this setting for the scripting variable to be available from the end-tag to the end of the page

Variable Declaration Through TLD variable Elements

The JSP 1.1 specification mandated that use of a scripting variable for a custom tag requires the creation of a tag-extra-info (TEI) class. See "Variable Declaration Through Tag-Extra-Info Classes". The JSP 1.2 specification, however, introduced a simpler mechanism—a <variable> element in the TLD file where the associated tag is defined. This is sufficient for most cases, where logic related to the variable is simple enough to not require use of a TEI class.

The <variable> element is a subelement under the <tag> element that defines the tag that uses the variable.

You can specify the name of the variable in one of two ways:

• Use a <name-given> subelement under <variable> to specify the variable name directly.

or:

• Use a <name-from-attribute> subelement under <variable> to specify a tag attribute whose value, at translation-time, will specify the variable name.

Along with <name-given> and <name-from-attribute>, the <variable> element has the following subelements:

• The <variable-class> element specifies the class of the variable. The default is java.lang.String.

• The <declare> element specifies whether the variable is to be a newly declared variable, in which case the JSP translator will declare it. The default is true. If false, then the variable is assumed to have been declared earlier in the JSP page through a standard mechanism such as a jsp:useBean action, a JSP scriptlet, a JSP declaration, or some custom action.

• The <scope> element specifies the scope of the variable: NESTED, AT_BEGIN, or AT_END, as described in "Scripting Variable Scopes". The default is NESTED.

Here is an example that declares two scripting variables for a tag myaction. Note that details within the <tag> element that are not directly relevant to this discussion are omitted:

<tag>
   <name>myaction</name>
   ...
   <attribute>
     <name>attr2</name>
     <required>true</required>
   </attribute>
   <variable>
      <name-given>foo_given</name-given>
      <declare>false</declare>
      <scope>AT_BEGIN</scope>
   </variable>
   <variable>
      <name-from-attribute>attr2</name-from-attribute>
      <variable-class>java.lang.Integer</variable-class>
   </variable>
</tag>

The name of the first variable is hardcoded as foo_given. By default, it is of type String. It is not to be newly declared, so is assumed to exist already, and its scope is from the start-tag to the end of the page.

The name of the second variable is according to the setting of the required attr2 attribute. It is of type Integer. By default, it is to be newly declared and its scope is NESTED, between the myaction start-tag and end-tag.

See "Tag Library Descriptor Files" for more information about related TLD syntax.

Variable Declaration Through Tag-Extra-Info Classes

For a scripting variable with associated logic that is at least somewhat complicated, the use of a <variable> element in the TLD file to declare the variable might be insufficient. In this case, you can specify details regarding the scripting variable in a subclass of the javax.servlet.jsp.tagext.TagExtraInfo abstract class. This manual refers to such a subclass as a tag-extra-info class. Tag-extra-info classes support additional validation of tag attributes and provide additional information about scripting variables to the JSP runtime.

The JSP container uses tag-extra-info instances during translation. The TLD file specifies any tag-extra-info classes to use for scripting variables of a given tag. Use <tei-class> elements, as in the following example:

<tag>
  <name>loop</name>
  <tag-class>examples.ExampleLoopTag</tag-class>
  <tei-class>examples.ExampleLoopTagTEI</tei-class>
  <body-content>JSP</body-content>
  <description>for loop</description>
  <attribute>
     ...
  </attribute>
  ...
</tag>

The following are related classes, also in the javax.servlet.jsp.tagext package:

• TagData: An instance of this class contains translation-time attribute value information for a tag instance.

• VariableInfo: Each instance of this class contains information about a scripting variable that is declared, created, or modified by a tag at runtime.

• TagInfo: An instance of this class contains information about the relevant tag. The class is instantiated from the TLD file and is available only at translation time. TagInfo has methods such as getTagName(), getTagClassName(), getBodyContent(), getDisplayName(), and getInfoString().

You can refer to the following location for further information:

http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/jsp/tagext/package-summary.html

The following methods of the TagExtraInfo class are related:

• boolean isValid(TagData data)

  The JSP translator calls this method for translation-time validation of the tag attributes, passing it a TagData instance.

• VariableInfo[] getVariableInfo(TagData data)

  The JSP translator calls this method during translation, passing it a TagData instance. This method returns an array of VariableInfo instances, with one instance for each scripting variable the tag creates.

• void setTagInfo(TagInfo info)

  Calling this method sets a TagInfo instance as an attribute of the tag-extra-info class. This method is typically called by the JSP container.

• TagInfo getTagInfo()

  Use this method to retrieve the TagInfo attribute of the tag-extra-info class, assuming the TagInfo attribute was previously set.

The tag-extra-info class constructs each VariableInfo instance with the following information regarding the scripting variable:

• Its name

• Its Java type (not a primitive type)

• A boolean value indicating whether the variable is to be newly declared, in which case the JSP translator will declare it

• Its scope

See "Sample Tag-Extra-Info Class: ExampleLoopTagTEI.java" for sample code of a tag-extra-info class.

TLD validator Element

To specify a TLV class for a tag library, use a <validator> element in the TLD file. The <validator> element has the following subelements:

• The <validator-class> subelement specifies the TLV class name.

• The <description> subelement can be used to provide documentation about the TLV class.

• The <init-param> subelement and its own subelements—<param-name> and <param-value>—can be used to set initialization parameters for the TLV class. This is similar to how <init-param> subelements work within <servlet> elements in the application deployment descriptor (web.xml). There is also an optional <description> subelement under the <init-param> element.

The following <validator> element examples are from the Sun Microsystems JavaServer Pages Standard Tag Library, Version 1.0 specification.

<validator>
   <validator-class>
      javax.servlet.jsp.jstl.tlv.ScriptFreeTLV
   </validator-class>
   <init-param>
      <param-name>allowDeclarations</param-name>
      <param-value>false</param-value>
   </init-param>
   <init-param>
      <param-name>allowScriptlets</param-name>
      <param-value>false</param-value>
   </init-param>
   <init-param>
      <param-name>allowExpressions</param-name>
      <param-value>true</param-value>
   </init-param>
   <init-param>
      <param-name>allowRTExpressions</param-name>
      <param-value>true</param-value>
   </init-param>
</validator>

<validator>
   <validator-class>
      javax.servlet.jsp.jstl.tlv.PermittedTaglibsTLV
   </validator-class>
   <init-param>
      <param-name>permittedTaglibs</param-name>
      <param-value>
         http://java.sun.com/jstl/core
         http://java.sun.com/jstl/xml
         http://java.sun.com/jstl/fmt
         http://java.sun.com/jstl/sql
      </param-value>
   </init-param>
</validator>

Key TLV-Related Classes and the validation() Method

As the introduction mentions, a TLV class is a subclass of the javax.servlet.jsp.tagext.TagLibraryValidator class.

The following related classes are also in the javax.servlet.jsp.tagext package:

• PageData: An instance of this class is generated by the JSP translator and contains information corresponding to the XML view of the page being translated.

• ValidationMessage: An instance of this class contains an error message from a TLV instance, being returned through the TLV validate() method.

Here is the key method of a TLV class:

• ValidationMessage[] validate (String prefix, String uri, PageData page)

  The JSP container calls this method each time it encounters a taglib directive that points to a TLD file that has a <validator> element. The method takes as input the tag library prefix, the TLD URI, and the PageData object (XML view) of the page. If errors are encountered during validation, the validate() method returns an array of validation messages. Because the OC4J JSP container supports the optional jsp:id attribute, the jsp:id values are included in the validation messages.

  See the next section, "TLV Processing", for more information.

TLV Processing

As each taglib directive is encountered in a JSP page during translation, the JSP container searches the associated TLD file for a <validator> element that specifies a TLV class. If one is found, the container executes the following steps during the translation. See the preceding section, "Key TLV-Related Classes and the validation() Method", for background information about classes and methods discussed here.

1. The TLV class is instantiated, with initialization parameter settings according to any <init-param> subelements of the <validator> element.

2. The XML view of the JSP page is exposed to the TLV instance. (See "Details of the JSP XML View".)

3. The validate() method of the TLV instance is called to validate the JSP page. (See the next section, "Validation Mechanisms".) If this method encounters any errors, it returns an array of ValidationMessage instances. If there are no errors, the method can return null or an empty ValidationMessage[] array.

   
   

   Note: The OC4J JSP container implements an optional JSP 1.2 feature for improved reporting of validation errors—the jsp:id attribute. See "The jsp:id Attribute for Error Reporting During Validation" for information.

   
   

4. Each time a custom tag belonging to this library (the library associated with the TLV class) is encountered, it is checked for a tag-extra-info class. If one is specified, then it is instantiated by the JSP container and its isValid() method is called to validate the attributes of the tag. The isValid() method returns true if this validation is successful, or false if not.

Validation Mechanisms

The XML view of a JSP page cannot generally be validated against a DTD and does not include a DOCTYPE statement. There are various namespace-aware mechanisms that you can use for validation. One mechanism in particular is the W3C XML Schema language. Refer to the W3C Web site for information:

http://www.w3.org/XML/

More elementary mechanisms might be suitable as well, such as simply verifying that only a certain set of elements are used in a JSP page, or that a certain set of elements are not used in a page.

TLD listener Element

In a TLD file, each <listener> element is at the top level underneath the root <taglib> element. The <listener> element has one subelement, the required <listener-class> element, which specifies the listener class to be instantiated. This would be a class that implements the ServletContextListener, ServletContextAttributeListener, HttpSessionListener, or HttpSessionAttributeListener interface.

Following is an example:

<taglib>
...
   <listener>
      <listener-class>mypkg.MyServletContextListener</listener-class>
   </listener>
...
</taglib>

Activation of Tag Library Event Listeners

When an application starts, the servlet container will make a call to the JSP container to perform the following:

1. Find and access TLD files.

2. Read TLD files to find their <listener> elements.

3. Instantiate and register the listeners.

This is a convenient way to manage application-level and session-level resources that are associated with the usage of a particular tag library. The functionality is essentially the same as for servlet context listeners specified in the web.xml file.

Access of TLD Files for Event Listener Information

You must take certain standard measures to ensure that the JSP container can access TLD files to find their <listener> elements. For general information about TLD file location, accessibility, and packaging, see "Tag Library and TLD Setup and Access". That section includes information about OC4J well-known tag library locations.

Also, generally speaking, for any TLD in the well-known tag library directory, you must specify the tag library in a <taglib> element in the application web.xml file if you want the application to activate any listeners specified in the TLD file. Without this step, TLD files in the shared directory are not accessed to search for their <listener> elements. This is to protect against needless performance impact for any application that does not use a tag library that happens to be in the shared directory. The <taglib> element in web.xml is not required, however, if you are using persistent TLD caching (described in "Oracle Extensions for Tag Library Sharing and Persistent TLD Caching").

Example: Using the IterationTag Interface

This sample shows the use of a custom tag, myIterator, to make the current item in a collection available as a scripting variable. It defines a scripting variable through a <variable> element in the TLD file.

For complete information about this example, including unpacking and deploying it, refer to the following Oracle Technology Network Web site:

http://www.oracle.com/technology/tech/java/oc4j/htdocs/how-to-jsp-iterationtag.html

(You must register for membership, but registration is free of charge.)

<%@ page contentType="text/html;charset=windows-1252"%> 
<HTML> 
<HEAD> 
<TITLE> 
JSP 1.2 IterationTag Sample 
</TITLE> 
</HEAD> 
<%@ taglib uri="/WEB-INF/exampleiterator.tld" prefix="it"%> 
<BODY> 

<% java.util.Vector vector = new java.util.Vector(); 
   vector.addElement("One"); 
   vector.addElement("Two"); 
   vector.addElement("Three"); 
   vector.addElement("Four"); 
   vector.addElement("Five"); 
%> 
  Collection to Iterate over is <%=vector%> ..... <p> 

 <B>Iterating ...</B><br> 
 <it:myIterator collection="<%= vector%>" > 
      Item  <B><%= item%></B><br> 
 </it:myIterator> 
</p> 
</BODY> 
</HTML> 

package oracle.taglib; 

import java.util.*; 
import javax.servlet.jsp.*; 
import javax.servlet.jsp.tagext.*; 

/** 
 * MyIteratorTag extends TagSupport. The TagSupport class in JSP 1.2 implements the IterationTag 
 */ 

public class MyIteratorTag extends TagSupport 
{ 
  private Iterator iterator; 
  private Collection _collection; 

  public void setCollection(Collection collection) 
  { 
        this._collection = collection; 
  } 

  public int doStartTag() throws JspTagException 
  { 
    if (_collection == null) 
    { 
      throw new JspTagException("No collection with name " 
        + _collection 
        + " found"); 
    } 

    iterator = _collection.iterator(); 
    if (iterator.hasNext()) 
    { 
      pageContext.setAttribute("item", iterator.next()); 
      return EVAL_BODY_INCLUDE; 
    } 
    else 
    { 
       return SKIP_BODY; 
    } 
  } 

  public int doAfterBody() 
  { 

     if (iterator.hasNext()) 
     { 
      pageContext.setAttribute("item", iterator.next()); 
      return EVAL_BODY_AGAIN; 
     } 
     else 
     { 
      return SKIP_BODY; 
     } 
  } 

}

<?xml version = '1.0' encoding = 'windows-1252'?> 
<!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>1.0</tlib-version> 
   <jsp-version>1.2</jsp-version> 
   <short-name>iterate</short-name> 
   <description>This tag lib implements new JSP 1.2 IterationTag
                interface</description> 
   <tag> 
      <name>myIterator</name> 
      <tag-class>oracle.taglib.MyIteratorTag</tag-class> 
      <body-content>JSP</body-content> 
      <attribute> 
          <name>collection</name> 
          <required>true</required> 
          <rtexprvalue>true</rtexprvalue> 
      </attribute> 
      <variable> 
        <name-given>item</name-given> 
        <variable-class>java.lang.Object</variable-class> 
        <declare>true</declare> 
        <!-- default scope: nested --> 
        <description>Scripting Variable item</description> 
      </variable> 
    </tag> 
</taglib>

Example: Using the IterationTag Interface and a Tag-Extra-Info Class

This section provides an end-to-end example of the definition and use of a custom tag, loop, that is used to iterate through the tag body a specified number of times. It defines a scripting variable through a tag-extra-info class.

This example includes the following:

• JSP source code for a page that uses the tag

• Source code for the tag handler class

• Source code for the tag-extra-info class

• TLD file

<%@ taglib uri="/WEB-INF/exampletag.tld" prefix="foo" %>
<% int num=5; %>
<br>
<pre>
<foo:loop index="i" count="<%=num%>">
body1here: i expr: <%=i%> 
           i property: <jsp:getProperty name="i" property="value" /> 
  <foo:loop index="j" count="3">
  body2here: j expr: <%=j%> 
  i property: <jsp:getProperty name="i" property="value" />
  j property: <jsp:getProperty name="j" property="value" /> 
  </foo:loop>
</foo:loop>
</pre>

package examples;

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import java.util.Hashtable;
import java.io.Writer;
import java.io.IOException;
import oracle.jsp.jml.JmlNumber;

public class ExampleLoopTag 
    extends TagSupport
{
    
    String index;
    int count;
    int i;
    JmlNumber ib;

    public ExampleLoopTag() {
      resetAttr();
    }

    public void release() {
      resetAttr();
    }

    private void resetAttr() {
      index=null;
      count=0;
      i=0;
      ib=null;
    }

    public void setIndex(String index)
    {
      this.index=index;
    }
    public void setCount(String count)
    {
      this.count=Integer.parseInt(count);
    }

    public int doStartTag() throws JspException {
        ib=new JmlNumber();
        pageContext.setAttribute(index, ib);
        i++;
        ib.setValue(i);
        return EVAL_BODY_INCLUDE;
    }

    public int doAfterBody() throws JspException {
        if (i >= count) {
            return SKIP_BODY;
        } else
            pageContext.setAttribute(index, ib);
        i++;
        ib.setValue(i);
        return EVAL_BODY_AGAIN;
    }
}

package examples;

import javax.servlet.jsp.tagext.*;

public class ExampleLoopTagTEI extends TagExtraInfo {
    public VariableInfo[] getVariableInfo(TagData data) {
        return new VariableInfo[] 
            {
                new VariableInfo(data.getAttributeString("index"),
                                 "oracle.jsp.jml.JmlNumber",
                                 true,
                                 VariableInfo.NESTED)
            };
    }

    public boolean isValid(TagData data)
    {
      String countStr=data.getAttributeString("count");
      if (countStr!=null)   // for request-time case
      {
        try {
          int count=Integer.parseInt(countStr);
        }
        catch (NumberFormatException e)
        {
          return false;
        }
      }
      return true;
    }
}

<?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>1.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  <short-name>simple</short-name>
  <description>
       A simple tab library for the examples
  </description>
  <!-- example tag -->
  <!-- for loop -->
  <tag>
    <name>loop</name>
    <tag-class>examples.ExampleLoopTag</tag-class>
    <tei-class>examples.ExampleLoopTagTEI</tei-class>
    <body-content>JSP</body-content>
    <description>for loop</description>
    <attribute>
        <name>index</name>
        <required>true</required>
    </attribute>
    <attribute>
        <name>count</name>
        <required>true</required>
        <rtexprvalue>true</rtexprvalue>
    </attribute>
  </tag>
</taglib>

General Compile-Time Versus Runtime Considerations

The JSP specification describes a runtime support mechanism for custom tag libraries. This mechanism, using an XML-style TLD file to specify the tags, is covered earlier in this chapter. Creating and using a tag library that adheres to this model generally assures that the library will be portable to any standard JSP environment.

There are, however, reasons to consider compile-time implementations:

• A compile-time implementation can produce more efficient code.

• A compile-time implementation allows the developer to catch errors during translation and compilation, instead of the user seeing them at runtime.

JSP Compile-Time Versus Runtime JML Library

OC4J provides a portable tag library called the JSP Markup Language (JML) library. This library uses the standard JSP 1.2 runtime mechanism.

However, the JML tags are also supported through a compile-time mechanism. This is because the tags were first introduced with JSP implementations that preceded the JSP 1.1 specification, which is when the runtime mechanism was introduced. The compile-time tags are still supported for backward compatibility.

The general advantages and disadvantages of compile-time implementations apply to the Oracle JML tag library as well. There might be situations where it is advantageous to use the compile-time JML implementation. There are also a few additional tags in that implementation, and some additional expression syntax that is supported.

The Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference describes both the runtime version and the compile-time version of the JML library.