Tag (Java EE 5)

属性

Tag 接口指定了用于核心 pageContext 和父属性的 setter 和 getter 方法。

JSP 页面实现对象调用 setPageContext 和 setParent，其顺序是在调用 doStartTag() 或 doEndTag() 之前。

方法

有两个主要操作：doStartTag 和 doEndTag。一旦已经初始化所有适当属性，就可以对标记处理程序调用 doStartTag 和 doEndTag 方法。在这些调用之间，假定标记处理程序保存了其必须保留的状态。在调用 doEndTag 之后，标记处理程序可用于进一步的调用（并且它应该已经保留了其属性）。

生命周期

以下的转换图和注释描述了生命周期的详细信息。

• [1] 此转换旨在释放长期数据。不能保证是否已经保留了任何属性。
• [2] 当且仅当标记正常结束，未引发异常时发生此转换。
• [3] 在重用标记处理程序之前，可以再次调用某些 setter。例如，如果在同一页面内但在不同级别上重用标记处理程序，则调用 setParent()，如果在另一个页面中使用标记处理程序，则调用 setPageContext()，如果值不同或者它们被表示为请求期间属性值，则调用属性的 setter 方法。
• 查阅 TryCatchFinally 接口，获得与异常处理和资源管理有关的其他详细信息。

一旦完成了标记处理程序上的所有调用，就对它调用 release 方法。一旦调用了 release 方法，就会假定所有 属性（包括父属性和 pageContext）都已重置为未指定的值。页面编译器可以保证，将在处理程序被释放到 GC 之前对标记处理程序调用 release()。

空操作和非空操作

如果 TagLibraryDescriptor 文件指示操作必须总是有一个空操作（通过 "empty" 的 <body-content> 条目），则 doStartTag() 方法必须返回 SKIP_BODY。

否则，doStartTag() 方法可能返回 SKIP_BODY 或 EVAL_BODY_INCLUDE。

如果返回 SKIP_BODY，则不会对正文（如果存在）求值。

如果返回 EVAL_BODY_INCLUDE，则对正文求值并“传递”到当前 out。

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.

英文文档：

SKIP_BODY

static final int SKIP_BODY

Skip body evaluation. Valid return value for doStartTag and doAfterBody.

See Also:

Constant Field Values

英文文档：

EVAL_BODY_INCLUDE

static final int EVAL_BODY_INCLUDE

Evaluate body into existing out stream. Valid return value for doStartTag.

See Also:

Constant Field Values

英文文档：

SKIP_PAGE

static final int SKIP_PAGE

Skip the rest of the page. Valid return value for doEndTag.

See Also:

Constant Field Values

英文文档：

EVAL_PAGE

static final int EVAL_PAGE

Continue evaluating the page. Valid return value for doEndTag().

See Also:

Constant Field Values

public void setPageContext(PageContext pc)
设置当前页面上下文。此方法由 JSP 页面实现对象在调用 doStartTag() 之前调用。

如果在 doStartTag() 调用之间此值发生变化，则*不*要通过 doEndTag() 重置此值，而必须通过页面实现显式重置它。

pc	此标记处理程序的页面上下文。

英文文档：

setPageContext

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.

public void setParent(Tag t)
设置此标记处理程序的父标记处理程序（最接近的封闭标记处理程序）。由 JSP 页面实现对象在调用 doStartTag() 之前调用。

*不*要通过 doEndTag() 重置此值，必须通过页面实现显式重置它。

t	父标记，或 null。

英文文档：

setParent

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.

public Tag getParent()
获取此标记处理程序的父标记处理程序（最接近的封闭标记处理程序）。

可使用 getParent() 方法在运行时导航嵌套的标记处理程序结构，以便在各自定义操作之间合作；例如，TagSupport 中的 findAncestorWithClass() 方法提供了一个实现此操作的便捷方式。

规范的当前版本仅提供一种正式方法指示标记处理程序的 observable 类型：其标记处理程序实现类，在标记元素的标记类子元素中描述。这可以通过一种非正式的方法扩展，即允许标记库作者在描述子元素中指示 observable 类型。该类型应该是标记处理程序实现类的子类型或者是 void 类型。支持特定标记库（比如 JSP 标准标记库）的专门化容器可以利用这一附加限制。

return	当前的父标记处理程序，如果不存在，则返回 null。
See also	findAncestorWithClass

英文文档：

getParent

Tag getParent()

Get the parent (closest enclosing tag handler) for this tag handler.

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.

Returns:

the current parent, or null if none.

See Also:

TagSupport.findAncestorWithClass(javax.servlet.jsp.tagext.Tag, java.lang.Class)

public int doStartTag() throws JspException
处理此实例的开始标记。此方法由 JSP 页面实现对象调用。

doStartTag 方法假定已经设置了属性 pageContext 和父属性。它还假定任何公开为属性的属性也已经进行了设置。在调用此方法时，尚未对正文求值。

此方法返回 Tag.EVAL_BODY_INCLUDE 或 BodyTag.EVAL_BODY_BUFFERED，指示应该对操作正文求值，或者返回 SKIP_BODY，指示不对正文求值。

当 Tag 返回 EVAL_BODY_INCLUDE 时，对正文（如果有）求值的结果将包含在当前 "out" JspWriter 中，然后调用 doEndTag()。

BodyTag.EVAL_BODY_BUFFERED 只在标记处理程序实现了 BodyTag 时有效。

在调用 doStartTag() 之后，JSP 容器将重新同步所有 AT_BEGIN 和 NESTED 变量（由关联的 TagExtraInfo 或 TLD 定义）的值，除了实现了 BodyTag 而该 BodyTag 的 doStartTag() 方法返回 BodyTag.EVAL_BODY_BUFFERED 的标记处理程序。

return	如果标记想处理正文，则返回 EVAL_BODY_INCLUDE，如果标记不想处理正文，则返回 SKIP_BODY。
Throws	JspException: 如果在处理此标记时发生错误
See also	javax.servlet.jsp.tagext.BodyTag

英文文档：

doStartTag

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 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.

Returns:

EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY if it does not want to process it.

Throws:

JspException - if an error occurred while processing this tag

See Also:

BodyTag

public int doEndTag() throws JspException
处理此实例的结束标记。由 JSP 页面实现对象对所有标记处理程序调用此方法。

此方法将在从 doStartTag 返回后调用。可能已经对操作正文求值，也可能未求值，取决于 doStartTag 的返回值。

如果此方法返回 EVAL_PAGE，则将继续对页面的其余部分求值。如果此方法返回 SKIP_PAGE，则不对页面其余部分求值，完成请求，且不调用封闭标记的 doEndTag() 方法。如果此请求被转发或包含到另一个页面（或 Servlet）中，则仅停止对当前页面的求值。

在调用 doEndTag() 之后，JSP 容器将重新同步所有 AT_BEGIN 和 AT_END 变量（由关联的 TagExtraInfo 或 TLD 定义）的值。

return	是否继续对 JSP 页面求值的指示。
Throws	JspException: 如果在处理此标记时发生错误

英文文档：

doEndTag

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 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().

Returns:

indication of whether to continue evaluating the JSP page.

Throws:

JspException - if an error occurred while processing this tag

public void release()
对标记处理程序调用，以释放状态。页面编译器保证 JSP 页面实现对象将对所有标记处理程序调用此方法，但之间可能会多次调用 doStartTag 和 doEndTag。

英文文档：

release

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 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.