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

Credits
XSLTC Credits

Xalan-Java version 2.3.1

Status
 
Changes since Xalan-Java 2.2
 

Global updates:

  • This release is integrated with release 2 of Xerces-Java.
  • This release does not include support for the deprecated Xalan-Java 1 compatability API. The Xalan-Java 1 compatability code does NOT compile with Xerces-Java 2.

Our SQL extension samples continue to use InstantDB, but based on our realization of changes that have occurred in the licensing of InstantDB, we no longer include InstantDB and the associated sample database with our distibution. We do, however, provide information on how to set up InstantDB to support our SQL extension samples.

Documentation updates: We have subdivided the release notes into multiple files to accelerate HTML document loading, and we have added a document on Transform features.

Core (Non-XSLTC) source code updates:

  • Committed by johng@apache.org on 01/17/2002
    Modified: java/src/org/apache/xalan/lib/sql XConnection.java
    Committer's log entry: Fixed second connection problem

  • Committed by johng@apache.org on 01/17/2002
    Modified: java/src/org/apache/xalan/lib/sql SQLDocument.java
    Committer's log entry: Update for new DTM Model

  • Committed by johng@apache.org on 01/17/2002
    Modified: java/src/org/apache/xalan/lib/sql DTMDocument.java
    Committer's log entry: Update for new DTM Model

  • Committed by johng@apache.org on 01/17/2002
    Modified: java/src/org/apache/xalan/lib/sql SQLDocument.java DTMDocument.java
    Committer's log entry: Removed Debug

  • Committed by jkesselm@apache.org on 01/18/2002
    Modified: java/src/org/apache/xml/utils FastStringBuffer.java
    Committer's log entry: Whups. There's a possible reentrancy problem when data is being serialized from an FSB, thru Sax, back into a new chunk of the same FSB; if the append causes a rechunking, the serialize loop may break. TEMPORARY PATCH; permanant fix to follow. See comments.

  • Committed by jkesselm@apache.org on 01/18/2002
    Modified: java/src/org/apache/xml/utils SuballocatedIntVector.java
    Committer's log entry: <blush>Wrong side of the fencepost...</blush>

  • Committed by jkesselm@apache.org on 01/23/2002
    Modified: java/src/org/apache/xalan/templates ElemTemplate.java java/src/org/apache/xalan/transformer TransformerImpl.java java/src/org/apache/xml/dtm DTMManager.java java/src/org/apache/xml/dtm/ref DTMDefaultBase.java DTMManagerDefault.java java/src/org/apache/xml/dtm/ref/sax2dtm SAX2DTM.java java/src/org/apache/xpath XPathContext.java
    Added: java/src/org/apache/xml/dtm/ref/sax2dtm SAX2RTFDTM.java
    Committer's log entry: These changes allow us to store multiple Result Tree Fragment (RTF) document trees (used when an XSLT variable contains a constructed set of nodes) into a single DTM object rather than using a new DTM for each RTF. They also permit "tail-pruning" this shared DTM to reuse that space as the variables go out of scope. The result is a slight performance improvement, and a much more significant improvement in storage efficiency. Stylesheets which use RTFs heavily should now run in much less memory; in one testcase, our "working set" heap size (storage actually in use, not counting objects released but not yet GC'd) dropped from 12-15MB down to 3-6MB, and heap churn (how quickly storage was being allocated and discarded) also reduced substantially. The code changes needed to support this new scheme are surprisingly small. And I believe it may be possible to reduce them further, if we're willing to merge the SAX2RTFDTM subclass back into its SAX2DTM superclass. I believe that could be done with very little adverse impact on other uses of SAX2DTM... but I felt it was safer to defer that decision for now.

  • Committed by mmidy@apache.org on 01/25/2002
    Modified: java/src/org/apache/xalan/transformer TransformerImpl.java
    Committer's log entry: Bug 5982 and 6022. The variable stack was not being cleared accross transforms so that when the transformer is reused, we were using nodesets from the previous transform which were using a different DTM. Note that we want keep any variables that have been set externally by the user (using Transformer.setParameter()).

  • Committed by mmidy@apache.org on 01/28/2002
    Modified: java/src/org/apache/xpath/res XPATHErrorResources.java
    Committer's log entry: bug 4762: Fixed the duplicate error message in XPATH.

  • Committed by jkesselm@apache.org on 01/28/2002
    Modified: java/src/org/apache/xalan/transformer TransformerImpl.java
    Committer's log entry: Bugzilla 4054: Retain previously set output properties when adding new ones.

  • Committed by mmidy@apache.org on 01/28/2002
    Modified: java/src/org/apache/xalan/transformer TransformerImpl.java
    Committer's log entry: Bug 5872. We were using a constructor of TranformerException without the locator information. Changed to code to use a locator if info is available.

  • Committed by dleslie@apache.org on 01/30/2002
    Modified: java/src/org/apache/xalan/lib NodeInfo.java
    Committer's log entry: Changed "system id" to "public identifier" in javadoc comments for publicId() methods.

  • Committed by jkesselm@apache.org on 01/30/2002
    Modified: java/src/org/apache/xml/dtm/ref/sax2dtm SAX2DTM.java
    Committer's log entry: Bugzilla 2617, part 1: Construct the data structures and access them correctly. Ignore too-late-to-be-safe requests to enable this feature. This doesn't resolve how to rewrite higher-level code so it makes the request early enough to be useful.

  • Committed by mmidy@apache.org on 01/30/2002
    Modified: java/src/org/apache/xalan/templates StylesheetComposed.java StylesheetRoot.java TemplateList.java java/src/org/apache/xalan/transformer TransformerImpl.java
    Committer's log entry: Bug 4987: Changed Apply-imports logic to only apply imports to stylesheets that are direct imports. The logic for includes has not changed, we will apply-imports to any stylesheet that is imported as a result of an inclusion. Note: had to change the order when includes and imports are recomposed!

  • Committed by jkesselm@apache.org on 01/31/2002
    Modified: java/src/org/apache/xalan/lib NodeInfo.java java/src/org/apache/xalan/processor TransformerFactoryImpl.java java/src/org/apache/xalan/transformer TransformerImpl.java java/src/org/apache/xalan/xslt Process.java java/src/org/apache/xml/dtm/ref DTMManagerDefault.java java/src/org/apache/xml/dtm/ref/sax2dtm SAX2DTM.java SAX2RTFDTM.java java/src/org/apache/xml/utils DefaultErrorHandler.java
    Committer's log entry: Bugzilla 2617: Recreated missing code, changed controls to ensure that this mode gets set early enough to be useful and can't be broken by being turned on and off during execution. NOTE: Current implementation relies on a global static flag in TransformerFactoryImpl. We need to rearchitect our APIs slightly so configuration hints of this kind can be passed down from top-level objects to the back-end code more elegantly. Revisit in future releases.

  • Committed by mmidy@apache.org on 01/31/2002
    Modified: java/src/org/apache/xalan/templates ElemApplyTemplates.java
    Committer's log entry: Bug 5505: Need to resolve params before we do anything else, so move code that does that above the code that sets up the different node stacks.

  • Committed by jkesselm@apache.org on 02/01/2002
    Modified: java/src/org/apache/xml/utils FastStringBuffer.java
    Committer's log entry: Bugzilla 6182. Darned fence posts; always either too many or not enough... <grin/>

  • Committed by mmidy@apache.org on 02/01/2002
    Modified: java/src/org/apache/xalan/transformer TransformerImpl.java java/src/org/apache/xpath VariableStack.java XPathContext.java
    Committer's log entry: Bug 6156: Change variable stack reset to just get a new object. Also make sure that the stack of result tree fragments is also cleaned ot during a reset.

  • Committed by mmidy@apache.org on 02/04/2002
    Modified: java/src/org/apache/xpath/objects XBoolean.java XNodeSet.java XNumber.java XObject.java XRTreeFrag.java XString.java java/src/org/apache/xpath/operations Equals.java
    Committer's log entry: Bug 5851: Make sure that the equal operation is evaluated by order of precedence of the operands, as defined by XSLT.

  • Committed by jkesselm@apache.org on 02/04/2002
    Modified: java/src/org/apache/xpath/objects XStringForFSB.java
    Committer's log entry: Bugzilla 5346: Prevent mantissa overflow when converting string to double. There is still a possible edge-case, since I detect overflow on decimal digit bounds rather than on bit bounds; I'm not sure what the IEEE spec calls for.

  • Committed by jkesselm@apache.org on 02/04/2002
    Modified: java/src/org/apache/xpath/objects XStringForFSB.java
    Committer's log entry: Bugzilla 5346: My first-cut messed up fractional values. This one is somewhat better. There's an open issue w/r/t numbers with many digits after the decimal point, regarding limits on how large a power of 10 can be contained in a long. In that one case I'm falling back on successive divisions (though as few as possible), and some loss of precision may result. Need to find a better algorithm...

  • Committed by jkesselm@apache.org on 02/04/2002
    Modified: java/src/org/apache/xpath/objects XStringForFSB.java
    Committer's log entry: Bugzilla 5346: Oops. Forgot to take out a debugging printout.

  • Committed by jkesselm@apache.org on 02/05/2002
    Modified: java/src/org/apache/xpath/objects XStringForFSB.java
    Committer's log entry: Bugzilla 5346: Responding to the re-open; more direct and reliable edge-case test. This does lose a few low bits on many-digit values, so it is not the best long-term solution.

  • Committed by jkesselm@apache.org on 02/05/2002
    Modified: java/src/org/apache/xpath/objects XStringForFSB.java
    Committer's log entry: Bug 5346: One more (last, I hope) edge case.

  • Committed by jkesselm@apache.org on 02/05/2002
    Modified: java/src/org/apache/xpath/objects XStringForFSB.java
    Committer's log entry: Bug 5346: Gaaah. This regressions was just plain foolish flailing. "Less haste, more speed."

  • Committed by jkesselm@apache.org on 02/05/2002
    Modified: java/src/org/apache/xalan/serialize CharInfo.java
    Committer's log entry: Bug 5857: Reusing objects that reuse objects has threading concerns. Three possible solutions: Don't reuse, synchronize reuse, or rewrite to avoid using the objects in the first place. See comments in code.

  • Committed by jkesselm@apache.org on 02/06/2002
    Modified: java/src/org/apache/xml/dtm/ref DTMManagerDefault.java IncrementalSAXSource.java IncrementalSAXSource_Filter.java IncrementalSAXSource_Xerces.java java/src/org/apache/xml/dtm/ref/sax2dtm SAX2DTM.java
    Committer's log entry: Bug 4244: Incremental wasn't setting up correctly for the DTDHandler stream. It never occurred to me that XSLT would ever have a use for unparsed entities...

  • Committed by curcuru@apache.org on 02/06/2002
    Modified: java/src/org/apache/xalan Version.java java/src/org/apache/xalan/processor XSLProcessorVersion.java
    Committer's log entry: Whoops! Never updated release number to 2.3 in these version files!

  • Committed by curcuru@apache.org on 02/06/2002
    Modified: java/src/org/apache/xalan/res XSLTInfo.properties
    Committer's log entry: updated version number to 2.3

  • Committed by mmidy@apache.org on 02/07/2002
    Modified: java/src/org/apache/xpath SourceTreeManager.java
    Committer's log entry: Bug 6304: Remove print stacktrace

  • Committed by jkesselm@apache.org on 02/08/2002
    Modified: java/src/org/apache/xalan/extensions XSLProcessorContext.java java/src/org/apache/xalan/lib/sql DTMDocument.java java/src/org/apache/xalan/templates ElemForEach.java FuncDocument.java FuncKey.java java/src/org/apache/xalan/transformer KeyIterator.java TransformerHandlerImpl.java TransformerImpl.java java/src/org/apache/xml/dtm DTM.java java/src/org/apache/xml/dtm/ref DTMDefaultBase.java DTMDefaultBaseIterators.java DTMDocumentImpl.java DTMNodeProxy.java java/src/org/apache/xml/dtm/ref/sax2dtm SAX2RTFDTM.java java/src/org/apache/xpath/axes IteratorPool.java
    Committer's log entry: Bugzilla 6314: Additional support changes for multiple RTFs per DTM. Many files affected, but the basic change is that dtm.getDocument() with no arguments is meaningless when there are multiple docs in a single DTM object; instead, folks should use the new getRootNode() method or getOwnerDocument(), both of which take a node as input and thus more clearly identify which document we're referring to.

  • Committed by jkesselm@apache.org on 02/12/2002
    Modified: java/src/org/apache/xml/utils FastStringBuffer.java
    Committer's log entry: Bugzilla 6328, whitespace normalization. Late fix, but it was a genuine regresion. This code could still do with a rationalization pass; I think it can be made slightly a touch faster.

  • Committed by curcuru@apache.org on 02/14/2002
    Modified: java/src/org/apache/xalan/xslt EnvironmentCheck.java
    Committer's log entry: Update various .jar sizes for recent builds and 2.3.0


