001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package javax.servlet.jsp.tagext;
018
019 /**
020 * Information on the scripting variables that are created/modified by
021 * a tag (at run-time). This information is provided by TagExtraInfo
022 * classes and it is used by the translation phase of JSP.
023 *
024 * <p>
025 * Scripting variables generated by a custom action have an associated
026 * scope of either AT_BEGIN, NESTED, or AT_END.
027 *
028 * <p>
029 * The class name (VariableInfo.getClassName) in the returned objects
030 * is used to determine the types of the scripting variables.
031 * Note that because scripting variables are assigned their values
032 * from scoped attributes which cannot be of primitive types,
033 * "boxed" types such as <code>java.lang.Integer</code> must
034 * be used instead of primitives.
035 *
036 * <p>
037 * The class name may be a Fully Qualified Class Name, or a short
038 * class name.
039 *
040 * <p>
041 * If a Fully Qualified Class Name is provided, it should refer to a
042 * class that should be in the CLASSPATH for the Web Application (see
043 * Servlet 2.4 specification - essentially it is WEB-INF/lib and
044 * WEB-INF/classes). Failure to be so will lead to a translation-time
045 * error.
046 *
047 * <p>
048 * If a short class name is given in the VariableInfo objects, then
049 * the class name must be that of a public class in the context of the
050 * import directives of the page where the custom action appears.
051 * The class must also be in the CLASSPATH for the Web Application
052 * (see Servlet 2.4 specification - essentially it is WEB-INF/lib and
053 * WEB-INF/classes). Failure to be so will lead to a translation-time
054 * error.
055 *
056 * <p><B>Usage Comments</B>
057 * <p>
058 * Frequently a fully qualified class name will refer to a class that
059 * is known to the tag library and thus, delivered in the same JAR
060 * file as the tag handlers. In most other remaining cases it will
061 * refer to a class that is in the platform on which the JSP processor
062 * is built (like J2EE). Using fully qualified class names in this
063 * manner makes the usage relatively resistant to configuration
064 * errors.
065 *
066 * <p>
067 * A short name is usually generated by the tag library based on some
068 * attributes passed through from the custom action user (the author),
069 * and it is thus less robust: for instance a missing import directive
070 * in the referring JSP page will lead to an invalid short name class
071 * and a translation error.
072 *
073 * <p><B>Synchronization Protocol</B>
074 *
075 * <p>
076 * The result of the invocation on getVariableInfo is an array of
077 * VariableInfo objects. Each such object describes a scripting
078 * variable by providing its name, its type, whether the variable is
079 * new or not, and what its scope is. Scope is best described through
080 * a picture:
081 *
082 * <p>
083 * <IMG src="doc-files/VariableInfo-1.gif"
084 * alt="NESTED, AT_BEGIN and AT_END Variable Scopes"/>
085 *
086 *<p>
087 * The JSP 2.0 specification defines the interpretation of 3 values:
088 *
089 * <ul>
090 * <li> NESTED, if the scripting variable is available between
091 * the start tag and the end tag of the action that defines it.
092 * <li>
093 * AT_BEGIN, if the scripting variable is available from the start tag
094 * of the action that defines it until the end of the scope.
095 * <li> AT_END, if the scripting variable is available after the end tag
096 * of the action that defines it until the end of the scope.
097 * </ul>
098 *
099 * The scope value for a variable implies what methods may affect its
100 * value and thus where synchronization is needed as illustrated by
101 * the table below. <b>Note:</b> the synchronization of the variable(s)
102 * will occur <em>after</em> the respective method has been called.
103 *
104 * <blockquote>
105 * <table cellpadding="2" cellspacing="2" border="0" width="55%"
106 * bgcolor="#999999" summary="Variable Synchronization Points">
107 * <tbody>
108 * <tr align="center">
109 * <td valign="top" colspan="6" bgcolor="#999999"><u><b>Variable Synchronization
110 * Points</b></u><br>
111 * </td>
112 * </tr>
113 * <tr>
114 * <th valign="top" bgcolor="#c0c0c0"> </th>
115 * <th valign="top" bgcolor="#c0c0c0" align="center">doStartTag()</th>
116 * <th valign="top" bgcolor="#c0c0c0" align="center">doInitBody()</th>
117 * <th valign="top" bgcolor="#c0c0c0" align="center">doAfterBody()</th>
118 * <th valign="top" bgcolor="#c0c0c0" align="center">doEndTag()</th>
119 * <th valign="top" bgcolor="#c0c0c0" align="center">doTag()</th>
120 * </tr>
121 * <tr>
122 * <td valign="top" bgcolor="#c0c0c0"><b>Tag<br>
123 * </b></td>
124 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br>
125 * </td>
126 * <td valign="top" align="center" bgcolor="#ffffff"><br>
127 * </td>
128 * <td valign="top" align="center" bgcolor="#ffffff"><br>
129 * </td>
130 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br>
131 * </td>
132 * <td valign="top" align="center" bgcolor="#ffffff"><br>
133 * </td>
134 * </tr>
135 * <tr>
136 * <td valign="top" bgcolor="#c0c0c0"><b>IterationTag<br>
137 * </b></td>
138 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br>
139 * </td>
140 * <td valign="top" align="center" bgcolor="#ffffff"><br>
141 * </td>
142 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br>
143 * </td>
144 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br>
145 * </td>
146 * <td valign="top" align="center" bgcolor="#ffffff"><br>
147 * </td>
148 * </tr>
149 * <tr>
150 * <td valign="top" bgcolor="#c0c0c0"><b>BodyTag<br>
151 * </b></td>
152 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<sup>1</sup><br>
153 * </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<br>
157 * </td>
158 * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br>
159 * </td>
160 * <td valign="top" align="center" bgcolor="#ffffff"><br>
161 * </td>
162 * </tr>
163 * <tr>
164 * <td valign="top" bgcolor="#c0c0c0"><b>SimpleTag<br>
165 * </b></td>
166 * <td valign="top" align="center" bgcolor="#ffffff"><br>
167 * </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">AT_BEGIN, AT_END<br>
175 * </td>
176 * </tr>
177 * </tbody>
178 * </table>
179 * <sup>1</sup> Called after <code>doStartTag()</code> if
180 * <code>EVAL_BODY_INCLUDE</code> is returned, or after
181 * <code>doInitBody()</code> otherwise.
182 * </blockquote>
183 *
184 * <p><B>Variable Information in the TLD</B>
185 * <p>
186 * Scripting variable information can also be encoded directly for most cases
187 * into the Tag Library Descriptor using the <variable> subelement of the
188 * <tag> element. See the JSP specification.
189 */
190
191 public class VariableInfo {
192
193 /**
194 * Scope information that scripting variable is visible only within the
195 * start/end tags.
196 */
197 public static final int NESTED = 0;
198
199 /**
200 * Scope information that scripting variable is visible after start tag.
201 */
202 public static final int AT_BEGIN = 1;
203
204 /**
205 * Scope information that scripting variable is visible after end tag.
206 */
207 public static final int AT_END = 2;
208
209 /**
210 * Constructor
211 * These objects can be created (at translation time) by the TagExtraInfo
212 * instances.
213 *
214 * @param varName The name of the scripting variable
215 * @param className The type of this variable
216 * @param declare If true, it is a new variable (in some languages this will
217 * require a declaration)
218 * @param scope Indication on the lexical scope of the variable
219 */
220
221 public VariableInfo(String varName, String className,
222 boolean declare, int scope) {
223 this .varName = varName;
224 this .className = className;
225 this .declare = declare;
226 this .scope = scope;
227 }
228
229 // Accessor methods
230
231 /**
232 * Returns the name of the scripting variable.
233 *
234 * @return the name of the scripting variable
235 */
236 public String getVarName() {
237 return varName;
238 }
239
240 /**
241 * Returns the type of this variable.
242 *
243 * @return the type of this variable
244 */
245 public String getClassName() {
246 return className;
247 }
248
249 /**
250 * Returns whether this is a new variable.
251 * If so, in some languages this will require a declaration.
252 *
253 * @return whether this is a new variable.
254 */
255 public boolean getDeclare() {
256 return declare;
257 }
258
259 /**
260 * Returns the lexical scope of the variable.
261 *
262 * @return the lexical scope of the variable, either AT_BEGIN, AT_END,
263 * or NESTED.
264 * @see #AT_BEGIN
265 * @see #AT_END
266 * @see #NESTED
267 */
268 public int getScope() {
269 return scope;
270 }
271
272 // == private data
273 private String varName;
274 private String className;
275 private boolean declare;
276 private int scope;
277 }
|