|
Oracle® Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 3 (10.1.3) Part No. B14430-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 3 (10.1.3) Part No. B14430-01 |
|
|
Previous |
Next |
JavaServer Pages technology is increasingly seen as an effective model for producing XML documents. New enhancements released with JSP 2.0, including an improved XML syntax, make JSP even more complementary to XML technology and more accessible to XML tools.
The OC4J JSP container fully implements JavaServer Pages support for XML as described in the JavaServer Pages 2.0 specification. This includes support for:
XML-style equivalents to JSP syntactical elements
The concept of the "XML view" of a JSP page
Allowing any XML element to be used as the document root (the <jsp:root> element is no longer required)
Support for the new <jsp:element> and <jsp:attribute> standard tag elements
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 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/
The term JSP document refers to a JSP page written in XML syntax. A JSP 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 standard action tags and custom tag libraries used. A traditional JSP page, by contrast, is typically not an XML document.
What advantages do JSP documents offer?
You can create dynamic documents that can be passed directly to the OC4J JSP container in a pure XML syntax compatible with existing XML tools
You can output content written in XML-based languages like XHTML or SVG in JSP pages
You can generate a JSP document from a textual representation by applying an XML transformation, like XSLT
You can use a JSP document for data-interchange between different Web applications
Many JSP syntax elements, such as standard action tags and custom tags, are already written in XML syntax. For JSP elements that are not compliant, equivalent XML elements are provided. See "Working with JSP Documents" for details.
Any of the following identify a file as a JSP document to the OC4J JSP container:
An <is-xml> element within the Web module's web.xml deployment descriptor
The <is-xml> is a subelement of the <jsp-property-group> element used to identify files as JSP documents. For example, this web.xml snippet identifies files with an.svg extension - specified in the <url-pattern> subelelement - as JSP documents:
<web-app ...> <jsp-config> <jsp-property-group> <description>Define files with SVG extension as JSP documents</description> <url-pattern>*.svg</url-pattern> <is-xml>true</is-xml> </jsp-property-group> </jsp-config> </web-app>
Note that the <is-xml> definition overrides any of the other indicators listed below.
A.jspx file extension
Support for this extension is new in JSP 2.0, and explicity defines the file as a JSP document. Note that tag files can also be written in XML syntax, and are identified to the container by the .tagx extension. See "What Are Tag Files?" for more on tag files.
A <jsp:root> element as the top element within the document body
This element includes a namespace specification for the JSP XML core syntax and namespace specifications for any custom tag libraries that are used. Note that this element was mandatory in JSP 1.2, but is optional in JSP 2.0, which allows you to specify your own root element.
The semantic model for JSP documents is the same as for traditional pages. A JSP 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 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.
The XML view is an XML document derived from a JSP page that is used to validate the page. The OC4J JSP container generates the XML view during JSP translation. The JSP 2.0 specification defines the view as "the mapping between a JSP page, written in either XML syntax or traditional syntax, and an XML document describing it".
Beginning with the JSP1.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 the case of a JSP 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 difference is that ID attributes for improved error reporting are added to all XML elements.
In the case of a traditional JSP page, the Web container performs a series of transformations to create the XML view from the page. See "Understanding the JSP XML View" for details.
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 Web container, for use in page validation.
This section describes the syntax of JSP 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 document.
|
JSP XML syntax includes the following elements. Note that the syntax includes an XML equivalent or replacement element for every JSP element except for <%-- comment --%>.
An optional <jsp:root> element, which includes a namespace specification for the JSP XML core syntax and namespace specifications for any custom tag libraries that are used. Note that this element is optional in JSP 2.0, which allows you to specify your own root element.
JSP page and include directives
JSP declaration elements
JSP expression elements
JSP scriptlet elements
JSP standard action elements
JSP custom action elements, including JavaServer Pages Standard Tag Library (JSTL) tag elements
New <jsp:attribute> and <jsp:element> elements, which may include expression language (EL) expressions in element bodies and attribute values
A text element, <jsp:text>, for static template data
Other XML elements, if desired, pertaining to template data
As noted previously, most of the standard JSP syntax is already XML-compliant, and can be used in a JSP document in XML element format. For the JSP elements that are not compliant, a set of equivalent XML elements are provided, as summarized in Table 8-1below.
Table 8-1 Standard JSP Syntax Versus XML Syntax
| Syntax Element | JSP Syntax | XML Syntax |
|---|---|---|
|
Comments |
|
|
|
Declarations |
|
|
|
Include Directives |
|
|
|
Page Directives |
|
|
|
Tag Library Directives |
|
|
|
Expressions |
|
|
|
Scriplets |
|
|
A JSP document must have a root element. Prior to the release of JSP 2.0, the <jsp:root> element had to be used as the root. While this element can still be used, it is no longer required, meaning that you can specify your own root element. This flexibility allows you to take any XML document and use it as a JSP document.
The root element in the example shown below document is html. You can also declare tag libraries to be used in the document within the root, as discussed in the next section.
Note that neither a JSP document nor its request output is required to include an XML declaration. In fact, if the JSP document is not producing XML output, the document should not include an XML declaration.
In JSP documents, XML namespaces are used to include both standard actions and custom tags in the document. An XML namespace is a collection of XML element types and attribute names.
Unlike in JSP pages, standard action tags such as <jsp:useBean> are not implicitly available; instead, you must include these elements with the following namespace, which identifies the namespace of the core JSP XML syntax:
xmlns:jsp="http://java.sun.com/JSP/Page"
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 or tag file library 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 tag library. The following example declares namespaces for the JSTL prefix c and the custom tag prefix my in the html root element:
<html xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:c="http://java.sun.com/jsp/jstl/core"
xmlns:my="urn:jsptagdir:/WEB-INF/tlds/mylib"
>
...body of document...
</html>
A URN indicates an application-relative path and must be of one of the following forms:
"urn:jsptld:path", where the path points to a single tag library, in the same way as the uri attribute in a taglib directive.
"urn:jsptagdir:path", where the path must start with /WEB-INF/tags/ and points to tag extensions implemented as tag files installed in the WEB-INF/tags/ directory or one of its subdirectories
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 TLDs in JAR files in WEB-INF/lib or TLDs under WEB-INF. See "Key web.xml Deployment Descriptor Entries" and "Packaging Multiple Tag Libraries and TLD Files in a JAR File".
Declaring tag libraries as xmlns attributes of the root element, as shown in the above example, gives all elements within the document access to those libraries. However, this is not required; tag libraries can also be referenced at the point of usage within the document, allowing you to scope a tag library for use with a particular element.
For example, the following example restricts usage of the tag library referenced by the c prefix to the <c:forEach element:
<c:forEach xmlns:c="http://java.sun.com/jsp/jstl/core"
var="counter" begin="0" end=${4}>
...
</c:forEach>
There are JSP XML elements that are equivalent to page and include directives. 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 language="java"
import="com.tks.ourpackage" %>
This is equivalent to the following JSP XML element:
<jsp:directive.page language="java"
import="com.tks.ourpackage" />
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<0) return("..."); } %>
This is equivalent to the following JSP XML element:
<jsp:declaration>
<![CDATA[ public String func(int myint) { if (myint<0) 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 < 0) 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 "Including Template and Dynamic Template Content", which follows.
You can include static template text in a JSP document using either uninterpreted XML tags, which do not preserve whitespace, or with the <jsp:text> element. denotes template data in a JSP document:
When the OC4J 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 the use of arbitrary elements (neither standard action elements nor custom action elements) for template data wherever a <jsp:text> element can appear. These arbitrary elements are processed in the same way as <jsp:text> elements, with content being sent to the current JSP out object.
Consider the following JSP document source text:
<hello><jsp:declaration>String n="Alfred";</jsp:declaration>
<morning>
<jsp:text> Good Morning
</jsp:text>${n}
</morning>
</hello>
This source text results in the following output from the OC4J JSP container. Note how the whitespace is preserved:
<hello> <morning> Good Morning Alfred </morning></hello>
You can also use <jsp:text> to output template data that is not well-formed XML. For example, if the ${list} EL expression below was not wrapped in a <jsp:text> tag, it would be illegal in a JSP document:
<c:forEach var="list" begin="1" end="${4}">
<jsp:text>${list}</jsp:text>
</c:forEach>
Dynamic template content can also be generated by a JSP document using EL expression, Java scripting elements (declarations, scriptlets, or expressions), standard action tags and custom tags - just as with a standard JSP page.
You can generate tags dynamically rather than hard coding them in your JSP document using EL expressions with the <jsp:element> standard action. This action takes one String attribute, which is used as the name of the generated element.
The tag element can optionally include a body, which can consist of:
A body that does not define attributes
One or more <jsp:attribute> elements, which are set as attributes of the new element
If <jsp:attribute> is used, a tag body can be included within a a <jsp:body> element
For example, the following code in a JSP document:
<jsp:element name="${searchRequest.type}"> <jsp:attribute name="language">${searchRequest.language}</jsp:attribute>
<jsp:body>${searchRequest.content}</jsp:body>
</jsp:element>
Could generate the following:
<standardSearch language="English">What is an attribute?</standardSearch>
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://otn.oracle.com/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:
<%@ taglib prefix="tags" tagdir="/WEB-INF/tags" %>
<html>
<head>
<title>An eStore for all occasions</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body>
<table align="center" width="100%" height="100%" border="4" bgcolor="#FFFFFF"
bordercolor="#FF0000">
<tr>
<td width="64%" valign="middle" align="center" bgcolor="#FFCCCC">
<div align="center"><img src="gifs/christmas/Electronic.gif"></div>
<tags:ProductDetails occasion="Christmas" category="Cards" thBgColor="#FF3366"
thFontColor="#FFFFFF">
<jsp:attribute name="normalPrice">
<td width="50%" align="center"><font color="#CC3300"><b>${name}</b></font></td>
<td width="30%" align="center"><font color="#CC3300"><b>${price}</b></font></td>
<td width="20%" align="center"><img src=${image} width="100" height="40"></td>
</tr>
</jsp:attribute>
<jsp:attribute name="onSale">
<tr>
<td width="50%" align="center"><font color="#CC3300"><b>${name}<img
src="gifs/main/discount.gif"></b></font></td>
<td width="30%" align="center"><font color="red"><b>
<strike>Was: ${price}</strike></b></font><br><font color="#996600"><b>
<font color="#CC3300">Now: ${saleprice}</font></b></font>
</td>
<td width="20%" align="center"><img src=${image} width="100"
height="40"></td>
</tr>
</jsp:attribute>
</tags:ProductDetails>
<br><br>
</td>
</tr>
</table>
</body>
</html>
Here is the same page in XML syntax. Note how HTML to be passed to the browser is enclosed in <jsp:text> tags.
<html xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:tags="/WEB-INF/tags">
<jsp:directive.page contentType="text/html" />
<jsp:text>
<![CDATA[
<head><title>An eStore for all occasions</title></head><body>
<table align="center" width="100%" height="100%" border="4" bgcolor="#FFFFFF" bordercolor="#FF0000">
<tr>
<td width="64%" valign="middle" align="center" bgcolor="#FFCCCC">
<div align="center"><img src="gifs/christmas/Electronic.gif"></div>
]]>
</jsp:text>
<tags:ProductDetails occasion="Christmas" category="Cards" thBgColor="#FF3366"
thFontColor="#FFFFFF">
<jsp:attribute name="normalPrice">
<jsp:text>
<![CDATA[<tr>
<td width="50%" align="center"><font color="#CC3300"><b>${name}</b></font></td>
<td width="30%" align="center"><font color="#CC3300"><b>${price}</b></font></td>
<td width="20%" align="center"><img src=${image} width="100" height="40"></td>
</tr>]]>
</jsp:text>
</jsp:attribute>
<jsp:attribute name="onSale">
<jsp:text>
<![CDATA[<tr>
<td width="50%" align="center"><font color="#CC3300"><b>${name}<img src="gifs/main/discount.gif"></b></font></td>
<td width="30%" align="center"><font color="red"><b>
<strike>Was: ${price}</strike></b></font><br><font color="#996600"><b>
<font color="#CC3300">Now: ${saleprice}</font></b></font>
</td>
<td width="20%" align="center"><img src=${image} width="100" height="40"></td>
</tr>]]>
</jsp:text>
</jsp:attribute>
</tags:ProductDetails>
<jsp:text>
<![CDATA[<br><br>
</td>
</tr>
</table>
</body>]]>
</jsp:text>
</html>
When OC4J 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 document—into an XML document that describes it.
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 Web container executes the following transformations in creating the XML view, both for traditional JSP pages and for JSP documents:
The container expands the XML view to include files brought in through include directives.
A Web 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 document, these points constitute the key differences between the XML view and the original page.
The Web 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 "Declaring Tag Libraries with XML Namespaces".
It converts each taglib directive into an additional xmlns attribute in the <jsp:root> element. See "Declaring Tag Libraries with XML Namespaces".
It converts each page directive into the equivalent element in JSP XML syntax. See "Using JSP XML Directive Elements".
It converts each declaration, expression, and scriptlet into the equivalent element in JSP XML syntax. See "Using JSP XML Declaration, Expression, and Scriptlet Elements".
It converts request-time expressions into XML syntax. See "Using JSP XML Standard Action and Custom Action Elements".
It creates <jsp:text> elements for template data. See "Including Template and Dynamic Template Content".
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 a jsp:id attribute that the Web container can add to each XML element in the XML view. The jsp:id attributes 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 Web 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. 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:
<%@ page import="java.util.*" %>
<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=""><![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="0"><![CDATA[
}
]]></jsp:scriptlet>
<jsp:text jsp:id=""><![CDATA[
</BODY>
</HTML>
]]></jsp:text>
</jsp:root>
