SimpleTag (Java EE 5)

简单标记处理程序不同于经典标记处理程序，因为它不支持 doStartTag() 和 doEndTag()，SimpleTag 接口提供了一个简单 doTag() 方法，对于任何给定标记调用，只能调用该方法一次。所有标记逻辑、迭代、正文求值等等，都在这一个方法中执行。因此，简单标记处理程序与 BodyTag 具有相等的效力，只是它具有更简单的生命周期和接口。

为了支持正文内容，提供了 setJspBody() 方法。容器使用封装了标记正文的 JspFragment 对象调用 setJspBody() 方法。标记处理程序实现可以对该片段调用 invoke()，根据需要多次对正文求值。

SimpleTag 处理程序必须具有不带参数的公共构造方法。多数 SimpleTag 处理程序应该扩展 SimpleTagSupport。

生命周期

以下是 SimpleTag 生命周期的非标准的简单概述。有关详细信息，请参见 JSP 规范。

1. 新的标记处理程序实例每次都由容器通过调用提供的无参数构造方法创建。与经典标记处理程序不同，简单标记处理程序从不被 JSP 容器缓存和重用。
2. setJspContext() 和 setParent() 方法由容器调用。setParent() 方法只在元素嵌套在另一个标记调用中时调用。
3. 为此标记定义的每个属性的 setter 方法都由容器调用。
4. 如果存在正文，则由容器调用 setJspBody() 方法来设置此标记的正文，以 JspFragment 的形式。如果页面的操作元素为空，则根本不调用此方法。
5. doTag() 方法由容器调用。所有标记逻辑、迭代、正文求值等等都发生在此方法中。
6. doTag() 方法返回，并且同步所有变量。

Interface for defining Simple Tag Handlers.

Simple Tag Handlers differ from Classic Tag Handlers in that instead of supporting doStartTag() and doEndTag(), the SimpleTag interface provides a simple doTag() method, which is called once and only once for any given tag invocation. All tag logic, iteration, body evaluations, etc. are to be performed in this single method. Thus, simple tag handlers have the equivalent power of BodyTag, but with a much simpler lifecycle and interface.

To support body content, the setJspBody() method is provided. The container invokes the setJspBody() method with a JspFragment object encapsulating the body of the tag. The tag handler implementation can call invoke() on that fragment to evaluate the body as many times as it needs.

A SimpleTag handler must have a public no-args constructor. Most SimpleTag handlers should extend SimpleTagSupport.

Lifecycle

The following is a non-normative, brief overview of the SimpleTag lifecycle. Refer to the JSP Specification for details.

1. A new tag handler instance is created each time by the container by calling the provided zero-args constructor. Unlike classic tag handlers, simple tag handlers are never cached and reused by the JSP container.
2. The setJspContext() and setParent() methods are called by the container. The setParent() method is only called if the element is nested within another tag invocation.
3. The setters for each attribute defined for this tag are called by the container.
4. If a body exists, the setJspBody() method is called by the container to set the body of this tag, as a JspFragment. If the action element is empty in the page, this method is not called at all.
5. The doTag() method is called by the container. All tag logic, iteration, body evaluations, etc. occur in this method.
6. The doTag() method returns and all variables are synchronized.

Since:

JSP 2.0

See Also:

SimpleTagSupport

public void doTag() throws JspException, java.io.IOException
容器调用它来调用此标记。此方法的实现由标记库开发人员提供，该实现处理所有标记处理、正文迭代，等等。

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

Throws	JspException: 如果处理此标记时发生错误。
Throws	SkipPageException: 如果（直接或间接）调用此标记的页面停止求值。如果调用的经典标记处理程序返回 SKIP_PAGE，或者调用的简单标记处理程序抛出 SkipPageException，或者调用的 JSP 片段抛出 SkipPageException，则标记文件生成的简单标记处理程序必定抛出此异常。
Throws	java.io.IOException: 如果写入输出流时出现错误。

英文文档：

doTag

void doTag()
           throws JspException,
                  IOException

Called by the container to invoke this tag. The implementation of this method is provided by the tag library developer, and handles all tag processing, body iteration, etc.

The JSP container will resynchronize any AT_BEGIN and AT_END variables (defined by the associated tag file, TagExtraInfo, or TLD) after the invocation of doTag().

Throws:

JspException - If an error occurred while processing this tag.

SkipPageException - If the page that (either directly or indirectly) invoked this tag is to cease evaluation. A Simple Tag Handler generated from a tag file must throw this exception if an invoked Classic Tag Handler returned SKIP_PAGE or if an invoked Simple Tag Handler threw SkipPageException or if an invoked Jsp Fragment threw a SkipPageException.

IOException - If there was an error writing to the output stream.

public void setParent(JspTag parent)
为了进行协作，设置此标记的父标记。

仅当此标记调用嵌套在另一个标记调用中时，容器才调用此方法。

parent

封闭此标记的标记

英文文档：

setParent

void setParent(JspTag parent)

Sets the parent of this tag, for collaboration purposes.

The container invokes this method only if this tag invocation is nested within another tag invocation.

Parameters:

parent - the tag that encloses this tag

public JspTag getParent()
为了进行协作，返回此标记的父标记。

return

此标记的父标记

英文文档：

getParent

JspTag getParent()

Returns the parent of this tag, for collaboration purposes.

Returns:

the parent of this tag

public void setJspContext(JspContext pc)
由容器调用以将此调用的 JspContext 提供给此标记处理程序。实现应该保存此值。

pc	此调用的页面上下文
See also	setPageContext

英文文档：

setJspContext

void setJspContext(JspContext pc)

Called by the container to provide this tag handler with the JspContext for this invocation. An implementation should save this value.

Parameters:

pc - the page context for this invocation

See Also:

Tag.setPageContext(javax.servlet.jsp.PageContext)

public void setJspBody(JspFragment jspBody)
以标记处理程序可以不调用或多次调用的 JspFragment 对象的形式提供此标记的正文。

此方法由 JSP 页面实现对象在调用 doTag() 之前调用。如果页面的操作元素为空，则根本不调用此方法。

jspBody

封装此标记正文的片段。

英文文档：

setJspBody

void setJspBody(JspFragment jspBody)

Provides the body of this tag as a JspFragment object, able to be invoked zero or more times by the tag handler.

This method is invoked by the JSP page implementation object prior to doTag(). If the action element is empty in the page, this method is not called at all.

Parameters:

jspBody - The fragment encapsulating the body of this tag.

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