View Javadoc

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   * &quot;boxed&quot; 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">&nbsp;</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 &lt;variable&gt; subelement of the
195  * &lt;tag&gt; 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