Skip Headers

Oracle® Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference 10g Release 2 (10.1.2) B14016-02 |
| Library | Product | Contents | Index

Previous | Next |

# 5 XML and XSL Tag Support

This chapter describes tags provided with OC4J that you can use for XML data and XSL transformation, and summarizes additional XML functionality in other OC4J tags. These tags are implemented according to the JSP specification.

The chapter consists of the following sections:

- Overview of Oracle Tags for XML Support

- XML Utility Tags

Note: See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for additional information about XML-related functionality for JSP pages.

## Overview of Oracle Tags for XML Support

The following sections provide an overview of tags supplied with OC4J that have XML functionality. This includes tags that can take XML DOM objects as input, generate XML DOM objects as output, transform XML documents according to a specified stylesheet, and parse data from an input stream to an XML DOM object.

- XML Producers and XML Consumers

- Summary of OC4J Tags with XML Functionality

Note: The custom XML tag library provided with OC4J pre-dates the JavaServer Pages Standard Tag Library (JSTL) and has areas of duplicate functionality. For standards compliance, it is now generally advisable to use JSTL instead. See "Support for the JavaServer Pages Standard Tag Library". Oracle is not desupporting the existing library, however. For features in the custom library that are not yet available in JSTL, where there seems to be general usefulness, Oracle will try to have the features adopted into the JSTL standard as appropriate.

### XML Producers and XML Consumers

An XML-related operation can be classified as either of the following, or as both:

- XML producer, which outputs an XML object

- XML consumer, which takes an XML object as input

Similarly, an XML-related tag can be classified as an XML producer, an XML consumer, or both. XML producers can pass XML objects to XML consumers either explicitly or implicitly; the latter is also known as anonymous passing.

For explicit passing between XML-related tags, there is a `toXMLObjName` attribute in the producer tag and a `fromXMLObjName` attribute in the consumer tag. Behind the scenes, the passing is done through the `getAttribute()` and `setAttribute()` methods of the standard JSP `pageContext` object. The following example uses explicit passing:

    <sql:dbQuery output="XML" toXMLObjName="foo" ... >
       ...SQL query...
    </sql:dbQuery>
    ...
    <ojsp:cacheXMLObj fromXMLObjName="foo" ... />

For implicit passing between XML-related tags, do not use the `toXMLObjName` and `fromXMLObjName` attributes. The passing is accomplished through direct interaction between the tag handlers, typically in a situation with a nested tag. The following example uses implicit passing:

    <ojsp:cacheXMLObj ... >
       <sql:dbQuery output="XML" >
          ...SQL query...
       </sql:dbQuery>
    </ojsp:cacheXMLObj>

Here, the XML produced in the `dbQuery` tag is passed to the `cacheXMLObj` tag directly, without being stored to the `pageContext` object.

For a tag to be able to function as a consumer with implicit passing, the tag handler implements the OC4J `ImplicitXMLObjConsumer` interface:

    interface ImplicitXMLObjConsumer
    {
       void setImplicitFromXMLObj();
    }

### Summary of OC4J Tags with XML Functionality

For the tag libraries supplied with OC4J, Table 5-1 summarizes the tags that can function as XML producers or consumers.

Table 5-1 OC4J Tags with XML Functionality

Tag | Library | Producer / Consumer | Related Attributes | Tag Information
--- | --- | --- | --- | ---
transform / styleSheet | XML | Both | fromXMLObjName toXMLObjName | "XML transform and styleSheet Tags for XML/XSL Data Transformation"
parsexml | XML | Producer | toXMLObjName | "XML parsexml Tag to Convert from Input Stream"
cacheXMLObj | Web Object Cache | Both | fromXMLObjName toXMLObjName | "Web Object Cache cacheXMLObj Tag"
dbQuery | SQL | Producer | toXMLObjName | "SQL dbQuery Tag"
invoke | Web Services | Producer | toXMLObjName | "Web Services invoke Tag"

Notes: The XML `transform` and `styleSheet` tags are equivalent and produce identical results. For convenience, the `cacheXMLObj` tag is defined in the XML tag library descriptor file (`xml.tld`) as well as the Web Object Cache tag library descriptor file (`jwcache.tld`).

## XML Utility Tags

The following sections describe XML utility tags supplied with OC4J:

- XML Utility Tag Descriptions

- XML Utility Tag Examples

Note the following requirements for the XML utility tag library:

- The XML tag library requires `ojsputil.jar`, `xmlparserv2.jar`, and `xsu12.jar` to be installed and in your classpath. These files are supplied with OC4J. The `ojsputil.jar` file is located in the "well-known" tag library directory.

