VariableInfo (Java EE 5)

自定义操作生成的脚本变量有一个相关联的范围，该范围是 AT_BEGIN、NESTED 或 AT_END。

返回对象中的类名称 (VariableInfo.getClassName) 用于确定脚本变量的类型。注意，因为脚本变量根据范围属性分配其值，该属性不能是基本类型，所以必须使用“装箱”类型（比如 java.lang.Integer），而不是基本类型。

类名称可以是完全限定类名称或者简短类名称。

如果提供完全限定类名称，则将引用应该位于 Web 应用程序的 CLASSPATH 中的类（请参见 Servlet 2.4 规范 - 实质上是 WEB-INF/lib 和 WEB-INF/classes）。操作失败将导致转换期间错误。

如果在 VariableInfo 对象中给出简短类名称，那么类名称必须是自定义操作出现的页面上 import 指令上下文中的某个公共类的名称。该类必须也位于 Web 应用程序的 CLASSPATH 中（请参见 Servlet 2.4 规范 - 实质上是 WEB-INF/lib 和 WEB-INF/classes）。操作失败将导致转换期间错误。

用法注释

通常，完全限定类名称将引用标记库已知的类，这样就可以在与标记处理程序相同的 JAR 文件中传送该类。在其他多数情况下，它将引用构建 JSP 处理器的平台（比如 J2EE）中的某个类。以这种方式使用完全限定类名称可对配置错误产生一定的抵抗力。

短名称通常由标记库根据从自定义操作用户（作者）传入的一些属性生成，因此，它不那么健壮：例如，在正引用的 JSP 页面中丢失 import 指令将导致无效短名称类和转换错误。

同步协议

调用 getVariableInfo 的结果是产生一个 VariableInfo 对象数组。每个 VariableInfo 对象都描述一个脚本变量，描述方式是提供该变量的名称、其类型、该变量是否是新变量以及其范围是什么。范围可通过图像得到最好的描述：

JSP 2.0 规范定义了这三个值的解释：

• NESTED，如果脚本变量在定义它的操作的开始标记和结束标记之间是可用的。
• AT_BEGIN，如果脚本变量从定义它的操作的开始标记一直到范围的结束都是可用的。
• AT_END，如果脚本变量在定义它的操作的结束标记之后一直到范围的结束都是可用的。

变量同步点
	doStartTag()	doInitBody()	doAfterBody()	doEndTag()	doTag()
Tag	AT_BEGIN 和 NESTED			AT_BEGIN 和 AT_END
IterationTag	AT_BEGIN 和 NESTED		AT_BEGIN 和 NESTED	AT_BEGIN 和 AT_END
BodyTag	AT_BEGIN 和 NESTED1	AT_BEGIN 和 NESTED1	AT_BEGIN 和 NESTED	AT_BEGIN 和 AT_END
SimpleTag					AT_BEGIN 和 AT_END

¹ 如果返回 EVAL_BODY_INCLUDE，则在调用 doStartTag() 之后调用，否则在调用 doInitBody() 之后调用。

TLD 中的变量信息

多数情况下，也可以使用 <tag> 元素的 <variable> 子元素直接将脚本变量信息编码到标记库描述符。请参见 JSP 规范。

Information on the scripting variables that are created/modified by a tag (at run-time). This information is provided by TagExtraInfo classes and it is used by the translation phase of JSP.

Scripting variables generated by a custom action have an associated scope of either AT_BEGIN, NESTED, or AT_END.

The class name (VariableInfo.getClassName) in the returned objects is used to determine the types of the scripting variables. Note that because scripting variables are assigned their values from scoped attributes which cannot be of primitive types, "boxed" types such as java.lang.Integer must be used instead of primitives.

The class name may be a Fully Qualified Class Name, or a short class name.

If a Fully Qualified Class Name is provided, it should refer to a class that should be in the CLASSPATH for the Web Application (see Servlet 2.4 specification - essentially it is WEB-INF/lib and WEB-INF/classes). Failure to be so will lead to a translation-time error.

If a short class name is given in the VariableInfo objects, then the class name must be that of a public class in the context of the import directives of the page where the custom action appears. The class must also be in the CLASSPATH for the Web Application (see Servlet 2.4 specification - essentially it is WEB-INF/lib and WEB-INF/classes). Failure to be so will lead to a translation-time error.

