The interface of a classic tag handler that does not want to manipulate
its body. The Tag interface defines the basic protocol between a Tag
handler and JSP page implementation class. It defines the life cycle
and the methods to be invoked at start and end tag.
Properties
The Tag interface specifies the setter and getter methods for the core
pageContext and parent properties.
The JSP page implementation object invokes setPageContext and
setParent, in that order, before invoking doStartTag() or doEndTag().
Methods
There are two main actions: doStartTag and doEndTag. Once all
appropriate properties have been initialized, the doStartTag and
doEndTag methods can be invoked on the tag handler. Between these
invocations, the tag handler is assumed to hold a state that must
be preserved. After the doEndTag invocation, the tag handler is
available for further invocations (and it is expected to have
retained its properties).
Lifecycle
Lifecycle details are described by the transition diagram below,
with the following comments:
[1] This transition is intended to be for releasing long-term data.
no guarantees are assumed on whether any properties have been retained
or not.
[2] This transition happens if and only if the tag ends normally
without raising an exception
[3] Some setters may be called again before a tag handler is
reused. For instance, setParent() is called if it's
reused within the same page but at a different level,
setPageContext() is called if it's used in another page,
and attribute setters are called if the values differ or are expressed
as request-time attribute values.
Check the TryCatchFinally interface for additional details related
to exception handling and resource management.
Once all invocations on the tag handler
are completed, the release method is invoked on it. Once a release
method is invoked all properties, including parent and
pageContext, are assumed to have been reset to an unspecified value.
The page compiler guarantees that release() will be invoked on the Tag
handler before the handler is released to the GC.
Empty and Non-Empty Action
If the TagLibraryDescriptor file indicates that the action must
always have an empty action, by an <body-content> entry of "empty",
then the doStartTag() method must return SKIP_BODY.
Otherwise, the doStartTag() method may return SKIP_BODY or
EVAL_BODY_INCLUDE.
If SKIP_BODY is returned the body, if present, is not evaluated.
If EVAL_BODY_INCLUDE is returned, the body is evaluated and
"passed through" to the current out.
Properties
The Tag interface specifies the setter and getter methods for the core pageContext and parent properties.
The JSP page implementation object invokes setPageContext and setParent, in that order, before invoking doStartTag() or doEndTag().
Methods
There are two main actions: doStartTag and doEndTag. Once all appropriate properties have been initialized, the doStartTag and doEndTag methods can be invoked on the tag handler. Between these invocations, the tag handler is assumed to hold a state that must be preserved. After the doEndTag invocation, the tag handler is available for further invocations (and it is expected to have retained its properties).
Lifecycle
Lifecycle details are described by the transition diagram below, with the following comments:
setParent()is called if it's reused within the same page but at a different level,setPageContext()is called if it's used in another page, and attribute setters are called if the values differ or are expressed as request-time attribute values.Once all invocations on the tag handler are completed, the release method is invoked on it. Once a release method is invoked all properties, including parent and pageContext, are assumed to have been reset to an unspecified value. The page compiler guarantees that release() will be invoked on the Tag handler before the handler is released to the GC.
Empty and Non-Empty Action
If the TagLibraryDescriptor file indicates that the action must always have an empty action, by an <body-content> entry of "empty", then the doStartTag() method must return SKIP_BODY.
Otherwise, the doStartTag() method may return SKIP_BODY or EVAL_BODY_INCLUDE.
If SKIP_BODY is returned the body, if present, is not evaluated.
If EVAL_BODY_INCLUDE is returned, the body is evaluated and "passed through" to the current out.