XSLT is a language, based on Extensible Markup Language (XML), that you can use to transform one XML document into another text document. For example, you can use XSLT to accept an XML data document as input, perform arithmetic calculations on element values in the document, and generate an Extensible HyperText Markup Language (XHTML) document that shows the calculation results.In XSLT, XPath is used to navigate and process elements in the source node tree. XPath models an XML document as a tree made up of nodes; the types of nodes in the XPath node tree correspond to the types of nodes in a DOM tree.

This chapter assumes that you are familiar with these World Wide Web Consortium (W3C) standards:

• Extensible Stylesheet Language (XSL) and Extensible Stylesheet Language Transformations (XSLT). For a general introduction to XSLT, see the XML resources listed in Related Documents.

The Oracle XML Developer's Kit (XDK) XSLT processor supports the XSLT2.0 recommendation.

XPath, which is the navigational language used by XSLT and other XML languages, is available in two versions: XPath 2.0 and the XPath 1.0 Recommendation.

Oracle XML Developer's Kit (XDK) provides several useful features not included in XSLT 1.0. To use XSLT 2.0, set the version attribute in your stylesheet.

<? xml-stylesheet version="2.0" ... ?>

Useful XSLT 2.0 features include these:

• User-defined functions

  You can use the <xsl:function> declaration to define functions. This element must have one name attribute to define the function name. The value of the name attribute is a QName. The content of the <xsl:function> element is zero or more xsl:param elements that specify the formal arguments of the function, followed by a sequence constructor that defines the value returned by the function.

  QName can have a null namespace, but user-defined functions must have a non-null namespace. That is, if abc is defined as a namespace, then add is not a legal user-defined function, but abc:add is.

• Grouping

  You can use the <xsl:for-each-group> element, current-group() function, and current-grouping-key() function to group items.

• Multiple result documents

  You can use the <xsl:result-document> element to create a result tree. The content of the <xsl:result-document> element is a sequence constructor for the children of the document node of the tree.

  For example, this element enables you to accept an XML document as input and break it into separate documents. You can take an XML document that describes a list of books and generate an XHTML document for each book. You can then validate each output document.

• Temporary trees

  Instead of representing the intermediate XSL transformation results and XSL variables as strings, as in XSLT 1.0, you can store them as a set of document nodes. The document nodes, which you can construct with the <xsl:variable>, <xsl:param>, and <xsl:with-param> elements, are called temporary trees.

• Character mapping

  In XSLT 1.0, you had to use the disable-output-escaping attribute of the <xsl:text> and <xsl:value-of> elements to specify character escaping. In XSLT 2.0, you can declare mapping characters with an <xsl:character-map> element as a top-level stylesheet element. You can use this element to generate files with reserved or invalid XML characters in the XSLT outputs, such as <, >, and &.

The basic design of the XSLT processor for Java is presented.

Figure 14-1 illustrates this process.

Figure 14-1 Using the XSLT Processor for Java

Description of "Figure 14-1 Using the XSLT Processor for Java"

Demo programs for the XSLT processor for Java are included in $ORACLE_HOME/xdk/demo/java/parser/xslt.

1. Change into the $ORACLE_HOME/xdk/demo/java/parser/xslt directory (UNIX) or %ORACLE_HOME%\xdk\demo\java\parser\xslt directory (Windows).
2. Make sure that your environment variables are set as described in Setting Up the XDK for Java Environment
3. Run make (UNIX) or Make.bat (Windows) at the command line. The make file compiles the source code and then runs the XSLSample and XSLSample2 programs for each *.xml file and its associated *.xsl stylesheet. The program writes its output for each transformation to *.out.
4. You can view the *.out files to see the output for the XML transformations. You can also run the programs on the command line as follows, where name is replaced by match, math, and so forth:

   java XSLSample name.xsl name.xml
   java XSLSample2 name.xsl name.xml
   

   For example, run the match.xml demos:

   java XSLSample match.xsl match.xml
   java XSLSample2 match.xsl match.xml

XDK includes oraxsl, which is a command-line Java interface that can apply a stylesheet to multiple XML documents. The $ORACLE_HOME/bin/oraxsl and %ORACLE_HOME%\bin\oraxsl.bat shell scripts execute the oracle.xml.jaxb.oraxsl class.

oraxsl options source stylesheet result

The fundamental classes used by the XSLT processor are DOMParser and XSLProcessor. The XSL2Sample.java demo program provides a good illustration of how to use these classes to transform an XML document with an XSLT stylesheet.

1. Create a DOM parser object that you can use to parse the XML data documents and XSLT stylesheets. This code fragment from XSL2Sample.java shows how to instantiate a parser:

   XMLDocument xml, xsldoc, out;URL xslURL;URL xmlURL;
   // ... 
   parser = new DOMParser();parser.setPreserveWhitespace(true);
   

   By default, the parser does not preserve white space unless a DTD is used. It is important to preserve white space because it enables XSLT white space rules to determine how white space is handled.