- The ta g library descriptor, `xml.tld`, must be available to the application, and any JSP page using the library must have an appropriate `taglib` directive. In an Oracle Application Server installation, the TLD is in `ojsputil.jar`. The `uri` value for `xml.tld` is the following:

      http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xml.tld

You can refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about `taglib` directives, the well-known tag library directory, TLD files, and the meaning of `uri` values.

Notes: The prefix "xml:" is used in the tag syntax here. This is by convention but is not required. You can specify any desired prefix in your `taglib` directive. See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

### XML Utility Tag Descriptions

The following sections describe XML utility tags:

- XML transform and styleSheet Tags for XML/XSL Data Transformation

- XML parsexml Tag to Convert from Input Stream

  Important: Tag attributes are request-time attributes, meaning they can take JSP expressions as input, unless otherwise noted.

#### XML transfo rm and styleSheet Tags for XML/XSL Data Transformation

Many uses of XML and XSL for dynamic JSP pages require an XSL transformation to occur in the server before results are returned to the client. Oracle provides two synonymous tags in the XML library to simplify this process. You can output the result directly to the HTTP client or, alternatively, you can output to a specified XML DOM object. Use either the `transform` tag or the `styleSheet` tag, as described and shown in this section. The two tags have identical effects.

Each tag acts as both an XML producer and an XML consumer. They can take as input either of the following:

- An XML DOM object

- The tag body, containing JSP commands and static text that produce the XML code

The tags can output to either or both of the following, with the specified stylesheet being applied in either case:

- An XML DOM object

- The output writer to the browser, in which case the specified stylesheet is applied

When you use the tag body for input, the tag applies to what is between the start-tag and end-tag. You can have multiple XSL transformation blocks within a page, with each block bounded by its own `transform` or `styleSheet` tag, specifying its own `href` pointer to the appropriate style sheet.

##### Syntax

    <xml:transform href="xslRef"
                 [ fromXMLObjName = "objectname" ]
                 [ toXMLObjName = "objectname" ]
                 [ toWriter = "true" | "false" ] >

       [...body...]

    </xml:transform >

or:

    <xml:styleSheet href="xslRef"
                 [ fromXMLObjName = "objectname" ]
                 [ toXMLObjName = "objectname" ]
                 [ toWriter = "true" | "false" ] >

       [...body...]

    </xml:styleSheet >

##### Attributes

- `href` (required): Specify the XSL stylesheet to use for the XML data transformation. This is required whether you are outputting to an XML object (where you can have transformation without formatting) or to the browser.

  Note the following regarding the `href` attribute:

  - It can refer to either a static XSL stylesheet or a dynamically generated one. For example, it can refer to a JSP page or servlet that generates the stylesheet.

  - It can be a fully qualified URL (`http://``host``:``port``/``path`), an application-relative JSP reference (starting with "`/`"), or a page-relative JSP reference (not starting with "`/`"). Refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about application-relative and page-relative paths.

  - Its value can be a static Java string constant literal, or it can be dynamically specified through a standard JSP request-time expression.

- `fromXMLObjName`: Use this to specify an input XML DOM object if input is from a DOM object instead of from the tag body. If there is both a tag body and a `fromXMLObjName` specification, `fromXMLObjName` takes precedence.

- `toXMLObjName`: Use this to specify the name of an output XML DOM object if output is to a DOM object, instead of or in addition to going to the JSP writer object for output to the HTTP client. This is not required if there is an implicit XML consumer, such as a tag within which the `transform` or `styleSheet` tag is nested.

- `toWriter`: This is "`true`" or "`false`" to indicate whether output goes to the JSP writer object for output to the HTTP client. This can be instead of or in addition to output to a DOM object. The default is "`true`", for backward compatibility. (Prior to Oracle9iAS Release 2, this was the only output choice; there was no `toXMLObjName` attribute.)

#### XML parsex ml Tag to Convert from Input Stream

The XML tag library supplies an XML producer utility tag, `parsexml`, that converts from an input stream to an XML DOM object. This tag can take input from a specified resource or from the tag body.

##### Syntax

    <xml:parsexml
                 [ resource = "xmlresource" ]
                 [ toXMLObjName = "objectname" ]
                 [ validateResource = "dtd_path" ]
                 [ root = "dtd_root_element" ] >

       [...body...]

    </xml:parsexml >

##### Attributes

