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 JSP specifications.

The chapter is organized as follows:

• Overview of Oracle Tags for XML Support

• XML Utility Tags

  Note: See the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for additional information about XML-related functionality for JSP pages.

Overview of Oracle Tags for XML Support

This section provides 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. The following topics are covered:

• XML Producers and XML Consumers

• Summary of OC4J Tags with XML Functionality

XML Producers and XML Consumers

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

• an XML producer, which outputs an XML object

• an XML consumer, which takes an XML object as input

Similarly, an XML-related tag can be classified as an XML producer, or 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 where the tags are nested. 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 Table 5-1 summarizes the tags that can function as XML producers or consumers.

Note the following:

• The XML transform and styleSheet tags are equivalent and produce identical results.

• For convenience, the cacheXMLObj tag is defined in the XML tag library (xml.tld) as well as the Web Object Cache tag library (jwcache.tld).

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 (and XML)	both	fromXMLObjName toXMLObjName	"Web Object Cache cacheXMLObj Tag"
dbQuery	SQL	producer	toXMLObjName	"SQL dbQuery Tag"

XML Utility Tags

This section describes XML utility tags supplied with OC4J, and is organized as follows:

• XML Utility Tag Descriptions

• XML Utility Tag Examples

In an Oracle9i Application Server installation, the tag library description file for XML utility tags, xml.tld, is located in the [Oracle_Home]/j2ee/tlds directory. To use this TLD file, you will need a taglib directive such as the following:

<%@ taglib uri="/WEB-INF/xml.tld" prefix="xml" %>

The XML tag library requires the ojsputil.jar, xmlparserv2.jar, and xsu12.jar (or xsu111.jar for JDK 1.1.x) files to be installed and in your classpath. These files are supplied with OC4J.

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

This section describes the following 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 transform 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 are synonymous, having 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

Each tag applies to what is inside its body, between its 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 set, specifying its own href pointer to the appropriate stylesheet.

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 Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference 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. (In earlier releases this was the only output choice; there was no toXMLObjName attribute.)

XML parsexml 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

This section provides the following examples:

• Example Using the transform Tag

• Example Using the transform and dbQuery Tags

• Examples Using the transform and parsexml Tags

Example 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--the XML in the page is 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="/WEB-INF/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 following output:

Text description of the illustration xslsamp.gif

Example Using 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 stylesheet 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 setconn.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="/WEB-INF/xml.tld" prefix="xml" %>
<%@ taglib uri="/WEB-INF/sqltaglib.tld" prefix="sql" %>

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

%>
<h3>Transform DBQuery Tag Example</h3>
<xml:transform href="style/rowset.xsl" >
<sql:dbOpen connId="conn1" URL="<%= connStr %>"
              user="scott" password="tiger">
    </sql:dbOpen>
    <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>

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>

setconn.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 the thin driver insert your host, port and database id.
     Once you have set the connection string it will remain in effect until
     the session times out for most demos.  For Connection Cache demos
     which use application scope on most servlet engines the connection 
     string will remain in effect for the life of the application. 
</pre>
<% 
   String connStr;
   connStr=request.getParameter("connStr");
   if (connStr==null) {
     connStr=(String)session.getValue("connStr");
   }
   if (connStr==null) {
     connStr="jdbc:oracle:thin:@localhost:1521:orcl";  // default connection str
   }

   session.putValue("connStr",connStr);
%>
<FORM METHOD=get>
<INPUT TYPE="text" NAME="connStr" SIZE=40 value="<%=connStr%>" >
<INPUT TYPE="submit" VALUE="Set Connection String" >
</FORM>
</font>

Examples Using the transform 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 parsexml 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 a separate 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="/WEB-INF/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="/WEB-INF/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>