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

What's New

Overview
Getting Started

FAQs

Sample Apps
Command Line

Usage Patterns

API (Javadoc)

Extensions
Extensions Library

Release Notes

Xalan 2 Design

Bugs
Testing

Credits

Xalan-Java version 2.0.0

Status
 
Changes since Xalan-Java version 2.0.D07
 

This release includes several bug fixes to the Xalan-Java and TrAX core and to the Xalan-Java 1 compatibility API. We also updated bsf.jar to the Bean Scripting Framework (BSF) release candidate 2.2, which fixes a bug running JPython extensions.

Core bug fixes:

  • A threading problem showed up when using multiple processors. We fixed it by using a separate XPathContext object to do whitespace node matches (xsl:strip-space).

  • Fixed a bug running Norm Walsh's DocBook stylesheets by not setting the variable stack position if the FilterExprWalker is not owned by a top-level NodeIterator.

  • Fixed a problem with null namespace being passed from xsl:element. This bug also surfaced while processing DocBook stylesheets.

  • In the interest of stability, we now treat "unknown error in XPath" as a fatal error.

  • Added support in stylesheet processing instructions for "text/xml" and "application/xml+xslt" mime types.

  • Fixed tokenizing of stylesheet processing instructions to allow parameters to be passed to server in href attributes.

  • Fixed a bug passing Transformer creation error messages to ErrorListener when an ErrorListener has been set on TransformerFactory.

  • When using an Exception to instantiate a FactoryConfigurationError (extends Error), we now propagate the Exception message to super().

  • Added defensive code to ElemTemplateElement for handling a null URI.

  • When using an Exception to instantiate a TransformerException (extends Exception), we now propagate the Exception message to super() rather than a generic message.

  • Fixed a bug (the generation of an unwanted entity reference) performing the identity transformation (see Serializing output) with an XML document containing a DOCTYPE declaration.

  • Message manager modified so that the SourceLocator must always be passed in, which will make a major difference in getting line number information.

  • xsl:element's handling of namespace attribute and prefix in name attribute changed so that it no longer manufactures prefixes... it always tries its best to match the prefix entered.

  • Bug fixed with namespace contexts in the stylesheet processor. The bug could cause <a xmlns:a="x"><b> to produce <a xmlns:a="x"><b xmlns:a="x">.

  • Modified processing of xsl:message to enhance it as a debugging aid. Line numbers are now output with each message. If the terminate attribute is true (the default is false) the message is sent to the console, and an exception is thrown with the message "Stylesheet directed termination".

  • In TransformerException, check that the cause != null when checking for a contained exception.

  • Fixed a problem validating non-namespaced attributes and a problem allowing non-namespaced attributes to be children of the stylesheet element.

  • Fixed checking of number of arguments in document() function.

  • Fixed problem with mutation of templates at run time. Templates resolution now takes place during the compose() method.

  • Fixed some minor threading issues in org.apache.xalan.stree (Child, Parent, ElementImpl, SourceTreeHandler).

  • Synchronized TrAX API functions subject to mutation to prevent mutation during a transformation.

  • Fixed bug reported by Jano Elovirta: substring() was returning an error if the start index is larger than the string.

  • Set StringKey.toString() to return the underlying String (m_str), thus avoiding a potential symmetry problem with the equals() method reported by Ito Kazumitsu.

  • In response to note from Ito Kazumitsu, changed Java encoding name "EUCJIS" in FormatterToXML to "EUC_JP".

  • When Xalan creates a FileOutputStream, it now closes the stream before exiting.

  • Fixed handling of an exception that can be thrown while building a DOM.

  • Fixed a problem reported by Dimitry Voytenko serializing compiled stylesheets.

  • For support of applets, modified TransformerFactory System.getProperty() calls to catch SecurityExceptions.

  • Fixed a bug reported by Krishna Mohan Meduri setting output properties.

  • Fixed error recovery when xsl:element encounters a bad name or unresolvable prefix.

  • Added AbstractMethodError handling to existing NoSuchMethodError handling as a fallback to the XMLReaderFactory for XML parsers that do not implement the JAXP parsers interface for creating an XMLReader

  • Fixed bug with cloned iterators reported by Tim Sean.

  • Fixed null pointer exception that could occur with getValue("xxx").

  • Fixed bug reported by Tim Sean handling the xml:space attribute.

