Skip Headers
Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 2 (10.1.2)
B14014-02
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

5 JSP XML Support

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/

JSP XML Documents and JSP XML View: Overview and Comparison

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.


Note:

Template data consists of any text that is not interpreted by the JSP translator.

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.

Details of JSP XML Documents

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 of include directives. For example, a traditional JSP page can include a JSP XML document.


Note:

A JSP XML document does not use a DOCTYPE statement.

JSP XML syntax includes the following:

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.

Summary Table of JSP XML Syntax

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 xmlns settings for tag libraries are equivalent to JSP taglib directives.

JSP page directive element:

<jsp:directive.page ... />

See "JSP XML Directive Elements".

<%@ page ... %>

JSP include directive element:

<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 jsp:include or jsp:forward

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 <jsp:text> element can appear.

See "JSP XML Text Elements and Other Elements".

Template data


JSP XML root Element and JSP XML Namespaces

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).

JSP XML Directive Elements

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.

Example: page Directive

Consider the following page directive:

<%@ page import="java.io.*" %>

This is equivalent to the following JSP XML element:

<jsp:directive.page import="java.io.*" />

Example: include Directive

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 contain include elements, because statically included segments are copied directly into the view.

JSP XML Declaration, Expression, and Scriptlet Elements

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.

Example: JSP Declaration

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 "&lt;" escape character instead of "<":

<jsp:declaration> 
   public String func(int myint) { if (myint &lt; 10) return("..."); }
</jsp:declaration>

Example: JSP Expression

Consider the following JSP expression:

<%= (user==null) ? "" : user %>

This is equivalent to the following JSP XML element:

<jsp:expression> (user==null) ? "" : user </jsp:expression>

Example: JSP Scriptlet

Consider the following JSP scriptlet:

<% if (pageBean.getNewName().equals("")) { %>
   ...

This is equivalent to the following JSP XML element:

<jsp:scriptlet> if (pageBean.getNewName().equals("")) { </jsp:scriptlet>
   ...

JSP XML Standard Action and Custom Action Elements

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.

JSP XML Text Elements and Other Elements

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.

Example: Other JSP XML Elements

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.

Sample Comparison: Traditional JSP Page Versus JSP XML Document

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.)

Sample Traditional JSP Page

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> 

Sample JSP XML Document

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 &lt; 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>

Details of the JSP XML View

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.

Transformation from a JSP Page to the XML View

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:

The jsp:id Attribute for Error Reporting During Validation

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.

Example: Transformation from Traditional JSP Page to XML View

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.

Traditional JSP Page

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> 

XML View of JSP Page

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>