Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 2 (10.1.2) B14014-02 |
|
Previous |
Next |
Because of additional support for XML introduced in the JSP 1.2 specification, JavaServer Pages can increasingly be seen as an effective model for producing XML documents. With these enhancements, JSP technology becomes more complementary to XML technology and more accessible to XML tools. Another benefit of JSP XML support is that page validation becomes more powerful and comprehensive.
This chapter describes JavaServer Pages support for XML. This includes support for XML-style equivalents to JSP syntactical elements, and the concept of the "XML view" of a JSP page. These features were added in the JSP 1.2 specification, although the JSP 1.1 specification included optional support for JSP XML syntax and defined the syntax.
The chapter includes the following sections:
For information about additional JSP support for XML and XSL, furnished in OC4J through custom tags, refer to the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.
For general information about XML, refer to the XML specification at the following Web site:
http://www.w3.org/XML/
Traditional JSP constructs, such as <%@ page...>
directives, <%@ include... >
directives, <%...%>
for scriptlets, <%!...%>
for declarations, and <%=...%>
for expressions, are not syntactically valid within an XML document. This issue was first addressed in the JSP 1.1 specification by defining equivalent XML-compatible syntax. In JSP 1.1, however, support for this syntax by a JSP container was optional.
Beginning with the JSP 1.2 specification, there is more complete support for XML-compatible JSP syntax, adding features and requiring support by compliant JSP containers.
Note: Prior to Oracle9iAS Release 2 (9.0.3), the OC4J JSP container supported the optional XML-alternative syntax of the JSP 1.1 specification. The JSP container now replaces this implementation with full XML support as prescribed by the current JSP specification. The JSP 1.1 syntax itself remains unchanged, but there are now additional aspects of JSP XML support, as described in this chapter.In addition, under the JSP 1.1 specification, you could intermix traditional syntax and XML-alternative syntax within a page. This is no longer true. |
The term JSP XML document (called JSP document in the JSP specification) refers to a JSP page that uses this XML-compatible syntax. The syntax includes, among other things, a root element and elements that serve as alternatives to JSP directives, declarations, expressions, and scriptlets. (Standard tag actions and custom tag actions already follow XML conventions.) See "Details of JSP XML Documents" for details.
A JSP XML document is well formed in pure XML syntax and is namespace-aware. It uses XML namespaces to specify the JSP XML core syntax and the syntaxes of any custom tag libraries used. A traditional JSP page, by contrast, is typically not an XML document.
A JSP XML document has the same file name extension as a traditional JSP page, .jsp
. However, it is recognizable by the JSP container as an XML document because of its root element, <jsp:root>
. Additionally, the semantic model for JSP XML documents is the same as for traditional pages. A JSP XML document dictates the same set of actions and results as a traditional page with equivalent syntax. Processing of white space follows XSLT conventions. Once the nodes of a JSP XML document have been identified, textual nodes that have only white space are dropped from the document, except within <jsp:text>
elements for template data. The content of <jsp:text>
elements is kept exactly as is.
In a JSP 1.2 environment, a JSP XML document can be processed directly by the JSP container. You can also use a JSP XML document with XML development tools or other XML tools, which will become increasingly important as such tools become more popular and prevalent.
Another key feature of XML support in the JSP specification is the JSP XML view. The specification defines this as "the mapping between a JSP page, written in either XML syntax or traditional syntax, and an XML document describing it". The JSP container generates it during translation.
In the case of a JSP XML document, the JSP XML view is similar to the page source. One difference is that the XML view is expanded according to any include
directives. Another (optional) difference, for JSP containers that support it, is that ID attributes for improved error reporting are added to all XML elements.
In the case of a traditional JSP page, the JSP container performs a series of transformations to create the XML view from the page. See "Details of the JSP XML View" for details.
The key function of the JSP XML view is its use for page validation. Beginning with the JSP 1.2 specification, any tag library can have a <validator>
element in its TLD file to specify a class that can perform validation. Such classes are referred to as tag-library-validator (TLV) classes. The purpose of a TLV class is to validate any JSP page that uses the tag library, verifying that the page adheres to any desired constraints that you have implemented. A validator class uses the JSP XML view as the source for its validation.
In summary, you can optionally use JSP XML syntax to create a JSP page that is XML-compatible. The JSP XML view, in contrast, is a function of the JSP container, for use in page validation.
This section describes the syntax of JSP XML documents in further detail. For a complete description, refer to the Sun Microsystems JavaServer Pages Specification.
Important: You cannot intermix JSP traditional syntax and JSP XML syntax in a single file. You can, however, make use of both syntaxes together in a single translation unit through the use ofinclude directives. For example, a traditional JSP page can include a JSP XML document.
|
Note: A JSP XML document does not use aDOCTYPE statement.
|
JSP XML syntax includes the following:
A root element, <jsp:root ...>
, which includes a namespace specification for the JSP XML core syntax and namespace specifications for any custom tag libraries that are used
JSP directive elements, for page
and include
directives
Note: A separate mechanism, throughxmlns attributes of the root element, is equivalent to the use of taglib directives. "JSP XML root Element and JSP XML Namespaces" describes this.
|
JSP declaration elements
JSP expression elements
JSP scriptlet elements
JSP standard action elements
JSP custom action elements
A text element, <jsp:text ... >
, for template (static) data
Other XML elements, if desired, pertaining to template data
The following subsection describes each of these types of elements, followed by an example comparing a traditional JSP page to the equivalent JSP XML document.
Table 5-1 summarizes JSP XML syntax, comparing it to JSP traditional syntax as applicable.
Table 5-1 JSP XML Syntax Versus JSP Traditional Syntax
JSP XML Syntax | Corresponding JSP Traditional Syntax |
---|---|
Root element: <jsp:root
xmlns:jsp=...
xmlns:xxx =...
...
version=...
/>
The root element indicates the standard JSP XML namespace, XML namespaces for any custom tag libraries, and a JSP version number (required). See "JSP XML root Element and JSP XML Namespaces".
|
The |
JSP <jsp:directive.page ... /> See "JSP XML Directive Elements".
|
<%@ page ... %> |
JSP <jsp:directive.include ... /> See "JSP XML Directive Elements".
|
<%@ include ... %> |
JSP declaration element: <jsp:declaration>
declaration
</jsp:declaration>
See "JSP XML Declaration, Expression, and Scriptlet Elements".
|
<%! declaration %>
|
JSP expression element: <jsp:expression>
expression
</jsp:expression>
See "JSP XML Declaration, Expression, and Scriptlet Elements".
|
<%= expression %>
|
JSP scriptlet element: <jsp:scriptlet>
code fragment
</jsp:scriptlet>
See "JSP XML Declaration, Expression, and Scriptlet Elements".
|
<% code fragment %>
|
JSP standard action, such as See "JSP XML Standard Action and Custom Action Elements".
|
JSP standard action The traditional standard action syntax is already XML-compatible. |
JSP custom action (any custom tag) See "JSP XML Standard Action and Custom Action Elements".
|
JSP custom action The traditional custom action syntax is already XML-compatible. |
JSP request-time attribute expression within a standard or custom action: <foo:bar attr="%=expr%" />
See "JSP XML Standard Action and Custom Action Elements".
|
<foo:bar attr="<%=expr%>" />
|
Text element: <jsp:text> ... </jsp:text> This is for template data. See "JSP XML Text Elements and Other Elements".
|
Template data |
Other XML elements. These can appear anywhere a |
Template data |
The <jsp:root>
element has three primary functions:
It establishes the document as a JSP XML document, instructing the JSP container to treat it accordingly.
It identifies, through xmlns
attribute settings, required XML namespaces for the JSP XML core syntax and any custom tag libraries.
It specifies a JSP version number (required).
There is always one xmlns
attribute to identify the namespace for the core JSP XML syntax:
xmlns:jsp="http://java.sun.com/JSP/Page"
This xmlns:jsp
setting enables the use of standard elements defined in the JSP specification.
You must also include an xmlns
attribute for each custom tag library you use, specifying the tag library prefix and namespace—that is, pointing to the corresponding TLD file for use in validating your tag usage. These xmlns
settings are equivalent to taglib
directives in a traditional JSP page.
You can use either a URN or a URI to point to the TLD file. The Sun Microsystems JavaServer Pages Specification, Version 1.2 provides the following example, for tag library prefixes eg
and temp
:
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:eg="http://java.apache.org/tomcat/examples-taglib"
xmlns:temp="urn:jsptld:/WEB-INF/tlds/my.tld"
version="1.2"
>
...body of document...
</jsp:root>
A URN indicates an application-relative path and must be of the form "urn:jsptld:
path
", where the path is specified in the same way as the uri
attribute in a taglib
directive. See "Overview: Specifying a Tag Library with the taglib Directive".
A URI can be a complete URL or it can be according to mapping in the <taglib>
element of the web.xml
file or the <uri>
element of a TLD file. See "Use of web.xml for Tag Libraries" and "Packaging and Accessing Multiple Tag Libraries in a JAR File".
Also note the version
attribute in the example. This is a required attribute, specifying the JSP version that the page uses (1.2 or higher).
There are JSP XML elements that are equivalent to page
and include
directives. (The taglib
directives are replaced by xmlns
settings in the <jsp:root>
element, as the preceding section, "JSP XML root Element and JSP XML Namespaces", describes.)
Transforming a page
or include
directive to the equivalent JSP XML element is straightforward, as shown in the following examples.
Consider the following page
directive:
<%@ page import="java.io.*" %>
This is equivalent to the following JSP XML element:
<jsp:directive.page import="java.io.*" />
Consider the following include
directive:
<%@ include file="/jsp/userinfopage.jsp" %>
This is equivalent to the following JSP XML element:
<jsp:directive.include file="/jsp/userinfopage.jsp" />
Note: The XML view of a page does not containinclude elements, because statically included segments are copied directly into the view.
|
There are JSP XML elements that are equivalent to JSP declarations, expressions, and scriptlets.
Transforming any of these constructs to the equivalent JSP XML element is straightforward, as shown in the following examples.
Consider the following JSP declaration:
<%! public String func(int myint) { if (myint<10) return("..."); } %>
This is equivalent to the following JSP XML element:
<jsp:declaration> <![CDATA[ public String func(int myint) { if (myint<10) return("..."); } ]]> </jsp:declaration>
The XML CDATA
(character data) designation is used because the declaration includes a "<
" character, which has special meaning to an XML parser. (If you use an XML editor to create your JSP XML pages, this would presumably be handled automatically.) Alternatively, you could write the following, using the "<
" escape character instead of "<
":
<jsp:declaration> public String func(int myint) { if (myint < 10) return("..."); } </jsp:declaration>
Traditional syntax for JSP standard actions (such as jsp:include
, jsp:forward
, and jsp:useBean
) and custom actions is already XML-compatible. In using standard actions or custom actions in JSP XML syntax, however, be aware of the following issues.
A standard action or custom action element with an attribute that can accept a request-time expression value can take that value through the following syntax:
"%=expression%"
Note that there are no angle brackets, "<
" and ">
", around this syntax and that white space around expression
is not necessary. Evaluation of expression
, after any applicable quoting as in any XML document, is the same as for any JSP request-time expression.
Any quoting must be according to the XML specification.
You can introduce template data through <jsp:text>
elements or through chosen XML elements that are neither standard nor custom. See "JSP XML Text Elements and Other Elements", which follows.
A <jsp:text>
element denotes template data in a JSP XML document:
<jsp:text>
...template data...
</jsp:text>
When a JSP container encounters a <jsp:text>
element, it passes the contents to the current JSP out
object (similar to the processing of an XSLT <xsl:text>
element).
The JSP specification also allows, wherever a <jsp:text>
element can appear, the use of arbitrary elements (neither standard action elements nor custom action elements) for template data. These arbitrary elements are processed in the same way as <jsp:text>
elements, with content being sent to the current JSP out
object.
The following example is from the Sun Microsystems JavaServer Pages Specification, Version 1.2.
Consider the following JSP XML document source text:
<hello><jsp:scriptlet>int i=3;</jsp:scriptlet> <hi> <jsp:text> hi you all </jsp:text><jsp:expression>i</jsp:expression> </hi> </hello>
This source text results in the following output from the JSP container:
<hello> <hi> hi you all 3 </hi></hello>
Note how the white space is treated.
This section shows two versions of a JSP page, one in traditional syntax and one in XML syntax.
For information about deploying and running this example, refer to the following Web site:
http://www.oracle.com/technology/tech/java/oc4j/htdocs/how-to-jsp-xmlview.html
(You must register for an Oracle Technology Network membership, but it is free of charge.)
Here is the sample page in traditional syntax:
<%@ page session = "false" %> <jsp:useBean id = "picker" class = "oracle.jsp.sample.lottery.LottoPicker" scope = "page" /> <% picker.setIdentity(request.getRemoteAddr() ); %> <HTML> <HEAD> <TITLE>Lotto Number Generator</TITLE> </HEAD> <BODY BACKGROUND="images/cream.jpg" BGCOLOR="#FFFFFF"> <H1 ALIGN="CENTER"></H1> <BR> <H1 ALIGN="CENTER">Your Specially Picked</H1> <P ALIGN="CENTER"><IMG SRC="images/winningnumbers.gif" WIDTH="450" HEIGHT="69" ALIGN="BOTTOM" BORDER="0"></P> <P> <P ALIGN="CENTER"> <TABLE ALIGN="CENTER" BORDER="0" CELLPADDING="0" CELLSPACING="0"> <TR> <% int [] picks = picker.getPicks(); for (int i = 0; i < picks.length; i++) { %> <TD> <IMG SRC="images/ball<%= picks[i] %>.gif" WIDTH="68" HEIGHT="76" ALIGN="BOTTOM" BORDER="0"> </TD> <% } %> </TR> </TABLE> </P> <P ALIGN="CENTER"><BR> <BR> <IMG SRC="images/playrespon.gif" WIDTH="120" HEIGHT="73" ALIGN="BOTTOM" BORDER="0"> </BODY> </HTML>
Here is the same page in XML syntax:
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="1.2"> <jsp:directive.page session = "false" contentType="text/html"/> <jsp:useBean id = "picker" class = "oracle.jsp.sample.lottery.LottoPicker" scope = "page" /> <jsp:scriptlet>picker.setIdentity(request.getRemoteAddr() ); </jsp:scriptlet> <jsp:text><![CDATA[<HTML> <HEAD> <TITLE>Lotto Number Generator</TITLE> </HEAD> <BODY BACKGROUND='../basic/lottery/images/cream.jpg' BGCOLOR='#FFFFFF'> <H1 ALIGN='CENTER'></H1> <BR> <H1 ALIGN='CENTER'>Your Specially Picked</H1> <P ALIGN='CENTER'><IMG SRC='../basic/lottery/images/winningnumbers.gif' WIDTH='450' HEIGHT='69' ALIGN='BOTTOM' BORDER='0'></P> <P ALIGN='CENTER'> <TABLE ALIGN='CENTER' BORDER='0' CELLPADDING='0' CELLSPACING='0'> <TR>]]></jsp:text> <jsp:scriptlet> int [] picks = picker.getPicks(); for (int i = 0; i < picks.length; i++) { </jsp:scriptlet> <jsp:text><![CDATA[<TD> <IMG SRC='../basic/lottery/images/ball]]> </jsp:text> <jsp:expression>picks[i]</jsp:expression> <jsp:text> <![CDATA[.gif' WIDTH='68' HEIGHT='76' ALIGN='BOTTOM' BORDER='0'> </TD>]]></jsp:text> <jsp:scriptlet> } </jsp:scriptlet> <jsp:text><![CDATA[</TR> </TABLE> </P> <P ALIGN='CENTER'><BR> <BR> <IMG SRC='../basic/lottery/images/playrespon.gif' WIDTH='120' HEIGHT='73' ALIGN='BOTTOM' BORDER='0'> </BODY> </HTML>]]></jsp:text> </jsp:root>
When a container that complies with JSP 1.2 translates a JSP page, it creates an XML version, known as the XML view, of the parsing result. The JSP specification defines the XML view as being a mapping of a JSP page—either a traditional page or a JSP XML document—into an XML document that describes it. The XML view can be used by tag-library-validator classes in validating the page. (See "Validation and Tag-Library-Validator Classes".) The XML view of a page looks mostly like the page as you would write it yourself if you were using JSP XML syntax, with a couple of key differences, as described shortly.
These topics are covered in the following sections:
Refer to the Sun Microsystems JavaServer Pages Specification for further details.
When translating a JSP page, the JSP container executes the following transformations in creating the XML view, both for traditional JSP pages and for JSP XML documents:
The container expands the XML view to include files brought in through include
directives.
A JSP container that supports the optional jsp:id
attribute, for improved error reporting, inserts that attribute into each XML element in the page. See "The jsp:id Attribute for Error Reporting During Validation".
For a JSP XML document, these points constitute the key differences between the XML view and the original page.
The JSP container executes the following additional transformations for traditional JSP pages:
It adds the <jsp:root>
element, with the standard xmlns
attribute setting for JSP XML syntax and the version
attribute for the JSP version. See "JSP XML root Element and JSP XML Namespaces".
It converts each taglib
directive into an additional xmlns
attribute in the <jsp:root>
element. See "JSP XML root Element and JSP XML Namespaces".
It converts each page
directive into the equivalent element in JSP XML syntax. See "JSP XML Directive Elements".
It converts each declaration, expression, and scriptlet into the equivalent element in JSP XML syntax. See "JSP XML Declaration, Expression, and Scriptlet Elements".
It converts request-time expressions into XML syntax. See "JSP XML Standard Action and Custom Action Elements".
It creates <jsp:text>
elements for template data. See "JSP XML Text Elements and Other Elements".
It converts JSP quotations into XML quotations.
It ignores JSP comments: <%--
comment
--%>
. They do not appear in the XML view.
Notes:
|
The JSP specification describes an optional jsp:id
attribute that the JSP container can add to each XML element in the XML view. A container does not have to support this feature to comply with JSP 1.2, but the OC4J JSP container does support it.
The jsp:id
attributes, if present, are used by tag-library-validator classes during page validation. The purpose of these attributes is to provide improved error reporting, possibly helping developers pinpoint where errors occur (depending on how the JSP container implements jsp:id
support).
The jsp:id
attribute values must be generated by the container in a way that ensures that each value, or ID, is unique across all elements in the XML view.
A tag-library-validator object can use these IDs in the ValidationMessage
objects that it returns. (See "Validation and Tag-Library-Validator Classes" for background information about TLV classes.)
In the OC4J JSP implementation, when a ValidationMessage
object with IDs is returned, each ID is transformed to reflect the tag name and source location of the matching element.
This example shows traditional page source, followed by the XML view of the page as generated by the OC4J JSP translator. The code displays the Oracle JSP version number and configuration parameter values.
Here is the traditional JSP page:
<HTML> <HEAD> <TITLE>JSP Information </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> JSP Version:<BR> <%= application.getAttribute("oracle.jsp.versionNumber") %> <BR> JSP Init Parameters:<BR> <% for (Enumeration paraNames = config.getInitParameterNames(); paraNames.hasMoreElements() ;) { String paraName = (String)paraNames.nextElement(); %> <%=paraName%> = <%=config.getInitParameter(paraName)%> <BR> <% } %> </BODY> </HTML>
Here is the corresponding XML view:
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" jsp:id="0" version="1.2"> <jsp:text jsp:id="1"><![CDATA[ <HTML> <HEAD> <TITLE>JSP Information </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> JSP Version:<BR>]]></jsp:text> <jsp:expression jsp:id="2"> <![CDATA[ application.getAttribute("oracle.jsp.versionNumber") ]]> </jsp:expression> <jsp:text jsp:id="3"><![CDATA[ <BR> JSP Init Parameters:<BR> ]]> </jsp:text> <jsp:scriptlet jsp:id="4"><![CDATA[ for (Enumeration paraNames = config.getInitParameterNames(); paraNames.hasMoreElements() ;) { String paraName = (String)paraNames.nextElement(); ]]></jsp:scriptlet> <jsp:text jsp:id="5"><![CDATA[ ]]></jsp:text> <jsp:expression jsp:id="6"><![CDATA[paraName]]></jsp:expression> <jsp:text jsp:id="7"><![CDATA[ = ]]></jsp:text> <jsp:expression jsp:id="8"> <![CDATA[config.getInitParameter(paraName)]]> </jsp:expression> <jsp:text jsp:id="9"><![CDATA[ <BR> ]]></jsp:text> <jsp:scriptlet jsp:id="10"><![CDATA[ } ]]></jsp:scriptlet> <jsp:text jsp:id="11"><![CDATA[ </BODY> </HTML> ]]></jsp:text> </jsp:root>