VariableInfo (Java EE 5)

Java EE API

previous page next page
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.servlet.jsp.tagext Class VariableInfo

java.lang.Object
  extended by javax.servlet.jsp.tagext.VariableInfo

public class VariableInfo
extends Object


有关由标记（在运行时）创建/修改的脚本变量的信息。此信息由 TagExtraInfo 类提供，在 JSP 的转换阶段使用。

自定义操作生成的脚本变量有一个相关联的范围，该范围是 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 对象都描述一个脚本变量，描述方式是提供该变量的名称、其类型、该变量是否是新变量以及其范围是什么。范围可通过图像得到最好的描述：

NESTED、AT_BEGIN 和 AT_END 变量范围

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
1 如果返回 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:

NESTED, AT_BEGIN and AT_END Variable Scopes

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.
The scope value for a variable implies what methods may affect its value and thus where synchronization is needed as illustrated by the table below. Note: the synchronization of the variable(s) will occur after the respective method has been called.
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
1 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.

Field Summary
static int AT_BEGIN
          Scope information that scripting variable is visible after start tag.
static int AT_END
          Scope information that scripting variable is visible after end tag.
static int NESTED
          Scope information that scripting variable is visible only within the start/end tags.
 
Constructor Summary
VariableInfo(String varName, String className, boolean declare, int scope)
          Constructor These objects can be created (at translation time) by the TagExtraInfo instances.
 
Method Summary
 String getClassName()
          Returns the type of this variable.
 boolean getDeclare()
          Returns whether this is a new variable.
 int getScope()
          Returns the lexical scope of the variable.
 String getVarName()
          Returns the name of the scripting variable.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

英文文档：

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

Constructor Detail

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

Method Detail

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
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature

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

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正；若因此而造成任何损失请直接找人民主席，请勿与本人联系。谢谢！

previous page start next page