4 XSLT Processor for Java

XSLT Processor for Java Example

This example has many comments. It uses one XML document and one XSL stylesheet as inputs.

public class XSLSample 
{
   public static void main(String args[]) throws Exception
   {
      if (args.length < 2)
      {
         System.err.println("Usage: java XSLSample xslFile xmlFile.");
         System.exit(1);
      }

      // Create a new XSLProcessor.
      XSLProcessor processor = new XSLProcessor();
      
      // Register a base URL to resolve relative references
      // processor.setBaseURL(baseURL);
      
      // Or register an org.xml.sax.EntityResolver to resolve 
      // relative references
      // processor.setEntityResolver(myEntityResolver);

      // Register an error log
      // processor.setErrorStream(new FileOutputStream("error.log"));
      
      // Set any global paramters to the processor
      // processor.setParam(namespace, param1, value1);
      // processor.setParam(namespace, param2, value2);

      // resetParam is for multiple XML documents with different parameters

      String xslFile = args[0];
      String xmlFile = args[1];

      // Create a XSLStylesheet
      //  The stylesheet can be created using one of following inputs:
      //
      // XMLDocument xslInput = /* using DOMParser; see later in this code */
      // URL         xslInput = new URL(xslFile);
      // Reader      xslInput = new FileReader(xslFile);
      
      InputStream xslInput = new FileInputStream(xslFile);

      XSLStylesheet stylesheet = processor.newXSLStylesheet(xslInput);

      // Prepare the XML instance document
      //   The XML instance can be given to the processor in one of 
      // following ways:
      //
      // URL         xmlInput = new URL(xmlFile);
      // Reader      xmlInput = new FileReader(xmlFile);
      // InputStream xmlInput = new FileInputStream(xmlFile);
      // Or using DOMParser

      DOMParser parser = new DOMParser();
      parser.retainCDATASection(false);
      parser.setPreserveWhitespace(true);
      parser.parse(xmlFile);
      XMLDocument xmlInput = parser.getDocument();

      // Transform the XML instance
      //   The result of the transformation can be one of the following:
      //
      // 1. Return a XMLDocumentFragment
      // 2. Print the results to a OutputStream
      // 3. Report SAX Events to a ContentHandler

      // 1. Return a XMLDocumentFragment
      XMLDocumentFragment result;
      result = processor.processXSL(stylesheet, xmlInput);
      
      // Print the result to System.out
      result.print(System.out);

      // 2. Print the results to a OutputStream
      // processor.processXSL(stylesheet, xmlInput, System.out);

      // 3. Report SAX Events to a ContentHandler
      // ContentHandler cntHandler = new MyContentHandler();
      // processor.processXSL(stylesheet, xmlInput, cntHandler);

   }
}

XSLT Processor for Java Extension Functions and Namespaces

Java extension functions belong to the namespace that starts with the following:

http://www.oracle.com/XSL/Transform/java/

An extension function that belongs to the following namespace refers to methods in class classname:

http://www.oracle.com/XSL/Transform/java/classname

For example, the following namespace can be used to call java.lang.String methods from XSL expressions:

http://www.oracle.com/XSL/Transform/java/java.lang.String

Static Versus Non-Static Methods

If the method is a non-static method of the class, then the first parameter is used as the instance on which the method is invoked, and the rest of the parameters are passed on to the method.

If the extension function is a static method, then all the parameters of the extension function are passed on as parameters to the static function.

<xsl:stylesheet
  xmlns:math="http://www.oracle.com/XSL/Transform/java/java.lang.Math"> 
  <xsl:template match="/"> 
  <xsl:value-of select="math:ceil('12.34')"/> 
</xsl:template> 
</xsl:stylesheet> 

Constructor Extension Function

The extension function new creates a new instance of the class and acts as the constructor.

<xsl:stylesheet 
xmlns:jstring="http://www.oracle.com/XSL/Transform/java/java.lang.String"> 
  <xsl:template match="/"> 
  <!-- creates a new java.lang.String and stores it in the variable str1 --> 
  <xsl:variable name="str1" select="jstring:new('Hello World')"/> 
  <xsl:value-of select="jstring:toUpperCase($str1)"/> 
</xsl:template> 
</xsl:stylesheet> 

Return Value Extension Function

The result of an extension function can be of any type, including the five types defined in XSL and the additional simple XML Schema data types defined in XSLT 2.0:

• NodeSet

• Boolean

• String

• Number

• ResultTree

They can be stored in variables or passed onto other extension functions.

If the result is of one of the five types defined in XSL, then the result can be returned as the result of an XSL expression.

<!-- Declare extension function namespace --> 
<xsl:stylesheet xmlns:parser =
 "http://www.oracle.com/XSL/Transform/java/oracle.xml.parser.v2.DOMParser"
 xmlns:document =
 "http://www.oracle.com/XSL/Transform/java/oracle.xml.parser.v2.XMLDocument" > 

<xsl:template match ="/"> <!-- Create a new instance of the parser, store it in
 myparser variable --> 