2. Parse the XSLT stylesheet with the DOMParser.parse() method. this code fragment from XSL2Sample.java shows how to perform the parse:

   xslURL = DemoUtil.createURL(args[0]);
   parser.parse(xslURL);
   xsldoc = parser.getDocument();
   

3. Parse the XML data document with the DOMParser.parse() method. this code fragment from XSL2Sample.java shows how to perform the parse:

   xmlURL = DemoUtil.createURL(args[1]);
   parser.parse(xmlURL);
   xml = parser.getDocument();
   

4. Create a new XSLT stylesheet object. You can pass objects of these classes to the XSLProcessor.newXSLStylesheet() method:

   • java.io.Reader

   • java.io.InputStream

   • XMLDocument

   • java.net.URL

   For example, XSL2Sample.java shows how to create a stylesheet object from an XMLDocument object:

   XSLProcessor processor = new XSLProcessor();
   processor.setBaseURL(xslURL);
   XSLStylesheet xsl = processor.newXSLStylesheet(xsldoc);
   

5. Set the XSLT processor to display any warnings. For example, XSL2Sample.java invokes the showWarnings() and setErrorStream() methods:

   processor.showWarnings(true);
   processor.setErrorStream(System.err);
   

6. Use the XSLProcessor.processXSL() method to apply the stylesheet to the input XML data document. Table 14-3 lists some other available XSLProcessor methods.

   Table 14-3 XSLProcessor Methods

   Method	Description
   removeParam()	Removes parameters.
   resetParams()	Resets all parameters.
   setParam()	Sets parameters for the transformation.
   setBaseUrl()	Sets a base URL for any relative references in the stylesheet.
   setEntityResolver()	Sets an entity resolver for any relative references in the stylesheet.
   setLocale()	Sets a locale for error reporting.

   This code fragment from XSL2Sample.java shows how to apply the stylesheet to the XML document:

   processor.processXSL(xsl, xml, System.out);
   

7. Process the transformed output. You can transform the results by creating an XML document object, writing to an output stream, or reporting SAX events.

   This code fragment from XSL2Sample.java shows how to print the results:

   processor.processXSL(xsl, xml, System.out);

   See Also:

   • XSL Transformations (XSLT)

   • The Extensible Stylesheet Language Family (XSL)

Sample programs show how to obtain the results from an XSL transformation.

XMLDocumentFragment result = processor.processXSL(xsl, xml);
result.print(System.out);

The XSLT 1.0 standard defines two kinds of extensions: extension elements and extension functions. XDK provides extension functions for XSLT processing that enable users of the XSLT processor to invoke any Java method from XSL expressions. When using Oracle XSLT extensions, follow these guidelines:

• When you define an XSLT extension in a given programming language, you can use only the XSLT stylesheet with XSLT processors that can invoke this extension. Thus, only the Java version of the processor can invoke extension functions that are defined in Java.

• Use XSLT extensions only if the built-in XSL functions cannot solve a given problem.

• As explained in this section, the namespace of the extension class must start with the proper URL.

These Oracle extension functions are especially useful:

• <ora:output>, you can use <ora:output> as a top-level element or in an XSL template. If used as a top-level element, it is similar to the <xsl:output> extension function, except that it has an additional name attribute. When used as a template, it has the additional attributes use and href. This function is useful for creating multiple outputs from one XSL transformation.

• <ora:node-set>, which converts a result tree fragment into a node-set. This function is useful when you want to refer the existing text or intermediate text results in XSL for further transformation.

The Oracle Java extension functions belong to the namespace that corresponds to this Universal Resource Identifier (URI): http://www.oracle.com/XSL/Transform/java/. An extension function that belongs to this namespace refers to methods in the Java classname, so that you can construct URIs in this format: http://www.oracle.com/XSL/Transform/java/classname.

If a Java method is a nonstatic method of a class then the first parameter is used as the instance on which the method is invoked, and the rest of the parameters are passed to the method. If the extension function is a static method, however, then all the parameters of the extension function are passed as parameters to the static function.

oraxsl ceil.xsl ceil.xsl ceil.out

<?xml version = '1.0' encoding = 'UTF-8'?>
13

<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  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> 

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

oraxsl hello.xsl hello.xsl hello.out

<?xml version = '1.0' encoding = 'UTF-8'?>
HELLO WORLD

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  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>

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:

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

oraxsl gettitle.xsl gettitle.xsl variable.out

