001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet.jsp.tagext; 027 028 /** 029 * Information on the scripting variables that are created/modified by 030 * a tag (at run-time). This information is provided by TagExtraInfo 031 * classes and it is used by the translation phase of JSP. 032 * 033 * <p> 034 * Scripting variables generated by a custom action have an associated 035 * scope of either AT_BEGIN, NESTED, or AT_END. 036 * 037 * <p> 038 * The class name (VariableInfo.getClassName) in the returned objects 039 * is used to determine the types of the scripting variables. 040 * Note that because scripting variables are assigned their values 041 * from scoped attributes which cannot be of primitive types, 042 * "boxed" types such as <code>java.lang.Integer</code> must 043 * be used instead of primitives. 044 * 045 * <p> 046 * The class name may be a Fully Qualified Class Name, or a short 047 * class name. 048 * 049 * <p> 050 * If a Fully Qualified Class Name is provided, it should refer to a 051 * class that should be in the CLASSPATH for the Web Application (see 052 * Servlet 2.4 specification - essentially it is WEB-INF/lib and 053 * WEB-INF/classes). Failure to be so will lead to a translation-time 054 * error. 055 * 056 * <p> 057 * If a short class name is given in the VariableInfo objects, then 058 * the class name must be that of a public class in the context of the 059 * import directives of the page where the custom action appears. 060 * The class must also be in the CLASSPATH for the Web Application 061 * (see Servlet 2.4 specification - essentially it is WEB-INF/lib and 062 * WEB-INF/classes). Failure to be so will lead to a translation-time 063 * error. 064 * 065 * <p><B>Usage Comments</B> 066 * <p> 067 * Frequently a fully qualified class name will refer to a class that 068 * is known to the tag library and thus, delivered in the same JAR 069 * file as the tag handlers. In most other remaining cases it will 070 * refer to a class that is in the platform on which the JSP processor 071 * is built (like J2EE). Using fully qualified class names in this 072 * manner makes the usage relatively resistant to configuration 073 * errors. 074 * 075 * <p> 076 * A short name is usually generated by the tag library based on some 077 * attributes passed through from the custom action user (the author), 078 * and it is thus less robust: for instance a missing import directive 079 * in the referring JSP page will lead to an invalid short name class 080 * and a translation error. 081 * 082 * <p><B>Synchronization Protocol</B> 083 * 084 * <p> 085 * The result of the invocation on getVariableInfo is an array of 086 * VariableInfo objects. Each such object describes a scripting 087 * variable by providing its name, its type, whether the variable is 088 * new or not, and what its scope is. Scope is best described through 089 * a picture: 090 * 091 * <p> 092 * <IMG src="doc-files/VariableInfo-1.gif" 093 * alt="NESTED, AT_BEGIN and AT_END Variable Scopes"/> 094 * 095 *<p> 096 * The JSP 2.0 specification defines the interpretation of 3 values: 097 * 098 * <ul> 099 * <li> NESTED, if the scripting variable is available between 100 * the start tag and the end tag of the action that defines it. 101 * <li> 102 * AT_BEGIN, if the scripting variable is available from the start tag 103 * of the action that defines it until the end of the scope. 104 * <li> AT_END, if the scripting variable is available after the end tag 105 * of the action that defines it until the end of the scope. 106 * </ul> 107 * 108 * The scope value for a variable implies what methods may affect its 109 * value and thus where synchronization is needed as illustrated by 110 * the table below. <b>Note:</b> the synchronization of the variable(s) 111 * will occur <em>after</em> the respective method has been called. 112 * 113 * <blockquote> 114 * <table cellpadding="2" cellspacing="2" border="0" width="55%" 115 * bgcolor="#999999" summary="Variable Synchronization Points"> 116 * <tbody> 117 * <tr align="center"> 118 * <td valign="top" colspan="6" bgcolor="#999999"><u><b>Variable Synchronization 119 * Points</b></u><br> 120 * </td> 121 * </tr> 122 * <tr> 123 * <th valign="top" bgcolor="#c0c0c0"> </th> 124 * <th valign="top" bgcolor="#c0c0c0" align="center">doStartTag()</th> 125 * <th valign="top" bgcolor="#c0c0c0" align="center">doInitBody()</th> 126 * <th valign="top" bgcolor="#c0c0c0" align="center">doAfterBody()</th> 127 * <th valign="top" bgcolor="#c0c0c0" align="center">doEndTag()</th> 128 * <th valign="top" bgcolor="#c0c0c0" align="center">doTag()</th> 129 * </tr> 130 * <tr> 131 * <td valign="top" bgcolor="#c0c0c0"><b>Tag<br> 132 * </b></td> 133 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 134 * </td> 135 * <td valign="top" align="center" bgcolor="#ffffff"><br> 136 * </td> 137 * <td valign="top" align="center" bgcolor="#ffffff"><br> 138 * </td> 139 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 140 * </td> 141 * <td valign="top" align="center" bgcolor="#ffffff"><br> 142 * </td> 143 * </tr> 144 * <tr> 145 * <td valign="top" bgcolor="#c0c0c0"><b>IterationTag<br> 146 * </b></td> 147 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 148 * </td> 149 * <td valign="top" align="center" bgcolor="#ffffff"><br> 150 * </td> 151 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 152 * </td> 153 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 154 * </td> 155 * <td valign="top" align="center" bgcolor="#ffffff"><br> 156 * </td> 157 * </tr> 158 * <tr> 159 * <td valign="top" bgcolor="#c0c0c0"><b>BodyTag<br> 160 * </b></td> 161 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<sup>1</sup><br> 162 * </td> 163 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<sup>1</sup><br> 164 * </td> 165 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 166 * </td> 167 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 168 * </td> 169 * <td valign="top" align="center" bgcolor="#ffffff"><br> 170 * </td> 171 * </tr> 172 * <tr> 173 * <td valign="top" bgcolor="#c0c0c0"><b>SimpleTag<br> 174 * </b></td> 175 * <td valign="top" align="center" bgcolor="#ffffff"><br> 176 * </td> 177 * <td valign="top" align="center" bgcolor="#ffffff"><br> 178 * </td> 179 * <td valign="top" align="center" bgcolor="#ffffff"><br> 180 * </td> 181 * <td valign="top" align="center" bgcolor="#ffffff"><br> 182 * </td> 183 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 184 * </td> 185 * </tr> 186 * </tbody> 187 * </table> 188 * <sup>1</sup> Called after <code>doStartTag()</code> if 189 * <code>EVAL_BODY_INCLUDE</code> is returned, or after 190 * <code>doInitBody()</code> otherwise. 191 * </blockquote> 192 * 193 * <p><B>Variable Information in the TLD</B> 194 * <p> 195 * Scripting variable information can also be encoded directly for most cases 196 * into the Tag Library Descriptor using the <variable> subelement of the 197 * <tag> element. See the JSP specification. 198 */ 199 200 public class VariableInfo { 201 202 /** 203 * Scope information that scripting variable is visible only within the 204 * start/end tags. 205 */ 206 public static final int NESTED = 0; 207 208 /** 209 * Scope information that scripting variable is visible after start tag. 210 */ 211 public static final int AT_BEGIN = 1; 212 213 /** 214 * Scope information that scripting variable is visible after end tag. 215 */ 216 public static final int AT_END = 2; 217 218 219 /** 220 * Constructor 221 * These objects can be created (at translation time) by the TagExtraInfo 222 * instances. 223 * 224 * @param varName The name of the scripting variable 225 * @param className The type of this variable 226 * @param declare If true, it is a new variable (in some languages this will 227 * require a declaration) 228 * @param scope Indication on the lexical scope of the variable 229 */ 230 231 public VariableInfo(String varName, 232 String className, 233 boolean declare, 234 int scope) { 235 this.varName = varName; 236 this.className = className; 237 this.declare = declare; 238 this.scope = scope; 239 } 240 241 // Accessor methods 242 243 /** 244 * Returns the name of the scripting variable. 245 * 246 * @return the name of the scripting variable 247 */ 248 public String getVarName() { 249 return varName; 250 } 251 252 /** 253 * Returns the type of this variable. 254 * 255 * @return the type of this variable 256 */ 257 public String getClassName() { 258 return className; 259 } 260 261 /** 262 * Returns whether this is a new variable. 263 * If so, in some languages this will require a declaration. 264 * 265 * @return whether this is a new variable. 266 */ 267 public boolean getDeclare() { 268 return declare; 269 } 270 271 /** 272 * Returns the lexical scope of the variable. 273 * 274 * @return the lexical scope of the variable, either AT_BEGIN, AT_END, 275 * or NESTED. 276 * @see #AT_BEGIN 277 * @see #AT_END 278 * @see #NESTED 279 */ 280 public int getScope() { 281 return scope; 282 } 283 284 285 // == private data 286 private String varName; 287 private String className; 288 private boolean declare; 289 private int scope; 290 } 291