<xsl:variable name="myparser" select="parser:new()"/> 
<!-- Call a non-static method of DOMParser. Since the method is a non-static
 method, the first parameter is the instance on which the method is called. This
 is equivalent to $myparser.parse('test.xml') --> 
<xsl:value-of select="parser:parse($myparser, 'test.xml')"/> 
<!-- Get the document node of the XML Dom tree --> 
<xsl:variable name="mydocument" select="parser:getDocument($myparser)"/> 
<!-- Invoke getelementsbytagname on mydocument --> 
<xsl:for-each
 select="document:getElementsByTagName($mydocument,'elementname')"> 
...
</xsl:for-each> </xsl:template>
</xsl:stylesheet> 

Datatypes Extension Function

Overloading based on number of parameters and type is supported. Implicit type conversion is done between the five XSL types as defined in XSL. Type conversion is done implicitly between (String, Number, Boolean, ResultTree) and from NodeSet to (String, Number, Boolean, ResultTree). Overloading based on two types which can be implicitly converted to each other is not permitted.

String ->     java.lang.String
Number ->     int, float, double
Boolean ->    boolean
NodeSet ->    XMLNodeList
ResultTree -> XMLDocumentFragment

XSLT Processor for Java Built-In Extensions: ora:node-set and ora:output

Here are the definitions of these Oracle XSL extensions; both are preceded by xmlns:ora="http://www.oracle.com/XSL/Transform/java".

$ oraxsl foo.xml slides.xsl toc.html

<!--
    | Illustrate using ora:node-set and ora:output
    | 
    | Both extensions depend on defining a namespace
    | with the uri of "http://www.oracle.com/XSL/Transform/java"
+-->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:ora="http://www.oracle.com/XSL/Transform/java">

<!-- <xsl:output> affects the primary result document -->
<xsl:output mode="html" indent="no"/>

<!-- 
     |   <ora:output> at the top-level enables all attributes
     |   that <xsl:output> enables, but you must provide the
     |   additional "name" attribute to assign a name to
     |   these output settings to be used later.
+-->
<ora:output name="myOutput" mode="html" indent="no"/>
<!-- 
     | This top-level variable is a result-tree fragment
+-->
<xsl:variable name="fragment">
   <slides>
       <slide>
          <title>First Slide</title>
             <bullet>Point One</bullet>
             <bullet>Point Two</bullet>
             <bullet>Point Three</bullet>
       </slide>
       <slide>
          <title>Second Slide</title>
              <bullet>Point One</bullet>
              <bullet>Point Two</bullet>
              <bullet>Point Three</bullet>
       </slide>
   </slides>
</xsl:variable>
<xsl:template match="/">
<!--    | We cannot "de-reference" a result-tree-fragment to
        | navigate into it with an XPath expression. However, using
        | the ora:node-set() built-in extension function, you can
        | "cast" a result-tree fragment to a node-set which *can*
        | then be navigated using XPath. Since we'll use the node-set
        | of <slides> twice later, we save the node-set in a variable.
+-->
<xsl:variable name="slides" select="ora:node-set($fragment)"/>
<!--
    | This <html> page will go to the primary result document.
    | It is a "table of contents" for the slide show, with
    | links to each slide. The "slides" will each be generated
    | into *secondary* result documents, each slide having
    | a file name of "slideNN.html" where NN is the two-digit
    | slide number
+-->
<html> 
   <body>
      <h1>List of All Slides</h1>
<xsl:apply-templates select="$slides" mode="toc"/>
   </body>
</html>
<!--
     | Now go apply-templates to format each slide
+-->    
<xsl:apply-templates select="$slides"/>
</xsl:template>
<!-- In 'toc' mode, generate a link to each slide we match -->
<xsl:template match="slide" mode="toc">
     <a href="slide{format-number(position(),'00')}.html">
<xsl:value-of select="title"/>
     </a><br/>
</xsl:template>
<!-- 
      | For each slide matched, send the output for the current
      | <slide> to a file named "slideNN.html". Use the named
      | output style defined earlier called "myOutput".
<xsl:template match="slide">
<ora:output use="myOutput href="slide{format-number(position(),'00')}.html">
<html>
    <body>
<xsl:apply-templates select="title"/>
       <ul>
<xsl:apply-templates select="*[not(self::title)]"/>
       </ul>
    </body>
</html>
</ora:output>
</xsl:template>
<xsl:template match="bullet">
    <li><xsl:value-of select="."/></li>
</xsl:template>
<xsl:template match="title">
    <h1><xsl:value-of select="."/></h1>
</xsl:template>
</xsl:stylesheet>

Merging Two XML Documents

To merge two XML documents, you can either use the DOM APIs or use XSLT-based approaches.

If you use the DOM APIs, then you have to copy the DOM node from the source DOM document before you can append it to the destination DOM document. This operation is required to avoid DOM document ownership errors, like WRONG_DOCUMENT_ERR. Both the importNode() method, introduced in DOM 2, and adoptNode() method, introduced in DOM 3, can be used to copy and paste a DOM document fragment or a DOM node across different XML documents.

