/* * 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: * *

* NESTED, AT_BEGIN and AT_END Variable Scopes * *

* The JSP 2.0 specification defines the interpretation of 3 values: * *

* * 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. */ 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; }