Skip Headers

Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide 10g Release 2 (10.1.2) B14014-02 |
| Library | Product | Contents | Index

Previous | 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:

- 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 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 X ML 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:

- 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, through `xmlns` 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.

### 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 X ML 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 Dir ective 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 Decla ration, 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 Sta ndard 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 X ML 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 Co mparison: 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:

- 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 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 js p: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: Tran sformation 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>