Tag Handler

The Tag Handler is responsible for the interaction between the JSP page and additional server-side objects. The handler is invoked during the execution of a JSP page when a custom tag is encountered. The doStartTag() and doEndTag() methods are invoked when the start and end custom tags, respectively, are encountered. The release() method releases resources allocated by the tag handler.

There are two interfaces that describe a tag handler:

The Tag Handler has two main action methods:

doStartTag() returns the following:

• EVAL_BODY_INCLUDE
  • process the body of the action but do not create a new BodyContent. Pass the body through without manipulating it. Only valid if you DON'T implement the BodyTag interface.
• EVAL_BODY_TAG
  • process the body of the action and create a new BodyContent. Only valid if you DO implement the BodyTag interface.
• SKIP_BODY
  • do not evaluate the body of the tag

doEndTag() returns the following:

• EVAL_PAGE
  • the rest of the JSP page will be evaluated
• SKIP_PAGE
  • the rest of the JSP page will not be evaluated

The return values direct the JSP container on how to evaluate the rest of the JSP page. The release() method releases resources allocated by the tag handler.

TagSupport and BodyTagSupport are subclasses of Tag and can be used as base classes when creating new tag handlers.

The TagSupport class is a utility class that implements the Tag interface and adds additional convenience methods including:

• getter method for Tag properties

If the tag handler manipulates the body of an action, it must implement the BodyTag interface. doStartTag() must return EVAL_BODY_TAG in order for the body of the tag to be evaluated. If SKIP_BODY is returned, the body will be ignored. Methods that interact with the body content include:

The BodyTagSupport class implements the BodyTag interface and adds additional convenience methods. Some of these methods include:

• getter for the bodyContent property
• getter for the previous out JSPWriter

In a Web Application handlers must reside in one of the following standard locations for Java classes:

• in a JAR file in the /WEB-INF/lib directory
• in a directory in the /WEB-INF/classes directory

A tag handler has access to some properties that are set by the JSP container using setter methods. This includes the pageContext and parent objects. The tag handler also has access to server-side objects and enclosing actions. If the tag is nested, the parent handler of the enclosing tag can be accessed by using either:

• TagSupport.getParent()
• TagSupport.findAncestorWithClass(from, class)

The parent handler's statically and dynamically created objects can be obtained once the parent object is retrieved.

Tag Library Descriptor

The Tag Library Descriptor (TLD) is used by the JSP container to interpret pages that include the taglib directives referring to that tag library. It is an XML document that maps action tags to tag handler classes. You can locate a TLD in two ways:

• web.xml taglib element
  • taglib-uri
    • uri identifying a Tag Library
  • taglib-location
    • location, as a resource, where the TLD file can be found
• default mapping

You can find more information about the web.xml taglib element in the Servlet 2.2 and JSP 1.1 specifications.

You will need to explicitly reference the external DOCTYPE because of a recent change to call the validating parser:

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

The TLD taglib element is the document root. It has the following subelements:

The tag element defines an action in the tag library. It may have several subelements that define the action:

bodycontent is included if the tag has a body. It is used by page composition tools so it does not affect the composition of the body. It can be one of the three following types:

• JSP (default)
  • the JSP container should evaluate any body of the tag, but it can also be empty
• tagdependent
  • any body of the tag would be handled by the tag itself, but it can also be empty
• empty
  • body must be empty

the teiclass defines the scripting variable and includes the following information:

• name
• type
• whether variable needs to be created or not
• scope

attributes can have the following fields:

• name (required)
  • attribute name
• required
  • if attribute is required or optional
• rtexprvalue
  • if attribute value may be dynamically calculated at runtime by a scriptlet. NOTE: default value is "false", meaning that the attribute has a static value. Make sure you set it to "true" if the attribute value is determined at request time.

For every attribute you must have a JavaBeans style get and set methods in the Tag Handler. If your attribute is named id, the TagSupport class defines the setId() and getId() methods for you.

JavaServer Pages

JavaServer Pages can handle XML content encapsulated in Tag Library actions.

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

To use a Tag Library, you need to tell the JSP container where it is located using a taglib directive. The directive must come before any actions.

• The "identifier" will need to match the one used in <taglib-uri> in the web.xml file.
• The "prefix" distinguishes which tag library will be used.

Installation and Deployment

  META-INF/
  META-INF/MANIFEST.MF
  WEB-INF/
  WEB-INF/classes/
  WEB-INF/lib/
  WEB-INF/lib/{tagLibrary}.jar
  WEB-INF/web.xml
  WEB-INF/{tagLibrary}.tld

Examples

Some examples include:

• Basic Tag
• Simple Nested Tag
• UtilityTags Library Documentation

Basic Tag

This basic tag is the "Hello World" example. The text "Hello World" will print whenever the tag is encountered.

• Tag Handler
• Tag Library Descriptor
• web.xml file
• JSP

  package basic;

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

    public int doStartTag() throws JspException {
        try {
            pageContext.getOut().print("Hello World");
        } catch (Exception ex) {
            throw new JspException("IO problems");
        }
        return SKIP_BODY;
    }

  <?xml version="1.0" encoding="ISO-8859-1" ?>

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

  <taglib>
    <!-- The version number of this tag library -->
    <tlibversion>1.0</tlibversion>

    <!-- The JSP specification version required to function -->
    <jspversion>1.1</jspversion>

    <!-- The short name of this tag library -->
    <shortname>utility</shortname>

    <!-- Public URI that uniquely identifies this version of the tag library -->
    <uri>http://jakarta.apache.org/taglibs/utilitytags</uri>

    <!-- General information about this tag library -->
    <info>
          A simple tag library for the examples
    </info>

  <!-- Hello tag -->
    <tag>
      <name>Hello</name>
      <tagclass>basic.Hello</tagclass>
      <bodycontent>empty</bodycontent>
      <info>
        Print Hello World
      </info>
    </tag>

  <web-app>
    <taglib>
       <taglib-uri>
         http://jakarta.apache.org/taglibs/utilitytags
       </taglib-uri>
       <taglib-location>
         /WEB-INF/tld/utilitytags.tld
       </taglib-location>
    </taglib>
  </web-app>

  <%@ taglib uri="http://jakarta.apache.org/taglibs/utilitytags" prefix="jLib" %>

  <jLib:Hello/>

Simple Nested Action

This nested tag is an example of an "If" conditional tag. Based on the value of the attribute the included scriptlet will be evaluated or skipped.

• Tag Handler
• Tag Library Descriptor
• web.xml file
• JSP

  public class IfTag extends BodyTagSupport {

  public int doStartTag() {
    if (getPredicate()) return EVAL_BODY_TAG;
    else return SKIP_BODY;
  }

  public int doAfterBody() throws JspException {
    try {
      bodyContent.writeOut(bodyContent.getEnclosingWriter());
      return SKIP_BODY;
    } catch (IOException ex) {
      throw new JspTagException(ex.toString());
    }
  }

  <!-- IF tag -->
    <tag>
      <name>If</name>
      <tagclass>lang.IfTag</tagclass>

      <attribute>
        <name>predicate</name>
        <required>true</required>
        <rtexprvalue>true</rtexprvalue>
      </attribute>
      <info>
        Conditional Tag.
      </info>
    </tag>  

  <jlib:if predicate="<%= x==5 %>">
    <jLib:Hello/>   
  </jlib:if>

Documentation for the UtilityTags Tag Library

    <%@ taglib uri="http://jakarta.apache.org/taglibs/utilitytags" prefix="x" %>