Other points of interest
 
  • If an attempt is made to coerce a different namespace onto a prefix already in use in xsl:attribute, the attribute will come out in the wrong namespace. Workaround: either provide an NCName instead of a QName for the attribute, or provide a QName with a prefix not used elsewhere.

  • 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 2.0.0 does not).

  • When you traverse the namespace axis for a collection of element nodes, Xalan-Java includes one namespace node for each namespace in scope for one or more of the nodes in that collection. The XPath expression does not return additional (redundant) namespace nodes for each element for which the namespace nodes are in scope.

  • See Bugzilla bug 2291 for a discussion of issues surrounding use of the default character encoding to read META-INF/Services.

  • As Bugzilla bug 1800 reports, the Transformer does not get the setTransformState event until after the startDocument event. This could present a problem for tools developers, and we do intend to fix this bug.

Bugs
 

All known Xalan-Java bugs are listed in Bugzilla (the Apache bug database). For a list of open bugs with links to each bug report, see XalanJ2 open bugs. If you find a new bug, please enter a XalanJ2 bug report in this database.

NoteBefore you can enter your first bug report, you must submit your email address to Bugzilla and receive a password.

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.


Version of Xerces to use
 

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

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

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


Build Notes
 

We provide two distributions: a binary distribution, and a source distribution. See Downloading what you need. If you have downloaded the binary distribution, you already have a build. If you downloaded the source distribution, you can use Ant to build Xalan-Java, including xalan.jar, xalansamples.jar, xalanservlet.jar, the user documentation, and the Javadoc API documentation. You need the source distribution to do builds. Keep in mind that if you have also downloaded the binary distribution, any builds you run will overwrite that binary distribution.

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.


Building 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, xercesImpl.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, xml-apis.jar, and xercesImpl.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, xalan2jdoc.jar, xalan.jar, bsf.jar, bsfengines.jar, and xercesImpl.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 "xslt4j; 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.


Developers
 

A list of some of people currently working on working on Xalan-Java:



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