javax.servlet.jsp.tagext
Interface Tag

All Known Subinterfaces:
BodyTag, IterationTag

public interface Tag

The interface of a simple 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).

Release

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.

Lifecycle

Lifecycle details are described by the transition diagram below, with the following comments:


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

SKIP_BODY

public static final int SKIP_BODY
Skip body evaluation. Valid return value for doStartTag and doAfterBody.

EVAL_BODY_INCLUDE

public static final int EVAL_BODY_INCLUDE
Evaluate body into existing out stream. Valid return value for doStartTag. This is an illegal return value for doStartTag when the class implements BodyTag, since BodyTag implies the creation of a new BodyContent.

SKIP_PAGE

public static final int SKIP_PAGE
Skip the rest of the page. Valid return value for doEndTag.

EVAL_PAGE

public static final int EVAL_PAGE
Continue evaluating the page. Valid return value for doEndTag().
Method Detail

setPageContext

public void setPageContext(PageContext pc)
Set the current page context. This method is invoked by the JSP page implementation object prior to doStartTag().

This value is *not* reset by doEndTag() and must be explicitly reset by a page implementation if it changes between calls to doStartTag().

Parameters:
pc - The page context for this tag handler.

setParent

public void setParent(Tag t)
Set the parent (closest enclosing tag handler) of this tag handler. Invoked by the JSP page implementation object prior to doStartTag().

This value is *not* reset by doEndTag() and must be explicitly reset by a page implementation.

Parameters:
t - The parent tag, or null.

getParent

public Tag getParent()
Get the parent (closest enclosing tag handler) for this tag handler. This method is used by the findAncestorWithClass() method in TagSupport.

doStartTag

public int doStartTag()
               throws JspException
Process the start tag for this instance. This method is invoked by the JSP page implementation object.

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 any variable values that are indicated as so in TagExtraInfo after the invocation of doStartBody().

Throws:
JspException. -  
See Also:
BodyTag

doEndTag

public int doEndTag()
             throws JspException
Process the end tag for this instance. This method is invoked by the JSP page implementation object on all Tag handlers.

This method will be called after returning from doStartTag. The body of the action may or 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 and the request is completed. If this request was forwarded or included from another page (or Servlet), only the current page evaluation is completed.

The JSP container will resynchronize any variable values that are indicated as so in TagExtraInfo after the invocation of doEndBody().

Throws:
JspException. -  

release

public void release()
Called on a Tag handler to release state. The page compiler guarantees that JSP page implementation objects will invoke this method on all tag handlers, but there may be multiple invocations on doStartTag and doEndTag in between.


Copyright (c) 1999-2000 The Apache Software Foundation. All Rights Reserved.