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   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 
285
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags