/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ // // This source code implements specifications defined by the Java // Community Process. In order to remain compliant with the specification // DO NOT add / change / or delete method signatures! // package javax.servlet.jsp.tagext; /** * 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 J2EE). 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: * *
** ** *
* 1 Called after* *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 *
*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. */ public class VariableInfo { /** * Scope information that scripting variable is visible only within the * start/end tags. */ public static final int NESTED = 0; /** * Scope information that scripting variable is visible after start tag. */ public static final int AT_BEGIN = 1; /** * Scope information that scripting variable is visible after end tag. */ public static final int AT_END = 2; /** * Constructor * These objects can be created (at translation time) by the TagExtraInfo * instances. * * @param varName The name of the scripting variable * @param className The type of this variable * @param declare If true, it is a new variable (in some languages this will * require a declaration) * @param scope Indication on the lexical scope of the variable */ public VariableInfo(String varName, String className, boolean declare, int scope) { this.varName = varName; this.className = className; this.declare = declare; this.scope = scope; } // Accessor methods /** * Returns the name of the scripting variable. * * @return the name of the scripting variable */ public String getVarName() { return varName; } /** * Returns the type of this variable. * * @return the type of this variable */ public String getClassName() { return className; } /** * Returns whether this is a new variable. * If so, in some languages this will require a declaration. * * @return whether this is a new variable. */ public boolean getDeclare() { return declare; } /** * Returns the lexical scope of the variable. * * @return the lexical scope of the variable, either AT_BEGIN, AT_END, * or NESTED. * @see #AT_BEGIN * @see #AT_END * @see #NESTED */ public int getScope() { return scope; } // == private data private String varName; private String className; private boolean declare; private int scope; }