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