Document doc1 = new XMLDocument();
Element element1 = doc1.createElement("foo");
Document doc2 = new XMLDocument();
Element element2 = doc2.createElement("bar");
element2 = doc1.importNode(element2);
element1.appendChild(element2);

Document doc1 = new XMLDocument();
Element element1 = doc1.createElement("foo");
Document doc2 = new XMLDocument();
Element element2 = doc2.createElement("bar");
element2 = doc1.adoptNode(element2);
element1.appendChild(element2);

<messages>
   <msg>
      <key>AAA</key>
      <num>01001</num>
   </msg>
   <msg>
      <key>BBB</key>
      <num>01011</num>
    </msg>
</messages>

<messages>
   <msg>
     <key>AAA</key>
     <text>This is a Message</text>
   </msg>
   <msg>
      <key>BBB</key>
      <text>This is another Message</text>
   </msg>
</messages>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output indent="yes"/>
<xsl:variable name="doc2" select="document('demo2.xml')"/>
<xsl:template match="@*|node()">
   <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
   </xsl:copy>
</xsl:template>

<xsl:template match="msg">
   <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
         <text><xsl:value-of select="$doc2/messages/msg[key=current()/key]/text"/>
         </text>
   </xsl:copy>
</xsl:template>
</xsl:stylesheet>

$ oraxsl demo1.xml demomerge.xsl

<messages>
   <msg>
      <key>AAA</key>
      <num>01001</num>
      <text>This is a Message</text>
   </msg>
   <msg>
       <key>BBB</key>
       <num>01011</num>
       <text>This is another Message</text>
   </msg>
</messages>

Extracting Embedded XML Using Only XSLT

The content of your CDATA, it is just text. If you want the text content to be output without escaping the angle-brackets:

<xsl:value-of select="/OES_MESSAGE/PAYLOAD" disable-output-escaping="yes"/>

Support of Output Method "html" in the XSL Parser

XSLT fully supports all options of <xsl:output>. Your XSL stylesheet must be a well-formed XML document. Instead of using the <BR> element, you must use <BR/>. The <xsl:output method="html"/> requests that when the XSLT engine writes out the result of your transformation, it is a proper HTML document. What the XSLT engine reads in must be well-formed XML.

Assume that you have an XSL stylesheet that performs XML to HTML conversion. Everything works correctly with the exception of those HTML tags that end up as empty elements, that is, <input type="text"/>. For example, the following stylesheet creates an HTML document with an <input> element:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html"/>
...
<input type="text" name="{NAME}" size="{DISPLAY_LENGTH}" maxlength="{LENGTH}">
</input>
...
</xsl:stylesheet>

It renders HTML in the format of

<HTML>...<input type="text" name="in1" size="10" maxlength="20"/>
...
</HTML>

While Internet Explorer can handle this, Netscape cannot. Is there any way to generate completely cross-browser-compliant HTML with XSL?

The solution to this problem is that if you are seeing:

<input ... />

instead of:

<input ...></input>

then you are likely using the incorrect way of calling XSLProcessor.processXSL(), since it appears that it is not doing the HTML output for you. Use:

void processXSL(style,sourceDoc,PrintWriter)

instead of:

DocumentFragment processXSL(style,sourceDoc)

Creating an HTML Input Form

To generate an HTML form for inputting data using column names from the user_tab_columns table here is the XSL code:

<xsl:template match="ROW">
<xsl:value-of select="COLUMN_NAME"/>
 <INPUT NAME="{COLUMN_NAME}"/>
</xsl:template>

Correct XSL Namespace URI

The following URI is correct:

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

If you use:

xmlns:xsl="-- any other string here --"

it does not give correct output.

XSL Processor Produces Multiple Outputs

The XML Parser for Java, release 2.0.2.8 and above, supports <ora:output> to produce more than one result from one XML and XSL.

Keeping White Spaces in Your Output

Use this in your code, where (white spaces) means that you enter a space, newline, or tab there:

<xsl:text>...(white spaces)</xsl:text>

XDK Utilities That Translate Data from Other Formats to XML

XSLT translates from XML to XML, or to HTML, or to another text-based format. What about the other way around?

For HTML, you can use utilities like Tidy or JTidy to turn HTML into well-formed HTML that can be transformed using XSLT. For unstructured text formats, you can try utilities like XFlat at the following Web site:

http://www.unidex.com/xflat.htm

Multiple Threads Using a Single XSLProcessor and Stylesheet

Multiple threads can use a single XSLProcessor and XSLStylesheet instance to perform concurrent transformations. As long as you are processing multiple files with no more than one XSLProcessor and XSLStylesheet instance for each XML file you can do this simultaneously using threads.

Using Document Clones in Multiple Threads

It is safe to use clones of a document in multiple threads. The public void setParam(String,String) throws XSLException method of class oracle.xml.parser.v2.XSLStylesheet is supported. If you copy the global area set up by the constructor to another thread then it works. That method is supported since XML Parser for Java, release 2.0.2.5.

Disabling Output Escaping Is Supported

The XML Parser for Java provides an option to disable output escaping:

<xsl:text disable-output-escaping = "yes">