http://xml.apache.org/http://www.apache.org/http://www.w3.org/

What's New
DTM
XSLTC Translets

Overview
Getting Started

FAQs

Sample Apps
Command Line

Usage Patterns
Features

TrAX
API (Javadoc)

Extensions
Extensions Library

Release Notes

Xalan 2 Design
XSLTC Design

Bugs
Testing
Builds

Credits
XSLTC Credits

For this release, please note the following changes, additions, omissions, problems, procedures for running demos, and new support for the TrAX API.

For an introduction to XSLTC, see Using XSLTC.

Global changes since Xalan-Java 2.2.D14
 
NoteFor a list of Xalan-Java commits, see xalan-cvs@xml.apache.org in the Apache mailing list archive index.

Fix to Xalan-Java 2.3.0. Beginning with release 2.3.0, regexp.jar is required to compile translets and use the XSLTC API (see Setting the system classpath for XSLTC). For release 2.3.0, we posted regexp.jar to the Apache CVS repository, but we failed to update the Ant build process to include regexp.jar in the distribution files. As soon as a user alerted us to this error, we fixed build.xml to include regexp.jar in the distribution files. Accordingly, regexp.jar is in the 2.3.x binary and source distribution files.


XSLT 1.0 Conformance and Extensions
 

XSLTC does not yet support the following features of the XSL Transformations (XSLT) Version 1.0:

  • The case-order option to the sort element is not supported, because XSLTC relies on the underlying Java sorting classes (bugzilla 1396).

XSLTC supports a number of features that are not required by the XSLT 1.0 specification, but which are supported by a number of other XSLT processors:

  • Calling external Java methods from a Translet.
    At the time of writing, only static methods are supported. A call to a function whose namespace is either <http://xml.apache.org/xslt/Java or <http://xml.apache.org/xalan/xsltc/Java is resolved by loading the appropriate class and calling a static method that matches the signature of the function. The class can be specified as part of the namespace URI or as part of the function call as shown in the following example:
     <xsl:stylesheet version="1.0"
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
       xmlns:Java="http://xml.apache.org/xslt/Java"
       xmlns:Java-system="http://xml.apache.org/xslt/Java/java.lang.System">
       <xsl:template match="/">
         <xsl:value-of select="Java:java.lang.System.currentTimeMillis()"/>
         <xsl:value-of select="Java-system:currentTimeMillis()"/>
      </xsl:template>
    </xsl:stylesheet>

  • Result Tree Fragments as Node Sets
    Result Tree Fragments (RTFs) can be captured as the template content of a variable or parameter and then the variable can be passed to a for-each or an apply-templates as a node set.

  • nodeset() Function
    XSLTC also supports the nodeset() function for transforming an RTF (result tree fragment) into a node set. It can be used as an xsltc-extension function or as a standard XPATH function as shown in the following example:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"        
      xmlns:xsltc-extension="http://xml.apache.org/xalan/xsltc"
      xmlns:some-extension="http://some-extension"
      version="1.0">
      <xsl:template match="/">
        <xsl:variable name="rtf">
          <docelem>
            <elem1>elem1</elem1>
            <elem2>elem2</elem2>
          </docelem>
        </xsl:variable>
        <!-- Use nodeset as XSLTC extension -->
        <xsl:value-of select="xsltc-extension:nodeset($rtf)/docelem/elem1"/>
        <!-- Use nodeset as standard function -->
        <xsl:value-of select="nodeset($rtf)/docelem/elem1"/>
      </xsl:template> 
    </xsl:stylesheet>
    

  • Output Redirection
    Output can be redirected to one or more files, using code like the following:
     <xsl:stylesheet 
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
       xmlns:xsltc="http://xml.apache.org/xalan/xsltc"
       xsl:version="1.0">
       <xsl:template match="/">
         <xsl:text>This goes to standard output</xsl:text>
         <xsltc:output file="blob.xml">
           <xsl:text>This ends up in the file 'blob.xml'</xsl:text>
         </xsltc:output>
       </xsl:template>
    </xsl:stylesheet>


Known Problems
 
  • The strip space element does not work with copy-of. For example, with <xsl:strip-space elements="*"/>, if you do an identity transform by matching on the root node (/) and then do a copy-of select=".", the whitespace-only nodes are not stripped out. xsl:strip-space works when you do not do a copy-of.

  • In some cases, XSLTC can generate methods that are too long (> 64K length) to run, or contain jump offsets that are too large for the JVM to handle. You can minimize this by breaking up large templates into smaller templates. XSLTC has a new compile option to disable template inlining, compiling each template in a separate method. From the command line, you would use "-n" to turn off inlining, or with TrAX set the "disable-inlining" attribute to the TransformationFactory. For example,
    TransformationFactory tfac = new TransformationFactory(); 
    tfac.setAttribute("disable-inlining", new Boolean(true))

  • XSLTC tries to determine the order in which global variables are initialized by tracking the dependencies between them. In some cases, the value of a variable may depend on a template, e.g., if xsl:call-template is used to initialized a variable whose type is RTF. If this happens, a NPE may be thrown at runtime when the translet attempts to access a variable that has not been properly initialized. In most cases, this problem can be avoided by reordering the variable declarations.

To check on the open bugs in the current Apache xml-xalan/java repository, follow the instructions below:

  1. Go to http://nagoya.apache.org/bugzilla.
  2. Select Query Existing Bug Reports.
  3. Choose:
    Program: XalanJ2
    Component: org.apache.xalan.xsltc (and) Xalan-Xsltc
  4. Submit the query.

Smart Transformer Switch
 

As part of the TrAX API, a "Smart Transformer Switch" enables automatic switching between Xalan and XSLTC processors within your application. It uses Xalan to create your Transformer objects, and uses XSLTC to create your Templates objects.

To use the switch, you set the TrAX system property, javax.xml.transform.TransformerFactory, to org.apache.xalan.xsltc.trax.SmartTransformerImpl. For one-time transformations or transformations that require extensions supported by Xalan, and not XSLTC, you would use Transformer objects. For a repeated transformation where performance is critical, you would use Templates objects.



Copyright © 2002 The Apache Software Foundation. All Rights Reserved.