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