JspFragment (Java EE 5)

JSP 片段的定义必须仅包含模板文本和 JSP 操作元素。换句话说，它不得包含 scriptlet 或 scriptlet 表达式。在转换期间，容器生成一个能够执行定义的片段的 JspFragment 抽象类实现。

标记处理程序可以不调用或多次调用片段，或者在返回之前将它传递给其他标记。要将值传递给 JSP 片段或从 JSP 片段中获取值，标记处理程序将在与该片段关联的 JspContext 中存储/获取值。

注意，标记库开发人员和页面作者不应手动生成 JspFragment 实现。

实现注意事项：不必为每个片段生成单独的类。一种可能的实现是为实现 JspFragment 的每个页面生成一个 helper 类。在构造时，可传递一个鉴别符来选择该实例将执行哪个片段。

Encapsulates a portion of JSP code in an object that can be invoked as many times as needed. JSP Fragments are defined using JSP syntax as the body of a tag for an invocation to a SimpleTag handler, or as the body of a <jsp:attribute> standard action specifying the value of an attribute that is declared as a fragment, or to be of type JspFragment in the TLD.

The definition of the JSP fragment must only contain template text and JSP action elements. In other words, it must not contain scriptlets or scriptlet expressions. At translation time, the container generates an implementation of the JspFragment abstract class capable of executing the defined fragment.

A tag handler can invoke the fragment zero or more times, or pass it along to other tags, before returning. To communicate values to/from a JSP fragment, tag handlers store/retrieve values in the JspContext associated with the fragment.

Note that tag library developers and page authors should not generate JspFragment implementations manually.

Implementation Note: It is not necessary to generate a separate class for each fragment. One possible implementation is to generate a single helper class for each page that implements JspFragment. Upon construction, a discriminator can be passed to select which fragment that instance will execute.

Since:

JSP 2.0

public JspFragment()

英文文档：

JspFragment

public JspFragment()

abstract public void invoke(java.io.Writer out) throws JspException, java.io.IOException
执行该片段，并将所有输出定向到给定 Writer，如果 out 为 null，则将输出定向到与该片段关联的 JspContext 的 getOut() 方法返回的 JspWriter。

out	将片段输出到的 Writer，如果应该将输出发送到 JspContext.getOut()，则该参数为 null。
Throws	JspException: 如果调用此片段时发生错误，则抛出此异常。
Throws	SkipPageException: 如果（直接或间接）调用了标记处理程序（该标记处理程序调用了此片段）的页面将停止求值，则抛出此异常。如果经典标记处理程序返回 Tag.SKIP_PAGE，或者简单标记处理程序抛出 SkipPageException，则容器必定抛出此异常。
Throws	java.io.IOException: 如果写入流时出现错误。

英文文档：

invoke

public abstract void invoke(Writer out)
                     throws JspException,
                            IOException

Executes the fragment and directs all output to the given Writer, or the JspWriter returned by the getOut() method of the JspContext associated with the fragment if out is null.

Parameters:

out - The Writer to output the fragment to, or null if output should be sent to JspContext.getOut().

Throws:

JspException - Thrown if an error occured while invoking this fragment.

SkipPageException - Thrown if the page that (either directly or indirectly) invoked the tag handler that invoked this fragment is to cease evaluation. The container must throw this exception if a Classic Tag Handler returned Tag.SKIP_PAGE or if a Simple Tag Handler threw SkipPageException.

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

abstract public JspContext getJspContext()
返回绑定到此 JspFragment 的 JspContext。

return

在调用时此片段使用的 JspContext。

英文文档：

getJspContext

public abstract JspContext getJspContext()

Returns the JspContext that is bound to this JspFragment.

Returns:

The JspContext used by this fragment at invocation time.

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