Bug fixes in the Xalan-Java 1 compatibility API:

  • Fixed ProblemListener (for processing error messages) to derive from Xalan-Java 2 ErrorHandler.

  • Fixed evaluation of stylesheet string parameters to conform to Xalan-Java 1 behavior (expressions for Xalan-Java 1 vs. String objects for Xalan-Java 2).

  • Added XPathSupport and XPathSupportDefault, and fixed the derivation of XObject sub-types (XString, etc.).

  • Fixed bug with XSLTProcessor process(xmlIn, null, out) method so that it uses the StylesheetRoot (if one exists) that has been created with the processStylesheet() method.

For a list of tasks in the Xalan-Java 2 To-Do list that have been completed, see Tasks completed.


Other points of interest
 
  • Handling xsl:namespace-alias declarations: In release 2.0.D01, we reported the need to do some research concerning exactly how Xalan should handle xsl:namespace-alias declarations. As a result of discussions among members of the W3C Working Group on XSL, we have reached a more precise consensus on how namespaces should be represented when an xsl:namespace-alias declaration is in effect.

    If a literal result element has a namespace prefix, the prefix will be preserved and the namespace URI of the element will be as specified in the xsl:namespace-alias element, but the result-prefix is not required to appear in the result. This also applies to the two other cases of "Literal namespace URI" mentioned in the XSLT Recommendation on Literal Result Elements. More simply, if the stylesheet calls for <axsl:foo> to be output as a literal result element, then it will be output as <axsl:foo> in the result, but the namespace associated with this "axsl" prefix will be as designated in the xsl:namespace-alias declaration.

  • For HTML output, Xalan-Java 2 outputs character entity references (&copy; etc.) for the special characters designated in Appendix A. DTDs of the XHTML 1.0: The Extensible HyperText Markup Language. Xalan-Java 1.x, on the other hand, outputs literal characters for some of these special characters.

  • In conformance with the XSLT Recommendation on the HTML Output Method and Section B.2.1 of the HTML 4.0 Recommendation, Xalan-Java 2 uses %hh encoding for each byte of the UTF-8 representation of non-ASCII characters in HTML URI attributes.

  • When your stylesheet asks for an explicit carriage-return character (&#13;) to be inserted into the output, it is output during the serialization process in escaped form unless escaping has been disabled. When your stylesheet asks for an explicit line-feed character (&#10;) to be output, the system-default line-break character(s) is/are output during the serialization process. Also keep in mind that the XML parser normalizes line-breaks to line-feeds when it sends character events to the processor.

  • If your XML input is a DOM, use the javax.xml.parsers.DocumentBuilderFactory setCoalescing() method to set coalescing to true (it is false by default), if you want to append CDATA sections to adjacent text sections to form a single text node (as the XPath standard calls for), and if the XML parser supports this feature (Xerces-Java version 1.2.3 does not).

Open bugs
 

If you find a bug that does not appear on the list below, please report it to the Xalan Development Mailing List with "[Xalan-J 2 BUG]" in the subject line. We strongly encourage you write patches for problems you find and submit them to xalan-dev@xml.apache.org. We review the patches we receive to make sure they do not break something else, and (assuming they do not) include them in our next release. In the interest of fixing bugs, adding enhancements, and addressing outstanding design issues, we sincerely want (and need!) your active participation in the ongoing development of Xalan.

NoteMost of the bugs reported below have been generated by "negative tests," that is they indicate a failure to catch and/or return a useful message when the XSL transformer encounters a stylesheet syntax error.

Open bugs:

  • SPR#: DMAN4TATQP Date Created: 1/24/2001
    Description: No error raised for use-attribute-sets referring to non-existent set

  • SPR#: DMAN4TATTY Date Created: 1/24/2001
    Description: Must enforce correct structure of xsl:choose

  • SPR#: DMAN4TATYP Date Created: 1/24/2001
    Description: Need to catch use of | as or operator in boolean expression

  • SPR#: DMAN4TAU4Z Date Created: 1/24/2001
    Description: Need better catching of invalid characters in element/attribute/PI names

  • SPR#: DMAN4TAU7L Date Created: 1/24/2001
    Description: Need to enforce match-pattern syntax where used in xsl:key

  • SPR#: DMAN4TAUA4 Date Created: 1/24/2001
    Description: Use of undefined key name as first arg to key() should raise error

  • SPR#: DMAN4TAUDP Date Created: 1/24/2001
    Description: Must raise error when other top-level elements precede xsl:import

  • SPR#: DMAN4TAUFF Date Created: 1/24/2001
    Description: If a namespace prefix is referenced, it's an error for it to be unmapped

  • SPR#: DMAN4TAUJX Date Created: 1/24/2001
    Description: Must raise error when xsl:template has neither name nor match

  • SPR#: DMAN4TAURH Date Created: 1/24/2001
    Description: Need to catch duplicate-named templates, variables, params

  • SPR#: DMAN4TAUU5 Date Created: 1/24/2001
    Description: Need to report syntax errors with decimal-format pattern

  • SPR#: DMAN4TAV25 Date Created: 1/24/2001
    Description: Must detect grouping-separator being longer than one character in xsl:number

  • SPR#: DMAN4TAV3U Date Created: 1/24/2001
    Description: Where attribute can only take a keyword from a list, must raise error for other values

  • SPR#: DMAN4TAV5S Date Created: 1/24/2001
    Description: Should raise error when xsl:number tries to generate out-of-range Roman numerals

  • SPR#: DMAN4TAV8P Date Created: 1/24/2001
    Description: Need to raise error when attempting to output out-of-range character (based on the encoding)

  • SPR#: DMAN4TAVG5 Date Created: 1/24/2001
    Description: In multi-level sort, must raise warning if any level is bad

  • SPR#: DMAN4TAVHR Date Created: 1/24/2001
    Description: Should raise error in xsl:param or xsl:variable if value set two ways

  • SPR#: DMAN4TAVKC Date Created: 1/24/2001
    Description: Need to report when xsl:param is not first child inside xsl:template

  • SPR#: PDIK4TGQLK Date Created: 1/30/2001
    Description: Seems that we should be outputting the xml namespace node for document element of xml document.

  • SPR#: SCUU4SUQRE Date Created: 1/10/2001
    Description: SystemId: file:tests/api/file.xml not found

  • SPR#: SCUU4TCNLH Date Created: 1/26/2001
    Description: xalanj1compat.jar: setStylesheet(s1); process(xml, s2, target); uses s1 instead of s2

Xerces bug in Xerces-Java version 1.2.3:

  • Xerces-Java 1.2.3 does not process namespaces in SAX events when parsing UTF-16 documents, which causes Xalan-Java to fail with UTF-16 documents. Xerces will post a fix shortly.


Version of Xerces to use
 

The Xalan-Java version 2.0.0 has been tested with Xerces-Java version 1.2.3. The Xalan-Java version 2.0.0 download from xml.apache.org includes xerces.jar from Xerces-Java version 1.2.3. For information about including xerces.jar on the system class path, see Setting up the system class path.

Important You may experience unpredictable anomalies if your Xalan and Xerces builds are not in synch. If you download an update to Xalan, check the release notes to determine which version of Xerces you should use.

NoteYou can use Xalan with other XML parsers that implement the Java API for XML Parsing 1.0. See Plugging in the Transformer and XML parser.

To-do tasks
 

For a list of goals, tasks, and target dates for completion, see Xalan-Java Version 2: Things To Do. As tasks are completed, they are moved from the to-do list to Completed.

The source document for the to-do list is an active document in the Apache CVS repository: xml-xalan/java/todo.xml.



Build Notes
 
Using Ant
 

Apache Ant is a flexible, powerful, and easy-to-use Java build tool that we include with the Xalan-Java distribution. The Ant JAR file is in the bin directory, and the cross-platform XML build file (build.xml) is in the root directory along with a Windows32 batch file (build.bat) and a UNIX shell file (build.sh). The build file defines the "targets" that you can use Ant to build. The batch and shell files set up the classpath and launch Ant with the target (and any other arguments) you provide.

Instructions for using Ant

  1. Set the JAVA_HOME environment variable to the JDK root directory.

    If you are using JDK 1.1.8, you must also put classes.zip in the JDK bin directory on the classpath. You can use Ant with JDK 1.1.8 to compile and jar the Xalan-Java source files, but you must have JDK 1.2.2 or higher to build the documentation.

  2. Depending on your environment, run the batch file (build.bat) or shell file (build.sh) from the Xalan-Java root directory, optionally with arguments (see the table of targets below).

    The batch/shell file adds several JAR files to the classpath and launches Ant with any arguments you provide. If you provide no target, Ant compiles the source files and rebuilds xalan.jar (the "jar" target).

You can also set up your classpath manually (see build.bat or build.sh for the details), and then run Ant as follows:

java org.apache.tools.ant.Main target

where target is nothing (for the default target) or one of the following.

Target  What Ant does 
compile  compiles Xalan-Java in build/classes. 
jar (the default)  creates xalan.jar in the build directory 
samples  compiles and jars the sample apps in build/xalansamples.jar 
servlet  compiles and jars the sample servlet in build/xalanservlet.jar 
docs  creates the HTML User's Guide in build/docs 
javadocs  generates the API documentation in ./build/docs/apidocs 
dist  generates a complete distribution tree with zip and tar.gz distribution files in build 
clean  purges the build and distribution 

If you build a target that depends on other targets, Ant creates those other targets in the correct order.


Rebuilding Xalan-Java
 

The Xalan-Java build is in xalan.jar. The Xalan-Java source code tree is in the src directory.

If you are using Ant, the target is jar (the default). For more information, see Using Ant.

If you want to do the build without Ant, keep the following in mind:

  • Set the classpath to include the src directory, xerces.jar, bsf.jar, and bsfengines.jar.
  • Use a Java compiler (such as the IBM Just-In-Time compiler or the Sun javac) to compile all the .java files in the src tree.
  • Use the Sun jar utility to store the resulting .class files in xalan.jar

Rebuilding a sample application
 

If you modify a sample and want to recompile it, you can run the Java compiler in the directory containing the example. Be sure xalan.jar and xerces.jar are on the classpath. To recompile (and run!) the class files in the Servlet subdirectory, the javax.servlet and javax.servlet.http packages must also be on the classpath. Sun distributes these packages in the JSWDK 1.0.1 servlet.jar file.

After recompiling a sample, you can use the Sun jar utility to place your new .class files in xalansamples.jar.

You can use Ant with the samples target to recompile the samples and place the unpackaged class files in xalansamples.jar. For more information, see Using Ant.

NoteTo rebuild (and to run) the sample servlet, the javax.servlet and javax.servlet.http packages must be on your classpath.

Rebuilding the Xalan-Java documentation
 

Xalan-Java includes a number of XML source files, XSL stylesheets, document type definition (DTD) files, entity relationship (ENT) files, graphics, and a JavaScript file that provide the input for the Xalan HTML User's Guide, and the overview and package-level documents used during the generation of Javadoc.

To rebuild the documentation, you must use the StyleBook tool and the JDK 1.2.2 java and javadoc tools. StyleBook (which uses Xalan and Xerces) is in stylebook-1.0-b2.jar. Some of the document definition files, stylesheets, and resources are stored in xml-site-style.tar.gz, and are unzipped when you run Ant as described below.

You can use Ant with the docs target to regenerate the User's Guide and with the javadocs target to regenerate the Javadoc API documentation. For more information, see Using Ant.

If you want to rebuild the documentation without using Ant, keep the following in mind:

  • Unzip xml-site-style.tar.gz into the xdocs directory (the operation places files in a number of subdirectories).

  • Be sure stylebook-1.0-b2.jar, xalanjdoc.jar, xalan.jar, bsf.jar, bsfengines.jar, and xerces.jar are on the class path.

  • To build doc in a build/docs subdirectory, run StyleBook from the xdocs directory as follows:

    java org.apache.stylebook.StyleBook "targetDirectory=../build/docs/" sources/xalanLocal.xml style

  • To build the HTML source files that javadoc needs for the TrAX top-level and package-level documentation, add a build/docs/apdidocs/javax/xml/transform directory and run the Xalan command-line utility from the xdocs directory as follows (all one line):

    java org.apache.xalan.xslt.Process -in sources/trax/trax.xml -param package-root '../../../src/' -xsl style/stylesheets/spec.xsl -out build/docs/apidocs/javax/xml/transform/trax.html

  • Before you run javadoc, make sure the following directory structure exists under the Xalan root directory: build/docs/apidocs.

  • To build the API documentation, run the JDK 1.2.2 javadoc tool from the xdocs directory (all one line):

    javadoc -doclet xalanjdoc.Standard -docletpath ../bin/xalanjdoc.jar -private -overview ../src/javadocOverview.html -sourcepath ../src -group TrAX "javax.xml.transform*" -group Xalan_Core "org.apache.xalan.processor: org.apache.xalan.templates: org.apache.xalan.transformer" -group XPath "org.apache.xpath*" -group Utilities "org.apache.xml.utils*" -group Xalan_Other "org.apache.xalan.client: org.apache.xalan.dtm: org.apache.xalan.extensions:org.apache.xalan.res: org.apache.xalan.stree:org.apache.xalan.trace: org.apache.xalan.xslt" -group Xalan_Extensions "org.apache.xalan.lib*" -group Serializers "org.apache.xalan.serialize" org.apache.xalan.client org.apache.xalan.dtm org.apache.xalan.extensions org.apache.xalan.lib org.apache.xalan.lib.sql org.apache.xalan.processor org.apache.xalan.res org.apache.xalan.stree org.apache.xalan.templates org.apache.xalan.trace org.apache.xalan.transformer org.apache.xalan.xslt org.apache.xpath org.apache.xpath.axes org.apache.xpath.compiler org.apache.xpath.functions org.apache.xpath.objects org.apache.xpath.operations org.apache.xpath.patterns org.apache.xpath.res org.apache.xalan.serialize javax.xml.transform javax.xml.transform.dom javax.xml.transform.sax javax.xml.transform.stream javax.xml.parsers -d ../build/docs/apidocs -windowtitle "Xalan-Java 2" -doctitle "Xalan-Java 2" -bottom "Copyright © 2000 Apache XML Project. All Rights Reserved."


Getting in Touch
 

Your feedback is more than welcome. Offers of help are even more so! Perhaps you would like to take on an active role in the ongoing development, testing, and documentation of Xalan-Java?

Please email your comments, questions, suggestions, and offers to join the Xalan team to Xalan Development Mailing List.


Cumulative history of software changes
 

The following sections list the changes in each release since Xalan-Java version 2.0.D01.

Changes for Xalan-Java version 2.0.D07
 

Xalan-Java 2.0.D07 incorporates a Xalan-Java 1 compatibility jar, some performance enhancements, and a number of bug fixes for bugs found in version 2.0.D06.

  • Fixed handling of disable-output-escaping="no". Previously, once it was turned on, it could not be turned off.

  • Fixed a bug with whitespace handling where Xalan was incorrectly checking for whitespace stripping before collation of multiple whitespace events into a single text node.

  • Whitespace stripping wasn't working with input DOMs before. This is now fixed.

  • Fixed many exception handling problems and problems with error reporting.

  • Fixed a bug resetting parameters in Transformer clearParameters().

  • Fixed a bug where CDATA sections were not matching the text() node test.

  • Made better memory allocation problem with result tree fragments.

  • Made result tree fragment parsing of numbers consistent with strings.

  • Exceptions thrown from extensions should now be properly reported via the error listener.

  • Fixed hard-coded stack dump set off by m_reportInPostExceptionFromThread variable.

  • Fixed intermittent threading problem with text nodes being dropped.

  • Fixed problem with variable evaluation inside of union expressions.

Changes for Xalan-Java version 2.0.D06
 

We have fixed the bugs reported in Xalan-Java 2.0.D05. Along with several other enhancements, we have also fixed a number of bugs found by testing and our users:

  • Fixed some threading problems and improved support for handling Exceptions thrown in a secondary thread.

    Note: To support incremental output, Xalan-Java performs the transformation in a second thread while building the source tree in the main thread.

  • Fixed problems encountered in piping (utilizing transformation output as input for another transformation).

  • Fixed problems handling attributes and adding attributes to result tree.

  • Added defensive checking for null entities, null namespaces, and empty strings passed in for URIs and local names.

  • We now conform to the SAX convention of representing null namespaces with empty strings.

  • Fixed a bug encountered evaluating a variable in a predicate expression applied to child nodes.

  • Changed names of serializers from FormatterToXxx to SerializerToXxx. See Package org.apache.xalan.serialize.

  • Improved debugging support in a number of areas.

Changes for Xalan-Java version 2.0.D05
 

All of the bugs reported in Xalan-Java 2.0.D01 have been fixed. The remainder of this section discusses two changes that we believe are of particular importance:

TrAX

The Transformation API for XML (TrAX) that Xalan-Java 2 implements has undergone substantial revisions since the release of Xalan-Java 2.0.D01. TrAX has joined the Java API for XML Parsing (JAXP) as part of the Sun® Java Specification Request 63. Accordingly, the TrAX package names have changed. The conceptual organization has also changed somewhat: The primary transformation interfaces are defined in javax.xml.transform, with concrete classes for managing stream input/output, SAX parsers and ContentHandler, and DOM parsers and DOM trees in javax.xml.transform.stream, javax.xml.transform.sax, and javax.xml.transform.dom. For more information, see TRaX (Transformation API for XML), and review Usage Patterns.

Output properties

The handling of xsl:output properties has changed: org.apache.xalan.serialize.OutputFormat and apache.xalan.templates.OutputFormatExtended were removed and replaced with org.apache.xalan.templates.OutputProperties. The SerializerFactory getSerializer() method now takes Properties rather than a String indicating the output method. You can replace getSerializer("xml"), for example, with getSerializer(OutputProperties.getDefaultMethodProperties("xml")).

HTML, XML, and text xsl:output properties are specified in property files in org.apache.xalan.templates: output_html.properties, output_xml.properties, and output_text.properties.

You can start using the output properties defined in these files in your stylesheets. For example, you can turn URL escaping off in HTML output with
{http\u003a//xml.apache.org/xslt}use-url-escaping=no
and you can control indenting with
{http\u003a//xml.apache.org/xslt}indent-amount=n

NoteThe colon after the "http" protocol must be escaped.

Character-to-entity mapping is specified in org.apache.xalan.serialize: HTMLEntities.res and XMLEntities.res. You can override entity ref mapping from a stylesheet. For example:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
         xmlns:xalan="http://xml.apache.org/xslt" version="1.0">

  <xsl:output xalan:entities="myentities.ent"/>

  <xsl:template match="/">
    <out>&#125;</out>
  </xsl:template>

</xsl:stylesheet>

=== myentities.ent ===

quot 34
amp 38
lt 60
gt 62
lala 125

The output is:

<?xml version="1.0" encoding="UTF-8"?>
<out>&lala;</out>

See also Setting output properties in your stylesheets.




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