|
SunONE Application Server v8.0 PE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
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.
Field Summary | |
static int |
EVAL_BODY_INCLUDE
Evaluate body into existing out stream. |
static int |
EVAL_PAGE
Continue evaluating the page. |
static int |
SKIP_BODY
Skip body evaluation. |
static int |
SKIP_PAGE
Skip the rest of the page. |
Method Summary | |
int |
doEndTag()
Process the end tag for this instance. |
int |
doStartTag()
Process the start tag for this instance. |
Tag |
getParent()
Get the parent (closest enclosing tag handler) for this tag handler. |
void |
release()
Called on a Tag handler to release state. |
void |
setPageContext(PageContext pc)
Set the current page context. |
void |
setParent(Tag t)
Set the parent (closest enclosing tag handler) of this tag handler. |
Field Detail |
public static final int SKIP_BODY
public static final int EVAL_BODY_INCLUDE
public static final int SKIP_PAGE
public static final int EVAL_PAGE
Method Detail |
public void setPageContext(PageContext pc)
This value is *not* reset by doEndTag() and must be explicitly reset by a page implementation if it changes between calls to doStartTag().
pc
- The page context for this tag handler.public void setParent(Tag t)
This value is *not* reset by doEndTag() and must be explicitly reset by a page implementation.
t
- The parent tag, or null.public Tag getParent()
The getParent() method can be used to navigate the nested tag handler structure at runtime for cooperation among custom actions; for example, the findAncestorWithClass() method in TagSupport provides a convenient way of doing this.
The current version of the specification only provides one formal way of indicating the observable type of a tag handler: its tag handler implementation class, described in the tag-class subelement of the tag element. This is extended in an informal manner by allowing the tag library author to indicate in the description subelement an observable type. The type should be a subtype of the tag handler implementation class or void. This addititional constraint can be exploited by a specialized container that knows about that specific tag library, as in the case of the JSP standard tag library.
TagSupport.findAncestorWithClass(javax.servlet.jsp.tagext.Tag, java.lang.Class)
public int doStartTag() throws JspException
The doStartTag method assumes that the properties pageContext and parent have been set. It also assumes that any properties exposed as attributes have been set too. When this method is invoked, the body has not yet been evaluated.
This method returns Tag.EVAL_BODY_INCLUDE or BodyTag.EVAL_BODY_BUFFERED to indicate that the body of the action should be evaluated or SKIP_BODY to indicate otherwise.
When a Tag returns EVAL_BODY_INCLUDE the result of evaluating the body (if any) is included into the current "out" JspWriter as it happens and then doEndTag() is invoked.
BodyTag.EVAL_BODY_BUFFERED is only valid if the tag handler implements BodyTag.
The JSP container will resynchronize the values of any AT_BEGIN and NESTED variables (defined by the associated TagExtraInfo or TLD) after the invocation of doStartTag(), except for a tag handler implementing BodyTag whose doStartTag() method returns BodyTag.EVAL_BODY_BUFFERED.
JspException
- if an error occurred while processing this tagBodyTag
public int doEndTag() throws JspException
This method will be called after returning from doStartTag. The body of the action may or may not have been evaluated, depending on the return value of doStartTag.
If this method returns EVAL_PAGE, the rest of the page continues to be evaluated. If this method returns SKIP_PAGE, the rest of the page is not evaluated, the request is completed, and the doEndTag() methods of enclosing tags are not invoked. If this request was forwarded or included from another page (or Servlet), only the current page evaluation is stopped.
The JSP container will resynchronize the values of any AT_BEGIN and AT_END variables (defined by the associated TagExtraInfo or TLD) after the invocation of doEndTag().
JspException
- if an error occurred while processing this tagpublic void release()
|
SunONE Application Server v8.0 PE | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2003 Sun Microsystems, Inc. All rights reserved.