IterationTag (Java EE 5)

实现 IterationTag 的标记处理程序可被视为实现了与 doStartTag() 和 doEndTag() 方法有关的 Tag 的标记处理程序。IterationTag 提供了一个新方法：doAfterBody()。

doAfterBody() 方法在每次正文求值之后调用，以控制是否对正文重新求值。如果 doAfterBody() 返回 IterationTag.EVAL_BODY_AGAIN，则将对正文重新求值。如果 doAfterBody() 返回 Tag.SKIP_BODY，则将跳过正文并对 doEndTag() 求值。

属性 除了 Tag 中的那些属性之外，没有任何新属性。

方法 有一个新方法：doAfterBody()。

生命周期

以下的转换图描述了生命周期的详细信息。计算 doStartTag()、BODY 和 doAfterBody() 期间抛出的异常将中断执行序列，并向上传播到堆栈，除非标记处理程序实现了 TryCatchFinally 接口；有关详细信息，请参见该接口。

空操作和非空操作

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

注意，在 doStartTag() 之后调用哪些方法取决于返回值和自定义操作元素在 JSP 页面中是否为空，而不取决于它在 TLD 中的声明方式。

如果返回 SKIP_BODY，则不对正文求值，然后调用 doEndTag()。

如果返回 EVAL_BODY_INCLUDE，并且自定义操作元素不为空，则对正文求值并“传递”到当前 out，然后调用 doAfterBody()，并在 0 个或更多迭代之后调用 doEndTag()。

The IterationTag interface extends Tag by defining one additional method that controls the reevaluation of its body.

A tag handler that implements IterationTag is treated as one that implements Tag regarding the doStartTag() and doEndTag() methods. IterationTag provides a new method: doAfterBody().

The doAfterBody() method is invoked after every body evaluation to control whether the body will be reevaluated or not. If doAfterBody() returns IterationTag.EVAL_BODY_AGAIN, then the body will be reevaluated. If doAfterBody() returns Tag.SKIP_BODY, then the body will be skipped and doEndTag() will be evaluated instead.

Properties There are no new properties in addition to those in Tag.

Methods There is one new methods: doAfterBody().

Lifecycle

Lifecycle details are described by the transition diagram below. Exceptions that are thrown during the computation of doStartTag(), BODY and doAfterBody() interrupt the execution sequence and are propagated up the stack, unless the tag handler implements the TryCatchFinally interface; see that interface for details.

Empty and Non-Empty Action

If the TagLibraryDescriptor file indicates that the action must always have an empty element body, by a <body-content> entry of "empty", then the doStartTag() method must return SKIP_BODY.

Note that which methods are invoked after the doStartTag() depends on both the return value and on if the custom action element is empty or not in the JSP page, not on how it's declared in the TLD.

If SKIP_BODY is returned the body is not evaluated, and then doEndTag() is invoked.

If EVAL_BODY_INCLUDE is returned, and the custom action element is not empty, the body is evaluated and "passed through" to the current out, then doAfterBody() is invoked and, after zero or more iterations, doEndTag() is invoked.

英文文档：

EVAL_BODY_AGAIN

static final int EVAL_BODY_AGAIN

Request the reevaluation of some body. Returned from doAfterBody. For compatibility with JSP 1.1, the value is carefully selected to be the same as the, now deprecated, BodyTag.EVAL_BODY_TAG,

See Also:

Constant Field Values

public int doAfterBody() throws JspException
处理正文求值（重求值）。在每次对 BodyEvaluation 对象中的正文求值之后，由 JSP 页面实现对象调用此方法。如果没有正文求值，则不调用该方法。

如果 doAfterBody 返回 EVAL_BODY_AGAIN，则将发生新的正文求值（后面接着另一个 doAfterBody 调用）。如果 doAfterBody 返回 SKIP_BODY，则不会再进行正文求值，并且将调用 doEndTag 方法。

如果此标记处理程序实现了 BodyTag 并且 doAfterBody 返回 SKIP_BODY，则将在调用 doEndTag 之前使用 pageContext 中的 popBody 方法恢复 out 的值。

重新调用该方法可能导致不同的操作，因为共享的状态可能已经发生了某些变化，或者因为进行了外部计算。

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

return	是否需要附加的正文求值
Throws	JspException: 如果在处理此标记时发生错误

英文文档：

doAfterBody

int doAfterBody()
                throws JspException

Process body (re)evaluation. This method is invoked by the JSP Page implementation object after every evaluation of the body into the BodyEvaluation object. The method is not invoked if there is no body evaluation.

If doAfterBody returns EVAL_BODY_AGAIN, a new evaluation of the body will happen (followed by another invocation of doAfterBody). If doAfterBody returns SKIP_BODY, no more body evaluations will occur, and the doEndTag method will be invoked.

If this tag handler implements BodyTag and doAfterBody returns SKIP_BODY, the value of out will be restored using the popBody method in pageContext prior to invoking doEndTag.

The method re-invocations may be lead to different actions because there might have been some changes to shared state, or because of external computation.

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

Returns:

whether additional evaluations of the body are desired

Throws:

JspException - if an error occurred while processing this tag

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.