1 /** 2 * 3 * Copyright 2003-2004 The Apache Software Foundation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 // 19 // This source code implements specifications defined by the Java 20 // Community Process. In order to remain compliant with the specification 21 // DO NOT add / change / or delete method signatures! 22 // 23 24 package javax.servlet.jsp.tagext; 25 26 /** 27 * Information on the scripting variables that are created/modified by 28 * a tag (at run-time). This information is provided by TagExtraInfo 29 * classes and it is used by the translation phase of JSP. 30 * 31 * <p> 32 * Scripting variables generated by a custom action have an associated 33 * scope of either AT_BEGIN, NESTED, or AT_END. 34 * 35 * <p> 36 * The class name (VariableInfo.getClassName) in the returned objects 37 * is used to determine the types of the scripting variables. 38 * Note that because scripting variables are assigned their values 39 * from scoped attributes which cannot be of primitive types, 40 * "boxed" types such as <code>java.lang.Integer</code> must 41 * be used instead of primitives. 42 * 43 * <p> 44 * The class name may be a Fully Qualified Class Name, or a short 45 * class name. 46 * 47 * <p> 48 * If a Fully Qualified Class Name is provided, it should refer to a 49 * class that should be in the CLASSPATH for the Web Application (see 50 * Servlet 2.4 specification - essentially it is WEB-INF/lib and 51 * WEB-INF/classes). Failure to be so will lead to a translation-time 52 * error. 53 * 54 * <p> 55 * If a short class name is given in the VariableInfo objects, then 56 * the class name must be that of a public class in the context of the 57 * import directives of the page where the custom action appears. 58 * The class must also be in the CLASSPATH for the Web Application 59 * (see Servlet 2.4 specification - essentially it is WEB-INF/lib and 60 * WEB-INF/classes). Failure to be so will lead to a translation-time 61 * error. 62 * 63 * <p><B>Usage Comments</B> 64 * <p> 65 * Frequently a fully qualified class name will refer to a class that 66 * is known to the tag library and thus, delivered in the same JAR 67 * file as the tag handlers. In most other remaining cases it will 68 * refer to a class that is in the platform on which the JSP processor 69 * is built (like J2EE). Using fully qualified class names in this 70 * manner makes the usage relatively resistant to configuration 71 * errors. 72 * 73 * <p> 74 * A short name is usually generated by the tag library based on some 75 * attributes passed through from the custom action user (the author), 76 * and it is thus less robust: for instance a missing import directive 77 * in the referring JSP page will lead to an invalid short name class 78 * and a translation error. 79 * 80 * <p><B>Synchronization Protocol</B> 81 * 82 * <p> 83 * The result of the invocation on getVariableInfo is an array of 84 * VariableInfo objects. Each such object describes a scripting 85 * variable by providing its name, its type, whether the variable is 86 * new or not, and what its scope is. Scope is best described through 87 * a picture: 88 * 89 * <p> 90 * <IMG src="doc-files/VariableInfo-1.gif" 91 * alt="NESTED, AT_BEGIN and AT_END Variable Scopes"/> 92 * 93 *<p> 94 * The JSP 2.0 specification defines the interpretation of 3 values: 95 * 96 * <ul> 97 * <li> NESTED, if the scripting variable is available between 98 * the start tag and the end tag of the action that defines it. 99 * <li> 100 * AT_BEGIN, if the scripting variable is available from the start tag 101 * of the action that defines it until the end of the scope. 102 * <li> AT_END, if the scripting variable is available after the end tag 103 * of the action that defines it until the end of the scope. 104 * </ul> 105 * 106 * The scope value for a variable implies what methods may affect its 107 * value and thus where synchronization is needed as illustrated by 108 * the table below. <b>Note:</b> the synchronization of the variable(s) 109 * will occur <em>after</em> the respective method has been called. 110 * 111 * <blockquote> 112 * <table cellpadding="2" cellspacing="2" border="0" width="55%" 113 * bgcolor="#999999" summary="Variable Synchronization Points"> 114 * <tbody> 115 * <tr align="center"> 116 * <td valign="top" colspan="6" bgcolor="#999999"><u><b>Variable Synchronization 117 * Points</b></u><br> 118 * </td> 119 * </tr> 120 * <tr> 121 * <th valign="top" bgcolor="#c0c0c0"> </th> 122 * <th valign="top" bgcolor="#c0c0c0" align="center">doStartTag()</th> 123 * <th valign="top" bgcolor="#c0c0c0" align="center">doInitBody()</th> 124 * <th valign="top" bgcolor="#c0c0c0" align="center">doAfterBody()</th> 125 * <th valign="top" bgcolor="#c0c0c0" align="center">doEndTag()</th> 126 * <th valign="top" bgcolor="#c0c0c0" align="center">doTag()</th> 127 * </tr> 128 * <tr> 129 * <td valign="top" bgcolor="#c0c0c0"><b>Tag<br> 130 * </b></td> 131 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 132 * </td> 133 * <td valign="top" align="center" bgcolor="#ffffff"><br> 134 * </td> 135 * <td valign="top" align="center" bgcolor="#ffffff"><br> 136 * </td> 137 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 138 * </td> 139 * <td valign="top" align="center" bgcolor="#ffffff"><br> 140 * </td> 141 * </tr> 142 * <tr> 143 * <td valign="top" bgcolor="#c0c0c0"><b>IterationTag<br> 144 * </b></td> 145 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 146 * </td> 147 * <td valign="top" align="center" bgcolor="#ffffff"><br> 148 * </td> 149 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> 150 * </td> 151 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 152 * </td> 153 * <td valign="top" align="center" bgcolor="#ffffff"><br> 154 * </td> 155 * </tr> 156 * <tr> 157 * <td valign="top" bgcolor="#c0c0c0"><b>BodyTag<br> 158 * </b></td> 159 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<sup>1</sup><br> 160 * </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<br> 164 * </td> 165 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> 166 * </td> 167 * <td valign="top" align="center" bgcolor="#ffffff"><br> 168 * </td> 169 * </tr> 170 * <tr> 171 * <td valign="top" bgcolor="#c0c0c0"><b>SimpleTag<br> 172 * </b></td> 173 * <td valign="top" align="center" bgcolor="#ffffff"><br> 174 * </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">AT_BEGIN, AT_END<br> 182 * </td> 183 * </tr> 184 * </tbody> 185 * </table> 186 * <sup>1</sup> Called after <code>doStartTag()</code> if 187 * <code>EVAL_BODY_INCLUDE</code> is returned, or after 188 * <code>doInitBody()</code> otherwise. 189 * </blockquote> 190 * 191 * <p><B>Variable Information in the TLD</B> 192 * <p> 193 * Scripting variable information can also be encoded directly for most cases 194 * into the Tag Library Descriptor using the <variable> subelement of the 195 * <tag> element. See the JSP specification. 196 */ 197 198 public class VariableInfo { 199 200 /** 201 * Scope information that scripting variable is visible only within the 202 * start/end tags. 203 */ 204 public static final int NESTED = 0; 205 206 /** 207 * Scope information that scripting variable is visible after start tag. 208 */ 209 public static final int AT_BEGIN = 1; 210 211 /** 212 * Scope information that scripting variable is visible after end tag. 213 */ 214 public static final int AT_END = 2; 215 216 217 /** 218 * Constructor 219 * These objects can be created (at translation time) by the TagExtraInfo 220 * instances. 221 * 222 * @param varName The name of the scripting variable 223 * @param className The type of this variable 224 * @param declare If true, it is a new variable (in some languages this will 225 * require a declaration) 226 * @param scope Indication on the lexical scope of the variable 227 */ 228 229 public VariableInfo(String varName, 230 String className, 231 boolean declare, 232 int scope) { 233 this.varName = varName; 234 this.className = className; 235 this.declare = declare; 236 this.scope = scope; 237 } 238 239 // Accessor methods 240 241 /** 242 * Returns the name of the scripting variable. 243 * 244 * @return the name of the scripting variable 245 */ 246 public String getVarName() { 247 return varName; 248 } 249 250 /** 251 * Returns the type of this variable. 252 * 253 * @return the type of this variable 254 */ 255 public String getClassName() { 256 return className; 257 } 258 259 /** 260 * Returns whether this is a new variable. 261 * If so, in some languages this will require a declaration. 262 * 263 * @return whether this is a new variable. 264 */ 265 public boolean getDeclare() { 266 return declare; 267 } 268 269 /** 270 * Returns the lexical scope of the variable. 271 * 272 * @return the lexical scope of the variable, either AT_BEGIN, AT_END, 273 * or NESTED. 274 * @see #AT_BEGIN 275 * @see #AT_END 276 * @see #NESTED 277 */ 278 public int getScope() { 279 return scope; 280 } 281 282 283 // == private data 284 private String varName; 285 private String className; 286 private boolean declare; 287 private int scope; 288 } 289