Package: VariableInfo
VariableInfo
name | instruction | branch | complexity | line | method | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
VariableInfo(String, String, boolean, int) |
|
|
|
|
|
||||||||||||||||||||
getClassName() |
|
|
|
|
|
||||||||||||||||||||
getDeclare() |
|
|
|
|
|
||||||||||||||||||||
getScope() |
|
|
|
|
|
||||||||||||||||||||
getVarName() |
|
|
|
|
|
Coverage
1: /*
2: * Copyright (c) 1997, 2019 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: * Copyright 2004 The Apache Software Foundation
5: *
6: * Licensed under the Apache License, Version 2.0 (the "License");
7: * you may not use this file except in compliance with the License.
8: * You may obtain a copy of the License at
9: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing, software
13: * distributed under the License is distributed on an "AS IS" BASIS,
14: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15: * See the License for the specific language governing permissions and
16: * limitations under the License.
17: */
18:
19: package jakarta.servlet.jsp.tagext;
20:
21: /**
22: * Information on the scripting variables that are created/modified by a tag (at run-time). This information is provided
23: * by TagExtraInfo classes and it is used by the translation phase of JSP.
24: *
25: * <p>
26: * Scripting variables generated by a custom action have an associated scope of either AT_BEGIN, NESTED, or AT_END.
27: *
28: * <p>
29: * The class name (VariableInfo.getClassName) in the returned objects is used to determine the types of the scripting
30: * variables. Note that because scripting variables are assigned their values from scoped attributes which cannot be of
31: * primitive types, "boxed" types such as <code>java.lang.Integer</code> must be used instead of primitives.
32: *
33: * <p>
34: * The class name may be a Fully Qualified Class Name, or a short class name.
35: *
36: * <p>
37: * If a Fully Qualified Class Name is provided, it should refer to a class that should be in the CLASSPATH for the Web
38: * Application (see Servlet 2.4 specification - essentially it is WEB-INF/lib and WEB-INF/classes). Failure to be so
39: * will lead to a translation-time error.
40: *
41: * <p>
42: * If a short class name is given in the VariableInfo objects, then the class name must be that of a public class in the
43: * context of the import directives of the page where the custom action appears. The class must also be in the CLASSPATH
44: * for the Web Application (see Servlet 2.4 specification - essentially it is WEB-INF/lib and WEB-INF/classes). Failure
45: * to be so will lead to a translation-time error.
46: *
47: * <p>
48: * <B>Usage Comments</B>
49: * <p>
50: * Frequently a fully qualified class name will refer to a class that is known to the tag library and thus, delivered in
51: * the same JAR file as the tag handlers. In most other remaining cases it will refer to a class that is in the platform
52: * on which the JSP processor is built (like Jakarta EE). Using fully qualified class names in this manner makes the usage
53: * relatively resistant to configuration errors.
54: *
55: * <p>
56: * A short name is usually generated by the tag library based on some attributes passed through from the custom action
57: * user (the author), and it is thus less robust: for instance a missing import directive in the referring JSP page will
58: * lead to an invalid short name class and a translation error.
59: *
60: * <p>
61: * <B>Synchronization Protocol</B>
62: *
63: * <p>
64: * The result of the invocation on getVariableInfo is an array of VariableInfo objects. Each such object describes a
65: * scripting variable by providing its name, its type, whether the variable is new or not, and what its scope is. Scope
66: * is best described through a picture:
67: *
68: * <p>
69: * <IMG src="doc-files/VariableInfo-1.gif" alt="NESTED, AT_BEGIN and AT_END Variable Scopes">
70: *
71: * <p>
72: * The JSP 2.0 specification defines the interpretation of 3 values:
73: *
74: * <ul>
75: * <li>NESTED, if the scripting variable is available between the start tag and the end tag of the action that defines
76: * it.
77: * <li>AT_BEGIN, if the scripting variable is available from the start tag of the action that defines it until the end
78: * of the scope.
79: * <li>AT_END, if the scripting variable is available after the end tag of the action that defines it until the end of
80: * the scope.
81: * </ul>
82: *
83: * The scope value for a variable implies what methods may affect its value and thus where synchronization is needed as
84: * illustrated by the table below. <b>Note:</b> the synchronization of the variable(s) will occur <em>after</em> the
85: * respective method has been called.
86: *
87: * <blockquote>
88: * <table cellpadding="2" cellspacing="2" border="0" width="55%" style="background-color:#999999" summary="Variable
89: * Synchronization Points">
90: * <tr align="center">
91: * <td valign="top" colspan="6" style="background-color:#999999"><u><b>Variable Synchronization Points</b></u><br>
92: * </td>
93: * </tr>
94: * <tr>
95: * <th valign="top" style="background-color:#c0c0c0"> </th>
96: * <th valign="top" style="background-color:#c0c0c0" align="center">doStartTag()</th>
97: * <th valign="top" style="background-color:#c0c0c0" align="center">doInitBody()</th>
98: * <th valign="top" style="background-color:#c0c0c0" align="center">doAfterBody()</th>
99: * <th valign="top" style="background-color:#c0c0c0" align="center">doEndTag()</th>
100: * <th valign="top" style="background-color:#c0c0c0" align="center">doTag()</th>
101: * </tr>
102: * <tr>
103: * <td valign="top" style="background-color:#c0c0c0"><b>Tag<br>
104: * </b></td>
105: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
106: * </td>
107: * <td valign="top" align="center" style="background-color:#ffffff"><br>
108: * </td>
109: * <td valign="top" align="center" style="background-color:#ffffff"><br>
110: * </td>
111: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
112: * </td>
113: * <td valign="top" align="center" style="background-color:#ffffff"><br>
114: * </td>
115: * </tr>
116: * <tr>
117: * <td valign="top" style="background-color:#c0c0c0"><b>IterationTag<br>
118: * </b></td>
119: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
120: * </td>
121: * <td valign="top" align="center" style="background-color:#ffffff"><br>
122: * </td>
123: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
124: * </td>
125: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
126: * </td>
127: * <td valign="top" align="center" style="background-color:#ffffff"><br>
128: * </td>
129: * </tr>
130: * <tr>
131: * <td valign="top" style="background-color:#c0c0c0"><b>BodyTag<br>
132: * </b></td>
133: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, NESTED<sup>1</sup><br>
134: * </td>
135: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, NESTED<sup>1</sup><br>
136: * </td>
137: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
138: * </td>
139: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
140: * </td>
141: * <td valign="top" align="center" style="background-color:#ffffff"><br>
142: * </td>
143: * </tr>
144: * <tr>
145: * <td valign="top" style="background-color:#c0c0c0"><b>SimpleTag<br>
146: * </b></td>
147: * <td valign="top" align="center" style="background-color:#ffffff"><br>
148: * </td>
149: * <td valign="top" align="center" style="background-color:#ffffff"><br>
150: * </td>
151: * <td valign="top" align="center" style="background-color:#ffffff"><br>
152: * </td>
153: * <td valign="top" align="center" style="background-color:#ffffff"><br>
154: * </td>
155: * <td valign="top" align="center" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
156: * </td>
157: * </tr>
158: * </table>
159: * <sup>1</sup> Called after <code>doStartTag()</code> if <code>EVAL_BODY_INCLUDE</code> is returned, or after
160: * <code>doInitBody()</code> otherwise. </blockquote>
161: *
162: * <p>
163: * <B>Variable Information in the TLD</B>
164: * <p>
165: * Scripting variable information can also be encoded directly for most cases into the Tag Library Descriptor using the
166: * <variable> subelement of the <tag> element. See the JSP specification.
167: */
168: public class VariableInfo {
169:
170: /**
171: * Scope information that scripting variable is visible only within the start/end tags.
172: */
173: public static final int NESTED = 0;
174:
175: /**
176: * Scope information that scripting variable is visible after start tag.
177: */
178: public static final int AT_BEGIN = 1;
179:
180: /**
181: * Scope information that scripting variable is visible after end tag.
182: */
183: public static final int AT_END = 2;
184:
185: /**
186: * Constructor These objects can be created (at translation time) by the TagExtraInfo instances.
187: *
188: * @param varName The name of the scripting variable
189: * @param className The type of this variable
190: * @param declare If true, it is a new variable (in some languages this will require a declaration)
191: * @param scope Indication on the lexical scope of the variable
192: */
193: public VariableInfo(String varName, String className, boolean declare, int scope) {
194: this.varName = varName;
195: this.className = className;
196: this.declare = declare;
197: this.scope = scope;
198: }
199:
200: // Accessor methods
201:
202: /**
203: * Returns the name of the scripting variable.
204: *
205: * @return the name of the scripting variable
206: */
207: public String getVarName() {
208: return varName;
209: }
210:
211: /**
212: * Returns the type of this variable.
213: *
214: * @return the type of this variable
215: */
216: public String getClassName() {
217: return className;
218: }
219:
220: /**
221: * Returns whether this is a new variable. If so, in some languages this will require a declaration.
222: *
223: * @return whether this is a new variable.
224: */
225: public boolean getDeclare() {
226: return declare;
227: }
228:
229: /**
230: * Returns the lexical scope of the variable.
231: *
232: * @return the lexical scope of the variable, either AT_BEGIN, AT_END, or NESTED.
233: * @see #AT_BEGIN
234: * @see #AT_END
235: * @see #NESTED
236: */
237: public int getScope() {
238: return scope;
239: }
240:
241: // == private data
242: private String varName;
243: private String className;
244: private boolean declare;
245: private int scope;
246: }