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>

5 XML and XSL Tag Support

Overview of Oracle Tags for XML Support

XML Producers and XML Consumers

Summary of OC4J Tags with XML Functionality

XML Utility Tags

XML Utility Tag Descriptions

XML transform and styleSheet Tags for XML/XSL Data Transformation

Syntax

Attributes

XML parsexml Tag to Convert from Input Stream

Syntax

Attributes

XML Utility Tag Examples

Example Using the transform Tag

Sample Stylesheet: hello.xsl

Sample JSP Page: hello.jsp

Example Using the transform and dbQuery Tags

JSP Page

rowset.xsl

useDataSource.jsp

Examples Using the transform and parsexml Tags

Example 1 for transform and parsexml

Example 2 for transform and parsexml

email.xml

email.dtd

emailWithDtd.xml

email.xsl

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

XML parsex ml Tag to Convert from Input Stream

Exa mple Using the transform Tag

Example Us ing the transform and dbQuery Tags

Examples Using the tra nsform and parsexml Tags