Package: VariableInfo

VariableInfo

name	instruction	branch	complexity	line	method
VariableInfo(String, String, boolean, int)	M: 15 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 6 C: 0 0%	M: 1 C: 0 0%
getClassName()	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
getDeclare()	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
getScope()	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
getVarName()	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%

Coverage

1: /*
2: * Copyright (c) 1997, 2021 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 value of the `scope` attribute does not affect the visibility of the variables within the generated program. It
65: * affects where and thus for how long there will be additional references to the object denoted by the variable.
66: *
67: * <p>
68: * The result of the invocation on getVariableInfo is an array of VariableInfo objects. Each such object describes a
69: * scripting variable by providing its name, its type, whether the variable is new or not, and what its scope is. Scope
70: * is best described through a picture:
71: *
72: * <p>
73: * <IMG src="doc-files/VariableInfo-1.gif" alt="NESTED, AT_BEGIN and AT_END Variable Scopes">
74: *
75: * <p>
76: * The JSP 2.0 specification defines the interpretation of 3 values:
77: *
78: * <ul>
79: * <li>NESTED, if the scripting variable is synchronized with the calling page between the start tag and the end tag of
80: * the action that defines it.
81: * <li>AT_BEGIN, if the scripting variable is synchronized with the calling page from the start tag of the action that
82: * defines it until the end of the scope.
83: * <li>AT_END, if the scripting variable is synchronized with the calling page after the end tag of the action that
84: * defines it until the end of the scope.
85: * </ul>
86: *
87: * The scope value for a variable implies what methods may affect its value and thus where synchronization is needed as
88: * illustrated by the table below. <b>Note:</b> the synchronization of the variable(s) will occur <em>after</em> the
89: * respective method has been called.
90: *
91: * <blockquote>
92: * <table style="background-color:#999999">
93: * <caption>Variable Synchronization Points</caption>
94: * <tr>
95: * <td valign="top" colspan="6" style="background-color:#999999"><u><b>Variable Synchronization Points</b></u><br>
96: * </td>
97: * </tr>
98: * <tr>
99: * <th valign="top" style="background-color:#c0c0c0"> </th>
100: * <th valign="top" style="background-color:#c0c0c0">doStartTag()</th>
101: * <th valign="top" style="background-color:#c0c0c0">doInitBody()</th>
102: * <th valign="top" style="background-color:#c0c0c0">doAfterBody()</th>
103: * <th valign="top" style="background-color:#c0c0c0">doEndTag()</th>
104: * <th valign="top" style="background-color:#c0c0c0">doTag()</th>
105: * </tr>
106: * <tr>
107: * <td valign="top" style="background-color:#c0c0c0"><b>Tag<br>
108: * </b></td>
109: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
110: * </td>
111: * <td valign="top" style="background-color:#ffffff"><br>
112: * </td>
113: * <td valign="top" style="background-color:#ffffff"><br>
114: * </td>
115: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
116: * </td>
117: * <td valign="top" style="background-color:#ffffff"><br>
118: * </td>
119: * </tr>
120: * <tr>
121: * <td valign="top" style="background-color:#c0c0c0"><b>IterationTag<br>
122: * </b></td>
123: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
124: * </td>
125: * <td valign="top" style="background-color:#ffffff"><br>
126: * </td>
127: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
128: * </td>
129: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
130: * </td>
131: * <td valign="top" style="background-color:#ffffff"><br>
132: * </td>
133: * </tr>
134: * <tr>
135: * <td valign="top" style="background-color:#c0c0c0"><b>BodyTag<br>
136: * </b></td>
137: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, NESTED<sup>1</sup><br>
138: * </td>
139: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, NESTED<sup>1</sup><br>
140: * </td>
141: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, NESTED<br>
142: * </td>
143: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
144: * </td>
145: * <td valign="top" style="background-color:#ffffff"><br>
146: * </td>
147: * </tr>
148: * <tr>
149: * <td valign="top" style="background-color:#c0c0c0"><b>SimpleTag<br>
150: * </b></td>
151: * <td valign="top" style="background-color:#ffffff"><br>
152: * </td>
153: * <td valign="top" style="background-color:#ffffff"><br>
154: * </td>
155: * <td valign="top" style="background-color:#ffffff"><br>
156: * </td>
157: * <td valign="top" style="background-color:#ffffff"><br>
158: * </td>
159: * <td valign="top" style="background-color:#ffffff">AT_BEGIN, AT_END<br>
160: * </td>
161: * </tr>
162: * </table>
163: * <sup>1</sup> Called after <code>doStartTag()</code> if <code>EVAL_BODY_INCLUDE</code> is returned, or after
164: * <code>doInitBody()</code> otherwise. </blockquote>
165: *
166: * <p>
167: * <B>Variable Information in the TLD</B>
168: * <p>
169: * Scripting variable information can also be encoded directly for most cases into the Tag Library Descriptor using the
170: * <variable> subelement of the <tag> element. See the JSP specification.
171: */
172: public class VariableInfo {
173:
174: /**
175: * Scope information that scripting variable is synchronized with the calling page only within the start/end tags.
176: */
177: public static final int NESTED = 0;
178:
179: /**
180: * Scope information that scripting variable is synchronized with the calling page after start tag.
181: */
182: public static final int AT_BEGIN = 1;
183:
184: /**
185: * Scope information that scripting variable is synchronized with the calling page after end tag.
186: */
187: public static final int AT_END = 2;
188:
189: /**
190: * Constructor These objects can be created (at translation time) by the TagExtraInfo instances.
191: *
192: * @param varName The name of the scripting variable
193: * @param className The type of this variable
194: * @param declare If true, it is a new variable (in some languages this will require a declaration)
195: * @param scope Indication of the synchronization scope of the variable
196: */
197: public VariableInfo(String varName, String className, boolean declare, int scope) {
198: this.varName = varName;
199: this.className = className;
200: this.declare = declare;
201: this.scope = scope;
202: }
203:
204: // Accessor methods
205:
206: /**
207: * Returns the name of the scripting variable.
208: *
209: * @return the name of the scripting variable
210: */
211: public String getVarName() {
212: return varName;
213: }
214:
215: /**
216: * Returns the type of this variable.
217: *
218: * @return the type of this variable
219: */
220: public String getClassName() {
221: return className;
222: }
223:
224: /**
225: * Returns whether this is a new variable. If so, in some languages this will require a declaration.
226: *
227: * @return whether this is a new variable.
228: */
229: public boolean getDeclare() {
230: return declare;
231: }
232:
233: /**
234: * Returns the synchronization scope of the variable.
235: *
236: * @return the synchronization scope of the variable, either AT_BEGIN, AT_END, or NESTED.
237: * @see #AT_BEGIN
238: * @see #AT_END
239: * @see #NESTED
240: */
241: public int getScope() {
242: return scope;
243: }
244:
245: // == private data
246: private String varName;
247: private String className;
248: private boolean declare;
249: private int scope;
250: }