blob: 90d3ea3a25abbd832161c66dab4099069d17e69b [file] [log] [blame]
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"[
<!ENTITY xsltc_history SYSTEM "xsltc_history.xml">]>
<s1 title="XSLTC Release Notes">
<p>For this release, please note the following changes, additions, omissions, problems, procedures for running demos,
and new support for the TrAX API.</p>
<p>For an introduction to XSLTC, see <link idref="xsltc_usage">Using XSLTC</link>.</p>
<li><link anchor="xsltcnew">Changes and New Features</link></li>
<li><link anchor="xsltcconf">Conformance</link></li>
<li><link anchor="xsltcknownproblems">Known Problems</link></li>
<li><link anchor="xsltcsmart">Smart Transformer Switch</link></li>
<li><link anchor="xsltcdemos">Running Demos</link></li>
<li><link idref="xsltc_history">History of XSLTC software changes</link></li>
<anchor name="xsltcnew"/>
<s2 title="Changes since &xslt4j; 2.2.D14">
<p><em>Fix to &xslt4j; 2.3.0.</em> Beginning with release 2.3.0, regexp.jar is required to compile translets and use the XSLTC API (see <link idref="xsltc_usage" anchor="classpath">Setting the system classpath for XSLTC</link>). 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.1 binary and source distribution files.</p>
<anchor name="xsltcconf"/>
<s2 title="XSLT 1.0 Conformance and Extensions">
<p>XSLTC does not yet support the following features of the <resource-ref idref="xslt"/>:</p>
<li>Explicitly set template priorities are ignored (bugzilla 2886)</li>
<li>The case-order option to the sort element is not supported, because XSLTC relies on the underlying Java
sorting classes (bugzilla 1396).
<p>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:</p>
<li>Support for extension elements and external Java functions is incomplete.
Currently you can set up an extension function
to call a static Java method. For the extension namespace, use<br/>
and then within the xsl reference the static method with <code>java:SomeClass.Method()</code>.
<li>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.
<li>Output can be redirected to a file using the &lt;xsltc:output&gt; element. It takes a file
attribute to specify the output file. Attribute value templates can be used within the &quot;file&quot;
attribute to construct the name.
<anchor name="xsltcknownproblems"/>
<s2 title="Known Problems">
<li>Casting variables: XSLTC requires you to explicitly type cast values
returned by variables or expressions, when you use them in tests. Always a good
practice, but it may seem like overkill in some in contexts, where other XSLT processors
automatically assume or convert to the correct type. For example. unless you cast $country
to a string in the following apply-templates, entry nodes whose &lt;country&gt; elements
contain a string matching the global $country parameter are NOT selected.<br/><br/>
&nbsp;&nbsp;&nbsp;&nbsp;<code>&lt;xsl:apply-templates select="entry[country=string($country)]"/&gt;</code></li>
<li>XSLTC does not produce the correct output on the XSLTMark Performance Benchmark tests called 'alphabetize'
(bugzilla 5573), and 'trend' (bugzilla 5577).
<li>XLSTC throws a ClassCastException in method setImportPrecedence(int) of class
Stylesheet when 'elements' does not contain only TopLevelElements, thus causing compilation to fail (bugzilla 5964).
<li>XSLTC compiler can generate classes with methods longer than 65535 bytes. As a results the
compiled translet cannot be run (bugzilla 4516)</li>
<li>Using the 'select' attribute versus the template content to assign a value to a variable can lead to
inconistent results. For example, you get different results when
select=&quot;preceding-sibling::*[position() =1]/@x&quot; is used as the attribute
of the &lt;xsl:variable&gt; element versus when it is used as the attribute of an &lt;xsl:value-of&gt; element
contained within the &lt;xsl:variable&gt; element (bugzilla 6072).
<li>Setting the output type to XHTML and including the xmlns=&quot;; attribute in
the &lt;html&gt; Literal Result Element, causes XSLTC to disregard the mode attribute within apply-templates
(bugzilla 6074).
<li>After the first transformation, using a cached template object, the ouput is prematurely terminated
after an xsl:comment element. This has been reported to happen only when the stylesheet also includes
an xsl:for-each element (bugzilla 6109).
<li>XSLTC TRAX API produces an incorrect DOM Structure when using a DOMResult.
The org.apache.xalan.xsltc.trax.SAX2DOM class automatically adds a Element with
the name "root" to the top of the DOM tree on the startDocument method. On a
successful transform call, the node returned from the DOMResult.getNode()
method is the document node, with this 'root' element attached as the first
child. Xalan and Saxon both have the output document top nodes directly
attached below the Document node. Also, the TransformerImpl and SAX2DOM Classes does not respect
any node already set in the DOMResult (from bugzilla 6417).
<anchor name="xsltcsmart"/>
<s2 title="Smart Transformer Switch">
<p>As part of the TrAX API, a &quot;Smart Transformer Switch&quot; enables automatic switching between Xalan and XSLTC
processors within your application. It uses Xalan to create your
<code>Transformer</code> objects, and uses XSLTC to create your <code>Templates</code> objects.</p>
<p>To use the switch, you set the TrAX system property,
<code>javax.xml.transform.TransformerFactory</code>, to <code>org.apache.xalan.xsltc.trax.SmartTransformerImpl</code>.
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.</p>
<s2 title="Running Demos">
<p>XSLTC provides demos for using XSLTC as a servlet and as a handler for
Brazil (a new and powerful Web techology from Sun labs). To run these demos,
download Brazil from sunlabs:</p>
<p><code>&nbsp;&nbsp;&nbsp;&nbsp;<jump href=""></jump></code></p>
<p>and the java extensions for servlets from Sun:</p>
<jump href=""></jump>
<p>The translet must be specified as a pure class name, accessible
through the Brazil handler's classpath. For example:</p>
<p>The document must be specified as a valid URL. For example:</p>
<p>If the file is local to the Brazil handler, it has to be
specified using the "file:filename.xml" format.</p>
<note>You also need to make the Brazil and javax classes available from your classpath</note>
<p>See also: <link idref="samples" anchor="translets">sample JAXP translets</link>.</p>