- `resource`: Use this to specify an XML resource if input is from a resource instead of from the tag body. For example:

      resource="/dir1/hello.xml"

  If there is both a tag body and a specified resource, the resource takes precedence.

- `toXMLObjName`: Specify the name of the XML DOM object where the output will go. This is not required if there is an implicit XML consumer, such as a tag within which the `parsexml` tag is nested.

- `validateResource`: For XML validation, you can specify the path to the appropriate DTD. Alternatively, the DTD can be embedded in the XML resource. This is not a request-time attribute.

- `root`: If validating, specify the root element in the DTD for validation. This is not a request-time attribute. If you specify `validateResource` without specifying `root`, the default root is the top-level of the DTD.

### XML Utility Tag Examples

The following sections provide examples that use XML utility tags:

- Example Using the transform Tag

- Example Using the transform and dbQuery Tags

- Examples Using the transform and parsexml Tags

#### Exa mple Using the transform Tag

This section provides a sample XSL stylesheet and a sample JSP page that uses the `transform` tag to filter its output through the stylesheet. This is a simplistic example, with the XML in the page being static. A more realistic example might use the JSP page to dynamically generate all or part of the XML before performing the transformation.

##### Sample Stylesheet: hello.xsl

    <?xml version="1.0"?>

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

      <xsl:template match="page">
       <html>
        <head>
         <title>
          <xsl:value-of select="title"/>
         </title>
        </head>
        <body bgcolor="#ffffff">
         <xsl:apply-templates/>
        </body>
       </html>
      </xsl:template>

      <xsl:template match="title">
       <h1 align="center">
        <xsl:apply-templates/>
       </h1>
      </xsl:template>

      <xsl:template match="paragraph">
       <p align="center">
        <i>
         <xsl:apply-templates/>
        </i>
       </p>
      </xsl:template>

    </xsl:stylesheet>

##### Sample JSP Page: hello.jsp

    <%@ page session = "false" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xml.tld"
               prefix="xml" %>

    <xml:transform href="style/hello.xsl" >

    <page>
     <title>Hello</title>
     <content>
      <paragraph>This is my first XML/XSL file!</paragraph>
     </content>
    </page>

    </xml:transform>

This example results in the output shown in Figure 5-1.

Figure 5-1 Sample XSL Output

Description of "Figure 5-1 Sample XSL Output"

#### Example Us ing the transform and dbQuery Tags

This example returns a result set from a `dbQuery` tag, using a `transform` tag to filter the query results through the XSL style sheet `rowset.xsl` (code below). It uses a `dbOpen` tag to open a connection, with the connection string being obtained either from the `request` object or through the `useDataSource.jsp` page (code below). Data passing from the `dbOpen` tag to the `transform` tag is done implicitly. For related information, see "SQL dbQuery Tag" and "SQL dbOpen Tag".

##### JSP Page

    <%@ page import="oracle.sql.*, oracle.jdbc.driver.*, oracle.jdbc.*, java.sql.*" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xml.tld"
               prefix="xml" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/sqltaglib.tld"
               prefix="sql" %>

    <%
       String dataSrcStr=request.getParameter("dataSrcStr");
       if (dataSrcStr==null) {
         dataSrcStr=(String)session.getValue("dataSrcStr");
       } else {
         session.putValue("dataSrcStr",dataSrcStr);
       }
       if (dataSrcStr==null) { %>
    <jsp:forward page="../../sql/useDataSource.jsp" />
    <%
       }

    %>
    <h3>Transform DBQuery Tag Example</h3>
    <xml:transform href="style/rowset.xsl" >
        <sql:dbOpen connId="conn1" dataSource="<%= dataSrcStr %>" />
        <sql:dbQuery connId="conn1" output="xml" queryId="myquery" >
           select ENAME, EMPNO from EMP order by ename
        </sql:dbQuery>
        <sql:dbCloseQuery queryId="myquery" />
        <sql:dbClose connId="conn1" />
    </xml:transform>

Note: For the `dbOpen` tag in this example, assume that the data source specifies the user name and password as well as the URL.

##### rowset.xsl

    <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
    <xsl:template match="ROWSET">
     <html><body>
     <h1>A Simple XML/XSL Transformation</h1>
     <table border="2">
    <xsl:for-each select="ROW">
      <tr>
        <td><xsl:value-of select="@num"/></td>
        <td><xsl:value-of select="ENAME"/></td>
        <td><xsl:value-of select="EMPNO"/></td>
      </tr>
    </xsl:for-each>
    </table>
    </body></html>
    </xsl:template>
    </xsl:stylesheet>