<?xml version = '1.0' encoding = 'UTF-8'?>
The value of the title element is: Section Tests

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  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 and store it in myparser variable --> 
    <xsl:variable name="myparser" select="parser:new()"/> 

    <!-- Call an instance method of DOMParser. The first parameter is the object.
     The PI is equivalent to $myparser.parse('file:/my_path/variable.xml'). Note
     that you should replace my_path with the absolute path on your system. --> 
    <xsl:value-of select="parser:parse($myparser, 'file:/my_path/variable.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,'chapter')">
      The value of the title element is: <xsl:value-of select="docinfo/title" />
    </xsl:for-each>
  </xsl:template>
</xsl:stylesheet>

Examples show how to merge XML documents using XSLT.

oraxsl msg_w_num.xml msgmerge.xsl msgmerge.xml

<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 version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output indent="yes"/>
  <!-- store msg_w_text.xml in doc2 variable -->
  <xsl:variable name="doc2" select="document('msg_w_text.xml')"/>
  
  <!-- match each node in input xml document, that is, msg_w_num.xml -->
  <xsl:template match="@*|node()">
     <!-- copy the current node to the result tree -->
     <xsl:copy>
        <xsl:apply-templates select="@*|node()"/>
     </xsl:copy>
  </xsl:template>

  <!-- match each <msg> element in msg_w_num.xml -->
  <xsl:template match="msg">
     <xsl:copy>
        <xsl:apply-templates select="@*|node()"/>
        <!-- insert two spaces so indentation is correct in output document -->
        <xsl:text>  </xsl:text> 
        <!-- copy <text> node from msg_w_text.xml into result tree -->
        <text><xsl:value-of 
               select="$doc2/messages/msg[key=current()/key]/text"/>
        </text>
     </xsl:copy>
  </xsl:template>
</xsl:stylesheet>

<?xml version = '1.0' encoding = 'UTF-8'?>
<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>

To generate an HTML form for inputting data that uses column names from a database table, you can use the XML SQL Utility (XSU) to get an XML document based on the user_tab_columns table and then use XSLT to transform the XML into an HTML form.

1. Use XSU to generate an XML document based on the columns in the table. For example, using the table hr.employees, you can run XSU from the command line:

   java OracleXML getXML -user "hr/password"\
    "SELECT column_name FROM user_tab_columns WHERE table_name = 'EMPLOYEES'"
   

2. Save the XSU output as an XML file called emp_columns.xml. The XML looks like this, with one <ROW> element corresponding to each column in the table (some <ROW> elements have been removed to conserve space):

   <?xml version = '1.0'?><ROWSET>
      <ROW num="1">
         <COLUMN_NAME>EMPLOYEE_ID</COLUMN_NAME>
      </ROW>
      <ROW num="2">
         <COLUMN_NAME>FIRST_NAME</COLUMN_NAME>
      </ROW>
      <!-- rows 3 through 10 -->
      <ROW num="11">
         <COLUMN_NAME>DEPARTMENT_ID</COLUMN_NAME>
      </ROW>
   </ROWSET>
   

3. Create an XSLT stylesheet to transform the XML into HTML. For example, create the columns.xsl stylesheet:

   <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
     <xsl:output method="html"/>
     <xsl:template match="/">
       <HTML>
         <xsl:apply-templates select="@*|node()"/>
       </HTML>
     </xsl:template>
     <xsl:template match="ROW">
       <xsl:value-of select="COLUMN_NAME"/>
       <xsl:text>&nbsp;</xsl:text>
       <INPUT NAME="{COLUMN_NAME}"/>
       <BR/>
     </xsl:template>
   </xsl:stylesheet>
   

4. Run the oraxsl utility to generate the HTML form. For example:

   oraxsl emp_columns.xml columns.xsl emp_form.htm
   

5. Review the output HTML form, which has contents similar to these:

   <HTML>
      EMPLOYEE_ID&nbsp;<INPUT NAME="EMPLOYEE_ID"><BR>
      FIRST_NAME&nbsp;<INPUT NAME="FIRST_NAME"><BR>
      LAST_NAME&nbsp;<INPUT NAME="LAST_NAME"><BR>
      EMAIL&nbsp;<INPUT NAME="EMAIL"><BR>
      PHONE_NUMBER&nbsp;<INPUT NAME="PHONE_NUMBER"><BR>
      HIRE_DATE&nbsp;<INPUT NAME="HIRE_DATE"><BR>
      JOB_ID&nbsp;<INPUT NAME="JOB_ID"><BR>
      SALARY&nbsp;<INPUT NAME="SALARY"><BR>
      COMMISSION_PCT&nbsp;<INPUT NAME="COMMISSION_PCT"><BR>
      MANAGER_ID&nbsp;<INPUT NAME="MANAGER_ID"><BR>
      DEPARTMENT_ID&nbsp;<INPUT NAME="DEPARTMENT_ID"><BR>
   </HTML>