The following is a list of clarifications and corrections to the JSP 1.1 final specification (dated November 30th, 1999).
This errata has been created according to the Maintenance step of the JCP process. Issues were prompted by questions from vendors, implementors and end-users; the resolutions have been discussed in a mailing list1 which includes all the original experts in the JSP 1.1 expert group still active in this area as well as additional experts. The discussion was done under the facilitation of Eduardo Pelegri-Llopart, co-author of the original JSP 1.1 specification, acting as "interpretation guru" for the JSP 1.1 specification. This errata includes all issues discussed up until April 28th, 2000.
This errata will be posted for a 30 day public review before being declared final.
All issues will be incorporated into the JSP 1.2 specification. It is still undecided if there will be additional erratas or if later clarifications will be just appear in the JSP 1.2 specification.
The errata starts with a brief list of all issues. Each issue is then described in more detail and a resolution is given. All references are to the JSP 1.1 final specification.
All Issues
1. VariableInfo: PageContext scopes of scripting variables
2. VariableInfo: Fully Qualified Class Names
3. VariableInfo: Primitive types
4. TagExtraInfo: getTagInfo method
5. Attributes in custom actions: explicit list of attributes in TLD
6. Attributes in custom actions: determining setter methods to use
7. Attributes in custom actions: conversions applicable
8. Taglib directive: resolving the uri attribute
9. Taglib directive: locating TLDs
10. Taglib directive: conflicts on uri attribute
11. Semantics of id and scope attributes in custom actions
12. jsp:setProperty and jsp:getProperty and pageContext
13. Unset attributes and tag handlers: Setting attributes
14. Unset attributes and tag handlers: Reusing instances
15. Package Name of JSP Page Implementation Object class
16. Incorrect summary of request-time attributes
17. PageContext and handling Throwable or Exception
18. XML Syntax
19. ErrorPage in JSP and web.xml
Detailed Issues
Issue 1 ·
VariableInfo: PageContext Scopes of Scripting Variables
Section 5.5 indicates that a custom action can create new scripting variables using VariableInfo values through the TagExtraInfo interface. Can these variables have PageContext scope different than "page"? In implementation terms, should the generated code do a PageContext.getAttribute(<name>) or should it make a PageContext.findAttribute(<name>)
Resolution
Scripting variables generated by a custom action may have scope page, request, session, and application.
Issue 2 ·
VariableInfo: Fully Qualified Class Names
A Custom Action can define scripting variables by associating a TagExtraInfo class with the action tag (in the TLD). If such a class has been associated, the JSP processor determines what scripting variables are defined by a given custom action instance by constructing a TagData instance to represent the attributes and their translation-time values, and then invoking the getVariableInfo() method on a TagExtraInfo class associated with this specific custom action instance.
A VariableInfo includes a class name as a String. The question is: does this String have to be a fully qualified class name (i.e. of the form package.ClassName) or can it be a short class name (i.e. of the form ClassName).
Resolution
The class name (VariableInfo.getClassName) in the returned objects are used to determine the types of the scripting variables. The class name may be a Fully Qualified Class Name, or a short class name.
If a Fully Qualified Class Name is provided, it should refer to a class that should be in the CLASSPATH for the Web Application (see Servlet 2.2 specification - essentially it is WEB-INF/lib and WEB-INF/classes). Failure to be so will lead to a translation-time error.
If a short class name is given in the VariableInfo objects, then the class name must be that of a public class in the context of the import directives of the page where the custom action appears (will check if there is a JLS verbiage to refer to). The class must also be in the CLASSPATH for the Web Application (see Servlet 2.2 specification - essentially it is WEB-INF/lib and WEB-INF/classes). Failure to be so will lead to a translation-time error.
Usage Comments:
Frequently a fully qualified class name will refer to a class that is known to the tag library and thus, delivered in the same JAR file as the tag handlers. In almost other remaining cases it will refer to a class that is in the platform on which the JSP processor is build (like J2EE). Using fully qualified class names in this manner makes the usage relatively resistant to configuration errors.
A short name is usually generated by the tag library based on some attributes passed through from the custom action user (the author), and it is thus less robust: for instance a missing import directive in the referring JSP page will lead to an invalid short name class and a translation error.
We will further evolve this in JSP 1.2
Issue 3 ·
VariableInfo: Primitive Types
Can a custom action create a scripting variable (using VariableInfo) of a primitive type?"
Resolution
The answer is NO. This is because the only way to denote the type of the variable is using a String to denote the class name. The workaround is to use "boxed" types.
We discovered this problem late in the design cycle; different approaches can be taken to remove the limitation (use a Class object, use "Integer.TYPE"), but (a) it was too late to rock the boat, and (b) it is unclear that this is a big limitation.
Issue 4 ·
TagExtraInfo: getTagInfo method
TagExtraInfo is to be used in a tag library to perform translation-time actions, be them validation (isValid()) or scripting variable generation (getVariableInfo()). The intention was that information on the Tag Library Descriptor is to be available for this translation-time actions, and the intention was that this information would be available to the TagExtraInfo methods via invocations on getTagInfo().
Unfortunately, the javadoc description for TagExtraInfo.getTagInfo() does not indicate what value it should return.
In JSP 1.1, getTagInfo() is final and returns the value of the private variable tagInfo, which is set only by setTagInfo(). The javadoc should indicate who is responsible for invoking setTagInfo(), when, and with what value.
Resolution
It is the responsibility of the JSP translator that the initial value to be returned by calls to getTagInfo() corresponds to a TagInfo object for the tag being translated. If an explicit call to setTagInfo() is done, then the object passed will be returned in subsequent calls to getTagInfo().
In JSP 1.1, the only way to affect the value returned by getTagInfo() is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is to be called by the JSP translator, with a TagInfo object that corresponds to the tag being translated. The call should happen before any invocation on isValid() and before any invocation on getVariableInfo().
Issue 5 ·
Explicit list of attributes in TLD for custom actions
What attributes are visible (to the JSP container)?
Resolution
Issue 6 ·
Setter methods to use in a custom actions
Which setters method should be used when assigning a value to an attribute of a custom action?
Resolution
Use the JavaBeans introspector on the Tag handler class, then use the setter method associated with the property that has the same name as the attribute in question. An implication (unclear in the JavaBeans specification) is that there is only one setter per property.
There has been some talk that perhaps write-only properties would disappear from the JavaBeans specification. We have passed the feedback that write-only properties are useful for JSP beans and there are no plans to remove them at the moment.
Issue 7 ·
Conversions in attributes in custom actions
What type of conversions are applied to attribute values of a custom action. Specifically, what is done to a request-time attribute value, and what is done to a literal string.
Resolution
A request-time attribute value is passed with no conversion.
A literal string is converted following the rules in Table 2-4, section 2.13.2.
Issue 8 ·
TagLib Directive: Resolving the uri Attribute
The details of interpreting the uri attribute of a taglib directive is split into two issues. The first issue describes how to resolve the uri attribute of a taglib directive into what is called here a TLD_URI; the next issue addresses how to use that TLD_URI to get a TLD.
For example, the first determines that a given uri attribute maps into "/tlds/mylibrary.tld", and the second can just use "/tlds/mylibrary.tld" to get the TLD content. But, as indicated below, if the uri had mapped into "/WEB-INF/lib/mylibrary.jar" the second step will also say that this JAR is to be inspected to obtain the TLD that is at META-INF/taglib.tld.
Resolution
The description is somewhat verbose to make it more clear (we hope)
Definitions
An "absolute URI" is one that starts with a protocol and host. A "relative URI specification" is as in section 2.5.2, i.e. one without the protocol and host part.
All steps are described as if they were taken, but an implementation can use a different implementation strategy as long as the result is preserved.
Processing WEB.XML.
The web.xml for the web application may contain one or more <taglib></taglib> elements. All such elements are considered. The result of "processing" web.xml is, per each taglib element, two values, a TAGLIB_URI and a TAGLIB_LOCATION, as follows:
1 The value of the <taglib-uri> subelement is the TAGLIB_URI. This TAGLIB_URI may be an absolute URI, or a relative URI spec starting with "/" or one not starting with "/".
2a If the <taglib-location> subelement is some relative URI specification that starts with a "/" the TAGLIB_LOCATION is this URI.
2b If the <taglib-location> subelement is some relative URI specification that does not start with "/", the TAGLIB_LOCATION is the resolution of the URI relative to /WEB-INF/web.xml (the result of this resolution is a relative URI specification that starts with "/").
Processing a taglib directive to obtain a TLD location
We describe how to resolve a taglib directive to obtain a relative URI specification starting with "/" that can later be used to get the TLD content. We will use TLD_URI to refer to this result.
Case A - <%@ taglib uri="ABS_URI" prefix="foo" %>
1 Look in the processed web.xml for a taglib entry whose TAGLIB_URI is ABS_URI.
where ABS_URI is an absolute URI.
2a If found, the corresponding TABLIB_LOCATION is the value to assign to TLD_URI
2b If not found, a translation error is raised.
3 Use TLD_URI to locate the TLD (see issue 9). If the TLD cannot be located a translation error is raised.
Case B - <%@ taglib uri="ROOT_REL_URI" prefix="foo" %>
1 Look in the processed web.xml for a taglib entry whose TAGLIB_URI is ROOT_REL_URI.
where ROOT_REL_URI is a relative URI that starts with "/"
2a If found, the TABLIB_LOCATION for the taglib entry is the value to assign to TLD_URI.
2b If no such entry is found, ROOT_REL_URI is the value to assign to TLD_URI.
3 Use TLD_URI to locate the TLD (see issue 9). If the TLD cannot be located a translation error is raised.
Case C - <%@ taglib uri="NOROOT_REL_URI" prefix="foo" %>
1 Look in the processed web.xml for a taglib entry whose TAGLIB_URI is NOROOT_REL_URI.
where NOROOT_REL_URI is a relative URI that does not start with "/"
2a If found, the TABLIB_LOCATION for the taglib entry is the value to assign to TLD_URI.
2b If no such entry is found, resolve NOROOT_REL_URI relative to the current JSP page where the directive appears. Let ROOT_REL_URI be the resolved value (this is a relative URI specification that starts with "/" - by definition-). ROOT_REL_URI is the value to assign to TLD_URI.
3 Use TLD_URI to locate the TLD (see issue 9). If the TLD cannot be located a translation error is raised.
Issue 9 ·
Taglib directive: Locating TLDs
This is the second part of how to interpret the uri attribute of a taglib directive. Once the TLD_URI has been resolved according to the resolution of Issue 8, how to locate the TLD.
Resolution
There are two cases. In both cases the TLD_URI is to be interpreted relative to the root of the Web Application.
In the first case the TLD_URI refers to a TLD file directly..
In the second case, the TLD_URI refers to a JAR file. If so, that JAR file should have a TLD at location META-INF/taglib.tld.
Issue 10 ·
Taglib directive: Conflicts on uri Attribute
The spec doesn't say what should happen when two taglib directives are encountered that use the same prefix but have different URIs.
Resolution
It is a fatal translation error for two taglib directives to resolve to two different TLD_URI (using the notation of Issues 8 and 9).
Issue 11 ·
Semantics of id and scope attributes in Custom Actions
It is unclear what are the responsibilities of a JSP container regarding the semantics of the id and scope attributes for custom actions. It is unclear what type of validation will be performed
Resolution
A tag handler is responsible of implementing all its attributes, including id and scope, and that there is no validation that ids and scopes of a custom action will behave as described in 2.12.2 and 2.12.3.
Details may be revisited for 1.2
Issue 12 ·
jsp:setProperty and jsp:getProperty and PageContext
What objects can be referenced by jsp:setProperty and jsp:getProperty through the name attribute. How are these objects to be located?
Resolution
jsp:setProperty and jsp:getProperty both have a name attribute. This name will refer to an object that obtained from the pageContext object through its findAttribute() method.
The object named by the name must have been "introduced" to the JSP processor using either the jsp:useBean action or a custom action with an associated VariableInfo entry for this name.
Note: a consequence of the previous paragraph is that objects that are stored in, say, the session by a front component are not automatically visible to jsp:setProperty and jsp:getProperty actions in that page unless a jsp:useBean action, or some other action, makes them visible.
If the JSP processor can ascertain that there is an alternate way guaranteed to access the same object, it can use that information. For example it may use a scripting variable, but it must guarantee that no intervening code has invalidated the copy held by the scripting variable - i.e. the truth is always the value held by the pageContext object.
Issue 13 ·
Unset Attributes and Tag Handlers, Setting values
What should be done with unspecified attributes in a custom action?
Resolution
Unspecified attributes/properties should not be set (using a setter method).
Issue 14 ·
Unset Attributes and Tag Handlers: Reusing Instances
Consider the following JSP fragment:
<foo:bar attr1="abc" attr2="def"/>
<foo:bar attr1="xyz"/>
How many tag handler instances should or can be used?
Resolution
In the above example, two tag handler instances are needed because there is no mechanism in JSP 1.1 to reset a tag handler instance to its uninitialized state.
Given the semantics of JSP 1.1, handler instances can only be easily reused if they correspond to actions with the same attributes (not necessarily the same value). For example,
<x:foo att1="one" att2="two"/>
<x:foo att1="HELLO" att2="BYE"/>
these two can reuse the same handler instance: just do h.setAtt1("HELLO"); h.setAtt2("BYE"); to prepare the handler for the second action.
But in this case
<x:foo att1="one" att2="two"/>
<x:foo att1="HELLO"/>
the second action cannot use the tag handler for the first unless it invokes a release() on it.
We noticed this "feature" late in the spec and briefly considered adding a resetToDefaultValue() method but decided to wait and see whether it was deserved and not to perturb the implementation that late in the specification cycle. This decision may be revisited in JSP 1.2 with additional information.
Issue 15 ·
Package Name of JSP Page Implementation Object class
The JSP 1.1 spec does not indicate the (Java) package of the JSP Page implementation object corresponding to a JSP page (although TABLE 4-1 seems to suggest it is using the unnamed package). This has some implications for validity of some JSP pages, most notably accessing classes that are in the unnamed package.
Resolution
All the vendors polled are creating the JSP Page implementation object in a named package. The package used is implementation-dependent, and may even vary between one JSP and another, so minimal assumptions should be made.
One implication of this semantics is that classes in the unnamed package should not be used without an explicit "import" of the class.
Issue 16 ·
Incorrect summary of request-time attributes
The following attributes accept request-time attribute expressions:
The value and beanName attributes of jsp:setProperty (2.13.2).
The page attribute of jsp:include (2.13.4).
The page attribute of jsp:forward (2.13.5).
The value attribute of jsp:param (2.13.6).
There is no beanName in jsp:setProperty.
Resolution
The following attributes accept request-time attribute expressions:
The value attribute of jsp:setProperty (2.13.2).
The beanName attribute of jsp:useBean (2.13.1).
The page attribute of jsp:include (2.13.4).
The page attribute of jsp:forward (2.13.5).
The value attribute of jsp:param (2.13.6).
Issue 17 ·
PageContext and handling Throwable or Exception
There seems to be an inconsistency in the JSP 1.1 specification.
The implicit object "exception" is described as being a Throwable in TABLE 2-3 (Section 2.8). This is consistent with the "errorPage" attribute of the "page" directive (Section 2.7.1.1, pp47) where it says: "... URL to a resource to which any Java ... Throwable object... are forwarded..."
On the other hand, the methods in PageContext that are intended to be used to implement this functionality portably assume this is really an Exception. For example:
Figure F-1 (page 118)
method "Exception PageContext.getException()" (Section 6.1.4.2, page 119)
method "void PageContext.handlePageException(Exception)" (same section, page 120).
Resolution
Yes, there is some level of inconsistency that fell through the cracks. It can be described as a bug in the spec but it is too late for this type of changes, so we will punt on this for 1.1 and instead solve it in 1.2. The obvious solution is to add new methods like:
Throwable PageContext.getThrowable()
void PageContext.handlePageThrowable(Throwable)
Not pretty but works. In the meantime, the vendors will need to do use something besides PageContext if they are to implement the full semantics of exception being a Throwable. Sorry.
Issue 18 ·
XML Syntax
Exactly where can the "alternate XML syntax" appear?
Resolution
The spec only mentions the alternate XML syntax in the context of describing the XML document that corresponds to a JSP page. This equivalent XML document is not required to be accepted by any JSP container.
The background for the XML syntax is that we had initially intended it to be used by authoring tools but we ran out of time to debug the mapping in JSP 1.0. We intended to define the mapping fully in JSP 1.1 but then we realized there were multiple issues in this area and we decided to postpone any further work on the mapping until after JSP 1.1.
Note specially that we will not consider we have a backwards compatibility commitment between JSP 1.2 and JSP 1.1 regarding the details of the mapping between a JSP page and its equivalent XML document.
Issue 19 ·
ErrorPage in JSP and web.xml
JSP pages have an errorPage mechanism and so does web.xml. When does each apply is not totally clear in the specification.
Resolution
The JSP errorpage applies first, then web.xml.
1 Please send mail to pelegri@eng.sun.com if you want to be added to this mailing list (jsp-tfaq-comments@eng.sun.com). As a guideline most current members are actively involved in implementing the specification as a Container author, as an authoring tool, or for a significant tag library.