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