5
JSP XML Support

Because of additional support for XML 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 topics:

• JSP XML Documents and JSP XML View: Overview and Comparison

• Details of JSP XML Documents

• Details of the JSP XML View

For information about additional JSP support for XML and XSL, furnished in OC4J through custom tags, refer to the Oracle9iAS 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. Sun Microsystems first addressed this issue in the JavaServer Pages Specification, Version 1.1 by defining equivalent JSP syntax that is XML-compatible. In JSP 1.1, however, support for this syntax by a JSP container is optional.

The JavaServer Pages Specification, Version 1.2 offers more complete support for XML-compatible JSP syntax, adding features and requiring support by compliant JSP containers.

The term JSP XML document (called JSP document in the JSP 1.2 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 1.2 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, Version 1.2.

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)

• 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

This section 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:root
     xmlns:jsp=...
     xmlns:xxx =...
     ...
     version=...
/>

<jsp:directive.page ... />

<%@ page ... %>

<jsp:directive.include ... />

<%@ include ... %>

<jsp:declaration>
   declaration
</jsp:declaration>

<%! declaration %>

<jsp:expression>
   expression
</jsp:expression>

<%= expression %>

<jsp:scriptlet>
   code fragment
</jsp:scriptlet>

<% code fragment %>

<foo:bar attr="%=expr%" />

<foo:bar attr="<%=expr%>" />

<jsp:text>
...
</jsp:text>

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 1.2 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 JSP 1.2 specification 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

The following page directive:

<%@ page language="sqlj"
    import="sqlj.runtime.ref.DefaultContext,oracle.sqlj.runtime.Oracle" %>

is equivalent to the following JSP XML element:

<jsp:directive.page language="sqlj"
    import="sqlj.runtime.ref.DefaultContext,oracle.sqlj.runtime.Oracle" />

Example: include Directive

The following include directive:

<%@ include file="/jsp/userinfopage.jsp" %>

is equivalent to the following JSP XML element:

<jsp:directive.include file="/jsp/userinfopage.jsp" />

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

The following JSP declaration:

<%! public String func(int myint) { if (myint<10) return("..."); } %>

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 &lt; 10) return("..."); }
</jsp:declaration>

Example: JSP Expression

The following JSP expression:

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

is equivalent to the following JSP XML element:

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

Example: JSP Scriptlet

The following JSP scriptlet:

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

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 1.2 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://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.)

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

This section covers the following topics:

• Transformation from a JSP Page to the XML View

• The jsp:id Attribute for Error Reporting During Validation

• Example: Transformation from Traditional JSP Page to XML View

Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.2 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:

• 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 XML view has no DOCTYPE statement. No "other XML elements", as described in "JSP XML Text Elements and Other Elements", appear in the XML view. Only <jsp:text> elements are used for template data.

The jsp:id Attribute for Error Reporting During Validation

The JSP 1.2 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 from one of the OC4J JSP demo applications, followed by the XML view of the page as generated by the OC4J JSP translator. (The demo displays the Oracle JSP version number and configuration parameter values.)

Traditional JSP Page

Here is the traditional JSP page:

<HTML> 
    <HEAD> 
        <TITLE>OJSP Information </TITLE> 
    </HEAD>
    <BODY BGCOLOR="#FFFFFF"> 
         OJSP Version:<BR>
            <%= application.getAttribute("oracle.jsp.versionNumber") %>
         <BR>
         OJSP 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>OJSP Information </TITLE> 
       </HEAD>
       <BODY BGCOLOR="#FFFFFF"> 
            OJSP Version:<BR>]]></jsp:text>
   <jsp:expression jsp:id="2">
      <![CDATA[ application.getAttribute("oracle.jsp.versionNumber") ]]>
   </jsp:expression>
   <jsp:text jsp:id="3"><![CDATA[
            <BR>
            OJSP 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>