A tag handler describes the semantics of the action that results from use of a custom tag. A tag handler is an instance of a Java class that implements one of two standard Java interfaces, depending on whether the tag processes a body of statements (between a start tag and an end tag).
Each tag has its own handler class. By convention, the name of the tag handler class for a tag abc, for example, is AbcTag.
The tag library description file of a tag library specifies the name of the tag handler class for each tag in the library. (See "Tag Library Description Files" on page 7-10.) A tag handler instance is a server-side object used at request-time. It 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 custom tag is nested within an outer custom tag.
See "Sample Tag Handler Class: ExampleLoopTag.java" on page 7-15 for sample code of a tag handler class.
Custom Tag Body Processing
Custom tags, as with standard JSP tags, may or may not have a body. In the case of a custom tag, even when there is a body, it may not need special processing by the tag handler.
Note: Beginning with Oracle9iAS 9.0.2, the OC4J JSP container properly handles tag attributes that represent object types
(java.lang.Object). A string specified as the value of such an attribute is converted to a java.lang.Object instance and passed in to the corresponding setter method in the tag handler instance. This features complies with the JSP 1.2 specification.
Note: The Sun Microsystems JavaServer Pages Specification, Version 1.1 does not mandate whether multiple uses of the same custom tag within a JSP page should use the same or different tag handler instances—this is left to the discretion of JSP vendors. See "OC4J JSP Tag Handler Features" on page 7-19 for information about the Oracle implementation.
Standard Tag Library Framework
There are three possible situations:
■ There is no body.
In this case, there is just a single tag, as opposed to a start tag and end tag.
Following is a general example:
<oracust:abcdef attr1="...", attr2="..." />
■ There is a body that does not need special handling by the tag handler.
In this case, there is a start tag and 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:
<foo:if cond="<%= ... %>" >
...body executed if cond is true, but not processed by tag handler...
</foo:if>
■ There is a body that needs special processing by the tag handler.
In this case also, there is a start tag and end tag with a body of statements in between; however, the tag handler must process the body.
<oracust:ghijkl attr1="...", attr2="..." >
...body processed by tag handler...
</oracust:ghijkl>
Integer Constants for Body Processing
The tag handling interfaces that are described in the following sections specify a doStartTag() method (further described below) that you must implement to return an appropriate int constant, depending on the situation. The possible return values are as follows:
■ SKIP_BODY if there is no body or if evaluation and execution of the body should be skipped
■ EVAL_BODY_INCLUDE if there is a body that does not require special processing by the tag handler
■ EVAL_BODY_TAG if there is a body that requires special processing by the tag handler
Handlers for Tags That Do Not Process a Body
For a custom tag that does not have a body, or has a body that does not need special processing by the tag handler, the tag handler class must directly or indirectly implement the following standard interface:
■ javax.servlet.jsp.tagext.Tag
The following standard support class implements the Tag interface and can be used as a base class:
■ javax.servlet.jsp.tagext.TagSupport
The Tag interface specifies a doStartTag() method and a doEndTag() method.
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.
Action processing—whatever you want the action tag to accomplish—is implemented 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 doStartTag() method returns an integer value. For a tag handler class implementing the Tag interface (either directly or indirectly), this value must be either SKIP_BODY or EVAL_BODY_INCLUDE (described in "Integer Constants for Body Processing" above). EVAL_BODY_TAG is illegal for a tag handler class implementing the Tag interface.
Handlers for Tags That Process a Body
For a custom tag with a body that requires special processing by the tag handler, the tag handler class must directly or indirectly implement the following standard interface:
■ javax.servlet.jsp.tagext.BodyTag
The following standard support class implements the BodyTag interface and can be used as a base class:
■ javax.servlet.jsp.tagext.BodyTagSupport
The BodyTag interface specifies a doInitBody() method and a doAfterBody() method in addition to the doStartTag() and doEndTag() methods specified in the Tag interface.
Standard Tag Library Framework
Just as with tag handlers implementing the Tag interface (described in the preceding section, "Handlers for Tags That Do Not Process a Body"), the tag
developer implements the doStartTag() method for action processing by the tag, and the doEndTag() method for any post-processing.
The doStartTag() method returns an integer value. For a tag handler class implementing the BodyTag interface (directly or indirectly), this value must be either SKIP_BODY or EVAL_BODY_TAG (described in "Integer Constants for Body Processing" on page 7-5). EVAL_BODY_INCLUDE is illegal for a tag handler class implementing the BodyTag interface.
In addition to implementing the doStartTag() and doEndTag() methods, the tag developer, as appropriate, provides code for the doInitBody() method, to be invoked before the body is evaluated, and the doAfterBody() method, to be invoked after each evaluation of the body. The body could be evaluated multiple times, such as at the end of each iteration of a loop. The JSP page implementation class generated by the JSP translator includes appropriate calls to all of these methods.
After the doStartTag() method is executed, the doInitBody() and
doAfterBody() methods are executed if the doStartTag() method returned EVAL_BODY_TAG.
The doEndTag() method is executed after any body processing, when the end tag is encountered.
For custom tags that must process a body, the
javax.servlet.jsp.tagext.BodyContent class is available. This is a subclass of javax.servlet.jsp.JspWriter that you can use to process body
evaluations so that they can be re-extracted later. The BodyTag interface includes a setBodyContent() method that the JSP container can use to give a
BodyContent handle to a tag handler instance.