KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > jsp > tagext > VariableInfo


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  * &quot;boxed&quot; 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">&nbsp;</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 &lt;variable&gt; subelement of the
190  * &lt;tag&gt; 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 JavaDoc varName,
225             String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc varName;
280     private String JavaDoc className;
281     private boolean declare;
282     private int scope;
283 }
284
285
Popular Tags