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     
019    package javax.servlet.jsp.tagext;
020    
021    /**
022     * Information on the scripting variables that are created/modified by
023     * a tag (at run-time). This information is provided by TagExtraInfo
024     * classes and it is used by the translation phase of JSP.
025     *
026     * <p>
027     * Scripting variables generated by a custom action have an associated 
028     * scope of either AT_BEGIN, NESTED, or AT_END.
029     *
030     * <p>
031     * The class name (VariableInfo.getClassName) in the returned objects
032     * is used to determine the types of the scripting variables.
033     * Note that because scripting variables are assigned their values
034     * from scoped attributes which cannot be of primitive types,
035     * &quot;boxed&quot; types such as <code>java.lang.Integer</code> must 
036     * be used instead of primitives.
037     *
038     * <p>
039     * The class name may be a Fully Qualified Class Name, or a short
040     * class name.
041     *
042     * <p>
043     * If a Fully Qualified Class Name is provided, it should refer to a
044     * class that should be in the CLASSPATH for the Web Application (see
045     * Servlet 2.4 specification - essentially it is WEB-INF/lib and
046     * WEB-INF/classes). Failure to be so will lead to a translation-time
047     * error.
048     *
049     * <p>
050     * If a short class name is given in the VariableInfo objects, then
051     * the class name must be that of a public class in the context of the
052     * import directives of the page where the custom action appears. 
053     * The class must also be in the CLASSPATH for the Web Application 
054     * (see Servlet 2.4 specification - essentially it is WEB-INF/lib and
055     * WEB-INF/classes). Failure to be so will lead to a translation-time
056     * error.
057     *
058     * <p><B>Usage Comments</B>
059     * <p>
060     * Frequently a fully qualified class name will refer to a class that
061     * is known to the tag library and thus, delivered in the same JAR
062     * file as the tag handlers. In most other remaining cases it will
063     * refer to a class that is in the platform on which the JSP processor
064     * is built (like J2EE). Using fully qualified class names in this
065     * manner makes the usage relatively resistant to configuration
066     * errors.
067     *
068     * <p>
069     * A short name is usually generated by the tag library based on some
070     * attributes passed through from the custom action user (the author),
071     * and it is thus less robust: for instance a missing import directive
072     * in the referring JSP page will lead to an invalid short name class
073     * and a translation error.
074     *
075     * <p><B>Synchronization Protocol</B>
076     *
077     * <p>
078     * The result of the invocation on getVariableInfo is an array of
079     * VariableInfo objects.  Each such object describes a scripting
080     * variable by providing its name, its type, whether the variable is
081     * new or not, and what its scope is.  Scope is best described through
082     * a picture:
083     *
084     * <p>
085     * <IMG src="doc-files/VariableInfo-1.gif"
086     *      alt="NESTED, AT_BEGIN and AT_END Variable Scopes"/>
087     *
088     *<p>
089     * The JSP 2.0 specification defines the interpretation of 3 values:
090     * 
091     * <ul>
092     * <li> NESTED, if the scripting variable is available between
093     * the start tag and the end tag of the action that defines it.
094     * <li>
095     * AT_BEGIN, if the scripting variable is available from the start tag
096     * of the action that defines it until the end of the scope.
097     * <li> AT_END, if the scripting variable is available after the end tag
098     * of the action that defines it until the end of the scope.
099     * </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