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