Usage Comments

Frequently a fully qualified class name will refer to a class that is known to the tag library and thus, delivered in the same JAR file as the tag handlers. In most other remaining cases it will refer to a class that is in the platform on which the JSP processor is built (like Java EE). Using fully qualified class names in this manner makes the usage relatively resistant to configuration errors.

A short name is usually generated by the tag library based on some attributes passed through from the custom action user (the author), and it is thus less robust: for instance a missing import directive in the referring JSP page will lead to an invalid short name class and a translation error.

Synchronization Protocol

The result of the invocation on getVariableInfo is an array of VariableInfo objects. Each such object describes a scripting variable by providing its name, its type, whether the variable is new or not, and what its scope is. Scope is best described through a picture:

The JSP 2.0 specification defines the interpretation of 3 values:

• NESTED, if the scripting variable is available between the start tag and the end tag of the action that defines it.
• AT_BEGIN, if the scripting variable is available from the start tag of the action that defines it until the end of the scope.
• AT_END, if the scripting variable is available after the end tag of the action that defines it until the end of the scope.

Variable Synchronization Points
	doStartTag()	doInitBody()	doAfterBody()	doEndTag()	doTag()
Tag	AT_BEGIN, NESTED			AT_BEGIN, AT_END
IterationTag	AT_BEGIN, NESTED		AT_BEGIN, NESTED	AT_BEGIN, AT_END
BodyTag	AT_BEGIN, NESTED1	AT_BEGIN, NESTED1	AT_BEGIN, NESTED	AT_BEGIN, AT_END
SimpleTag					AT_BEGIN, AT_END

¹ Called after doStartTag() if EVAL_BODY_INCLUDE is returned, or after doInitBody() otherwise.

Variable Information in the TLD

Scripting variable information can also be encoded directly for most cases into the Tag Library Descriptor using the <variable> subelement of the <tag> element. See the JSP specification.

英文文档：

NESTED

public static final int NESTED

Scope information that scripting variable is visible only within the start/end tags.

See Also:

Constant Field Values

英文文档：

AT_BEGIN

public static final int AT_BEGIN

Scope information that scripting variable is visible after start tag.

See Also:

Constant Field Values

英文文档：

AT_END

public static final int AT_END

Scope information that scripting variable is visible after end tag.

See Also:

Constant Field Values

public VariableInfo(String varName, String className, boolean declare, int scope)
构造方法，可以通过 TagExtraInfo 实例（在转换期间）创建这些对象。

varName	脚本变量的名称
className	此变量的类型
declare	如果为 true，则该变量是一个新变量（在某些语言中，这将需要一个声明）
scope	变量的词法范围的指示

英文文档：

VariableInfo

public VariableInfo(String varName,
                    String className,
                    boolean declare,
                    int scope)

Constructor These objects can be created (at translation time) by the TagExtraInfo instances.

Parameters:

varName - The name of the scripting variable

className - The type of this variable

declare - If true, it is a new variable (in some languages this will require a declaration)

scope - Indication on the lexical scope of the variable

public String getVarName()
返回脚本变量的名称。

return

脚本变量的名称

英文文档：

getVarName

public String getVarName()

Returns the name of the scripting variable.

Returns:

the name of the scripting variable

public String getClassName()
返回此变量的类型。

return

此变量的类型

英文文档：

getClassName

public String getClassName()

Returns the type of this variable.

Returns:

the type of this variable

public boolean getDeclare()
返回此变量是否是新变量。如果是，那么在某些语言中这将需要一个声明。

return

此变量是否是新变量。

英文文档：

getDeclare

public boolean getDeclare()

Returns whether this is a new variable. If so, in some languages this will require a declaration.

Returns:

whether this is a new variable.

public int getScope()
返回变量的词法范围。

return	变量的词法范围，该范围是 AT_BEGIN、AT_END 或 NESTED。
See also	AT_BEGIN, AT_END, NESTED

英文文档：

getScope

public int getScope()

Returns the lexical scope of the variable.

Returns:

the lexical scope of the variable, either AT_BEGIN, AT_END, or NESTED.

See Also:

AT_BEGIN, AT_END, NESTED

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