##### useDataSource.jsp

    <body bgcolor="#FFFFFF">
    <font size=+0>
    <B>Please enter a suitable JDBC connection string, before you try the above demo</B>
    <pre>
         To use a data source that you have set up in data-sources.xml, enter the
         data source string below. Once you have set the data source string it
         will remain in effect until the session times out.
    </pre>
    <%
       String dataSrcStr;
       dataSrcStr=request.getParameter("dataSrcStr");
       if (dataSrcStr==null) {
         dataSrcStr=(String)session.getValue("dataSrcStr");
       }
       if (dataSrcStr==null) {
         dataSrcStr="jdbc/OracleCoreDS";  // default data source string
       }

       session.putValue("dataSrcStr",dataSrcStr);
    %>
    <FORM METHOD=get ACTION="<%= request.getParameter("nextaction") %>" >
    <INPUT TYPE="text" NAME="dataSrcStr" SIZE=40 value="<%=dataSrcStr%>" >
    <INPUT TYPE="submit" VALUE="Change Data Source String" >
    </FORM>
    </font>

#### Examples Using the tra nsform and parsexml Tags

This section provides two examples that take output from a `parsexml` tag and filter it through a `transform` tag, using the XSL stylesheet `email.xsl`. In each case, data is collected by the `parsexml` tag handler from a specified resource XML file, then passed explicitly from the `parsexml` tag to the `transform` tag through the `toxml1` XML object.

The first example uses the XML resource `email.xml` and the DTD `email.dtd`. No `root` attribute is specified, so validation is from the top-level element, `<email>`.

The second example uses the XML resource `emailWithDtd.xml`, which has the DTD embedded in the file. The `root` attribute explicitly specifies that validation is from the element `<email>`.

The files `email.xml`, `email.dtd`, `emailWithDtd.xml`, and `email.xsl` are also listed below.

##### Example 1 for transform and parsexml

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xml.tld"
               prefix="xml" %>
    <h3>XML Parsing Tag Email Example</h3>
    <xml:transform fromXMLObjName="toxml1" href="style/email.xsl">
       <xml:parsexml resource="style/email.xml" validateResource="style/email.dtd"
                     toXMLObjName="toxml1">
       </xml:parsexml>
    </xml:transform>

##### Example 2 for transform and parsexml

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xml.tld"
               prefix="xml" %>
    <h3>XML Parsing Tag Email Example</h3>
    <xml:transform fromXMLObjName="toxml1" href="style/email.xsl">
       <xml:parsexml resource="style/emailWithDtd.xml" root="email"
                     toXMLObjName="toxml1">
       </xml:parsexml>
    </xml:transform>

##### email.xml

    <email>
    <recipient>Manager</recipient>
    <copyto>jsp_dev</copyto>
    <subject>XML Bug fixed</subject>
    <bugno>BUG 1109876!</bugno>
    <body>for reuse tag and checked in the latest version!</body>
    <sender>Developer</sender>
    </email>

##### email.dtd

    <!ELEMENT email (recipient,copyto,subject,bugno,body,sender)>
    <!ELEMENT recipient (#PCDATA)>
    <!ELEMENT copyto (#PCDATA)>
    <!ELEMENT subject (#PCDATA)>
    <!ELEMENT bugno (#PCDATA)>
    <!ELEMENT body (#PCDATA)>
    <!ELEMENT sender (#PCDATA)>

##### emailWithDtd.xml

    <!DOCTYPE email [
    <!ELEMENT email (recipient,copyto,subject,bugno,body,sender)>
    <!ELEMENT recipient (#PCDATA)>
    <!ELEMENT copyto (#PCDATA)>
    <!ELEMENT subject (#PCDATA)>
    <!ELEMENT bugno (#PCDATA)>
    <!ELEMENT body (#PCDATA)>
    <!ELEMENT sender (#PCDATA)>]>
    <email>
    <recipient>Manager</recipient>
    <copyto>jsp_dev</copyto>
    <subject>XML Bug fixed</subject>
    <bugno>BUG 1109876!</bugno>
    <body>for reuse tag and checked in the latest version!</body>
    <sender>Developer</sender>
    </email>

##### email.xsl

    <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
    <xsl:template match="email">
     <html><body>
      To: <xsl:value-of select="recipient"/>
      CC: <xsl:value-of select="copyto"/>
      Subject:   <xsl:value-of select="subject"/> ...
      <xsl:value-of select="body"/> !!
      Thanks  <xsl:value-of select="sender"/>
    </body></html>
    </xsl:template>
    </xsl:stylesheet>