Xalan-Java version 1.2

- Status
- Build Notes
- Getting in touch
- History of software changes

| Status |

- Changes since version 1.2.D02
- Open bugs and bug reporting
- Version of Xerces to use
- To-do tasks for future Xalan-Java releases

| Changes since Xalan-Java version 1.2.D02 |

We have applied a number of enhancements and bug fixes, including patches submitted by developers to Xalan Development Mailing List. If you run across a problem with Xalan-Java, we strongly encourage you to write a patch and submit it to us. We will review it to make sure it doesn't break something else, and (assuming it doesn't) include it in our next release. In the interest of fixing bugs, adding enhancements, and addressing a host of thorny design issues, we sincerely want (and need!) your active participation in the ongoing development of Xalan.

- Xalan-Java now suports UTF-16 output encoding.
- We incorporated an updated BSF (support for extension elements and functions) that supports Mozilla Rhino js.jar 1.5. The new bsf.jar replaces the older bsf.jar and bsfengines.jar. If you are using Javascript extensions, you must now use js.jar 1.5. Mozilla Rhino 1.4 R3 is no longer supported.
- Costin Manolache submitted a patch that isolates all BSF-dependent code in org.apache.xalan.xpath.XSLTJavaClassEngine.
- We have added a custom processing instruction that you can use to instruct the Xalan-Java processor not to cache an XML document.
  To use this processing instruction, declare the following namespace in the stylesheet element:
  `xmlns:xalan="http://xml.apache.org/xslt"`
  and include the following processing instruction in an xsl:for-each loop or xsl:templates-apply where you are using the document() function to read external documents:
  `<?xalan:doc-cache-off?>`
- Costin Manolache submitted a new parser liaison class (org.apache.xalan.xpath.xml.JaxpLiaison) and patches to a number of existing classes so that you should be able to use Xalan-Java with any XML parser that implements Java API for XML Parsing.
- We modified SimpleNodeLocator to fix a problem matching [predicate]/node patterns.
- We modified ElemNumber.java to make accessing the Xalan resource bundle thread safe.
- We have improved the performance of keys by no longer allowing <xsl:key> elements to use key() functions in the match or use attribute.
- Gary Peskin submitted a patch that fixes step pattern root matches.
- We fixed org.apache.xalan.xslt.TemplateList to match wildcard patterns.
- Xalan now correctly observes import precedence when it evaluates a variable declared and set in more than one stylesheet.

| Open bugs and bug reporting |

Open bugs:

- When format-number() should format NaN or infinity, it generates the wrong string if default strings are used. Workaround: declare the strings in an xsl:decimal-format instruction at the top of the stylesheet.
- A "not serializable exception" occurs when you attempt to run a precompiled stylesheet that expects parameter values to be passed in. If you encounter this problem, you should forego the use of precompiled stylesheets until a fix is available.
- The namespace::* axis only selects namespaces that were declared locally on the context node. Inherited namespaces are in effect; the only known flaw is the lack of their presence on this rarely-used axis. The name() function, when applied to a namespace node, returns a string that disagrees with other processors, and the XPath spec is vague on this point.
- Implied HTML output (the output begins with <HTML>, but the output method has not been explicitly set to HTML) is not thread-safe, due to a "late" change of output method. Workaround: put an explicit <xsl:output method="html".../> declaration in the stylesheet.
- In some cases, exclude-result-prefixes takes effect even when the specified prefix appears in sub-elements, causing output of unresolved prefixes. If you experience this, please adjust your exclude-result-prefixes attribute.
- The id() function doesn't work in some complex match patterns.
- If you specify HTML output and encoding via xsl:output, and if a <HEAD> element is generated, then the encoding should be represented in a <META> tag inside the <HEAD> element. We do not put out the META tag nor any representation of the encoding in this case.
- If you are generating processing instructions (PIs) in XML output, and you attempt to insert a literal "?>" in it, the spec says that "? >" should be generated, inserting a space to prevent interpretation as the end of the PI. We do not take this special step, so "?>" is generated.
- When outputting URI attributes in HTML, almost all "control" characters below decimal 32 will cause an error to be raised, rather than silently being discarded. Most characters above decimal 127 will be output as that character. Percent should be output as %25 at all times (it is currently output as a literal percent); this will be fixed later.
- Need to verify which HTML element attributes should be treated as URIs.
- The setDiagnosticsOutput() method does not cause redirection of all the diagnostics that should be affected.
- If the use of an attribute value template for output (for example, attrib="{@title}") generates incorrect characters above decimal 127, try using the "long form" instead (for example, <xsl:attribute name="attrib" select="@title"/>).
- When using document() with two arguments, the second attempting to (re-)establish the base in the input document, the form document(x,/) may raise an error. Workaround: Use document(x,/doc) where doc is the outermost element of the input document.
- Attribute sets and document() references in imported stylesheets should be global, but are not.
- A variable can be declared with a qualified name(for example, my:var), but later attempts to reference it (for example, $my:var) may crash

Bug reports that we have not yet confirmed:

- We have a report that passing a long string value (somewhere over 128 characters) to a template via with-param caused an overflow problem under Solaris with a Sun JDK. We have not seen the problem under Sun's JDKs (1.1.8 and 1.2.2) on Win32. Additional reports are welcome.
- We have a report that external entities can affect xsl:copy in a DOM input scenario. An external entity that had no attributes was causing improper copying, and adding an attribute fixed the problem. To date we have been unable to create the bug situation in our lab.

The Apache XML Bug Tracking System is currently not working. If you find a bug, please report it (with "Xalan-J 1 bug" in the subject line) to the Xalan Development Mailing List.

| Version of Xerces to use |

The Xalan-Java version 1.2 has been tested with Xerces-Java version 1.2. The Xalan-Java version 1.2 download from xml.apache.org includes xerces.jar from Xerces-Java version 1.2. 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.

| You can use Xalan with other XML parsers, but it is up to you to implement liaisons to those parsers. Your liaison class should extend XMLParserLiaisonDefault class and implement XMLParserLiaison interface.

| To-do tasks for future Xalan-Java releases |

The Xalan-Java team is hard at work on Xalan-Java version 2.0, which represents a major redesign of the Xalan XSLT Processor. The main goals of this redesign are as follows:

1. Provide ease of access and usability of Xalan-Java, and encourage greater participation from the open source community in the ongoing design and development process
2. Reduce code size and complexity
3. Improve performance and simplify optimization.
4. Produce more localized, less-intertangled modules
5. Begin the adoption of the TRaX (Transformations for XML) interfaces
6. Take advantage of the SAX 2 and DOM level 2 packages

For an overview of the 2.0 design, see Xalan-J 2.0 Design. The source tree (still pre-alpha) is in the Apache CVS Repository: xml-xalan/java/src. Pre-alpha Xalan-J 2.0 Javadoc is also periodically updated on the xml.apache.org Website.

As part of the xml.apache team, members of the Xalan-Java team are also exploring options to upgrade the integration of all the xml.apache projects, including Xalan, Xerces, Cocoon, and FOP.

The more individuals who join in the design, development, testing, documentation, and use of Xalan-Java the better for us all in the xml.apache.org open source community! Watch the Xalan Development Mailing List for more information and for ideas about how you can get involved.

| Build Notes |

- Using Ant
- Rebuilding xalan.jar
- Rebuilding sample applications
- Rebuilding the Xalan-Java documentation

| 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 root directory along with a cross-platform XML build file (build.xml), 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.

| We now use Ant to build the distribution copy of Xalan-Java.

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 (bmild.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-J in build/classes.
jar | creates xalan.jar in the build directory (the default)
samples | compiles and jars the sample apps
docs | creates the HTML User's Guide in build/docs
javadocs | generates the API documentation in ./build/docs/apidocs
dist | creates a complete distribution in xalan-j_x_y_z
site | creates the website documentation tree in xml-site/target/xalan
clean | purges the build, distribution, and site trees, and removes any document files placed in the source tree for doc and Javadoc builds

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

Other build tools

The distribution also includes makefiles that you can use with the GNU development tools. And of course you can also use the underlying utilities to compile source files, create JAR files, generate Javadoc, and generate the HTML User's Guide. One utility that you may not be familiar with is org.apache.stylebook.StyleBook (in stylebook-1.0-b2.jar), a tool from the xml-stylebook module that we use along with Xalan and Xerces to help generate the documentation. For the details, you can inspect the makefiles.

| 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.

To use GNU development tools, do the following:

1. Set up GNU or the equivalent build environment on your workstation.
   If you are running Windows 95/98/2000/NT, you can use the Cygwin port of GNU. Be sure to put the appropriate Cygwin bin directory at the beginning of your system path. For information about Cygwin, see Cygwin.
2. Place Xerces-Java version 1.2 xerces.jar in the Java class path.
3. If you are working in Windows, set MAKE_MODE as follows:
   `set MAKE_MODE=UNIX`
4. Run the make file in the Xalan-Java root directory:
   `make build`

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

- Set the class path 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 class path. To recompile (and run!) the class files in the Servlet subdirectory, the javax.servlet and javax.servlet.http packages must also be on the class path. 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.

| To 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 the make files as described below. If the JDK 1.2.2 bin and lib directories are not on your class path, you can edit the make.include file in the Xalan root directory so the make file can find the JDK 1.2.2 java and javadoc tools. You can also include java and javadoc arguments on the make file command line. See the make.include file for the details.

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.

To generate the Xalan HTML User's Guide with the GNU development tools, run the Xalan make file in the Xalan xdocs directory:
`make makesbook`

To generate the Xalan API documentation with GNU, set up the make file to use the Javadoc tool in the Java JDK 1.2.2 bin directory.

Do the following:

1. Put the Java JDK 1.2.2 bin directory on your path (in front of any JDK 1.1.x bin directory that appears on the path).
2. In the Xalan docs directory, run the Xalan make file as follows:
   `make makejavadoc`

If you want to rebuild the documentation without using Ant or the GNU build environment, 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 top-level and package-level documentation, run StyleBook from the xdocs directory as follows:
  `java org.apache.stylebook.StyleBook "loaderConfig=sbk:/style/loaderjdoc.xml" targetDirectory=../src sources/javadocPackages.xml style`
- 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:
  `-doclet xalanjdoc.Standard -public -overview ../src/javadocOverview.html -sourcepath ../src -group XSLT_Packages "org.apache.xalan.xslt*" -group XPath_Packages "org.apache.xalan.xpath*" org.apache.xalan.xpath org.apache.xalan.xpath.xdom org.apache.xalan.xpath.dtm org.apache.xalan.xpath.xml org.apache.xalan.xslt org.apache.xalan.xslt.trace org.apache.xalan.xslt.client org.apache.xalan.xslt.extensions -windowtitle Xalan -d ../build/docs/apidocs`

| 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 |

| We started tracking the changes in earlier releases beginning with Xalan-Java version 1.1.

| Changes for Xalan-Java version 1.2.D02 |

We applied the following bug fixes

- The Xalan DTM (Document Table Model) was splitting text nodes containing entity references into multiple nodes. We have fixed this problem, and Xalan now treats the node as a single text node.
- Norm Walsh submitted patches enabling Xalan to accept URI substitutions set by a custom EntityResolver.
- Gary Peskin submitted a patch enabling Xalan to process expressions with path steps following a union. As a result, Xalan can now transform documents of the DocBook document type.
- We now encode characters above 127 in URI attributes (in some cases "garbage" characters were appearing). We are still soliciting input on how to handle special URI characters between 32 and 127.
- The use of position() in sort expressions now works as expected, which makes it easy to reverse node order.
- If a sort with the primary sort key fails completely, we no longer perform a sort with the secondary key.
- Sergei Ivanov submitted a patch to avoid including a minus sign in an ID in the rare case when a negative number was appearing in the ID.
- We believe we have fixed XPath retrieval of attributes qualified with a namespace prefix. Other namespace fixes enable the name() and namespace-uri() functions to be applied to namespace nodes.
- Ed Staub submitted a patch so that a message about processing instruction names now appears as a warning rather than an error.
- A thread-safety issue in pattern matching was identified and fixed.
- The output of very small decimal fractions has been improved.
- We fixed a problem with keys that appeared when multiple threads were using xsl:key concurrently.

We also updated the build process (Ant and Make) to avoid creating a copy of the source tree, and we placed the Ant tool in a new bin directory.

| Changes for Xalan-Java version 1.2.D01 |

We applied patches submitted by a number of developers to Xalan Development Mailing List.

- Patch submitted by Sergei S. Ivanov: Fixed XNumber.java so that the string function does not apply the current locale setting when formatting numbers. In other words, the locale setting will not override the format applied in the string function.
- Patch submitted by Bernd Köcke: Fixed FormatterToDOM.java and StylesheetRoot.java so can transform a DOM beginning with an Element-node or DocumentFragment-Node.
- Patch to SimpleNodeLocator.java submitted by Gary Peskin: Fixes the problem with complex XPath expressions including steps after a union that were raising an access error and not returning the correct node-set.
- Patch to XMLParserLiaisonDefault.java submitted by Bernd Köcke: Changed ProblemListener variable to non-static, so users working in a multithreaded environment can can log errors from multiple ProblemListeners.
- Patch to FuncFormatNumb submitted by Dimitry Voytenko: Supplied missing curly braces in an else clause.
- Patch to XPath.java submitted by Naohiko Uramoto: Increased MAXTOKENQUEUSIZE from 500 to 2000 to support longer XPath expressions.
- Patches to XObject.java, XBoolean.java, XNodeSet.java, XNull.java, XNumber.java, XtreeFrag.java, and XString.java submitted by Gary L. Peskin: GetTypeString() method changed from private to protected, so that it returns an appropriate message for each node type.
- Some updates to XNumber to attempt to address formatting issues with jview.
- We have not included other patches that we consider too risky or that we think should be addressed in the scope of Xalan-Java version 2.0.

| Changes for Xalan-Java version 1.1 |

- Updates to stay in synch with Xerces-Java
- Bug fixes
- URI attributes in HTML output
- Ant

| Updates to stay in synch with Xerces-Java |

Xerces-Java version 1.0.4 introduced some API changes that caused problems for Xalan-Java version 1.0.1. The two teams collaborated to bring Xalan-Java and Xerces-Java back into synch with Xalan-Java version 1.1.D01 (a Developer's release) and Xerces-Java version 1.1.1.

Xerces-Java version 1.2 replaced java.net.URL with a new URI class to resolve system IDs for external entities. As a result, Xerces-Java no longer accepts OS file path names for URIs. If, for example you used "c:\foo\bar.xml" to designate a URI in an earlier release of Xerces-Java, you must now use "file:///c:/foo/bar.xml".

We have updated the command-line utility (org.apache.xalan.xslt.Process) so that it will continue to accept file path names.

When you use the API to instantiate an XSLTInputSource object, you must use the correct String designation for the URI. For example:
`XSLTInputSource =`
`new XSLTInputSource("file:///c:/foo/bar.xml");`

If you really want you use a file name, you must do something along the lines of the following code fragment:

    import java.net.URL;
    import org.apache.xalan.xslt.*;
    ...
    // Must escape "\" character.
    String fileName="c:\\foo\\bar.xml";

    // Create a URL object and use it to generate
    // a string in the correct URI format.
    URL url = new URL(fileName);
    String urlIn = url.toExternalForm();

    // Now have the correct string for an XSLTInputSource object.
    XSLTInputSource = new XSLTInputSource(urlIn);
    ...

| This change has no effect on the creation of an XSLTOutput object. You can still use a file name. You may also continue to use a file name with the XSLTProcessor setStylesheet() method.

| Bug fixes |

We have also addressed several bugs found in Xalan-Java version 1.0.1:

- A function or variable reference on the left-hand-side of a union was sometimes incorrectly evaluated. This has been fixed. The fix, however, introduces a new bug that we have not yet fixed: complex XPath expressions including steps after a union raise an unknown access error and do not return the correct node-set.
- Numbered entity references were sometimes output in hexadecimal, not decimal. Numbered entity references are now always output in decimal.
- Xalan-Java was not using the xsl:output standalone attribute to place document standalone declarations in the output. If the standalone attribute is set to "yes", Xalan-Java now includes a standalone document declaration in the output. If the standalone attribute is set to "no", Xalan-Java does not place a standalone document declaration in the output.
- xsl:key declarations in imported stylesheets did not work. This has been fixed.
- When the key() function encountered an attribute set to a null string, key() ignored all subsequent nodes. This has been fixed.
- The local-name function now returns the correct string for text and comment nodes.
- We fixed a namespace resolution problem in the XPathAPI eval() method. XPathAPI provides an API for executing XPath expressions and is included with the ApplyXPath sample application.

| URI attributes in HTML output |

In response to requests, we have added a boolean SpecialEscapeURLs property to FormatterToHTML and changed the way we output certain characters in URI attributes (such as HREF) when the output method is HTML.

What we did in version 1.0.1: Non-ASCII characters, space, and double quote("), were output as `%hh`, where `hh` is the hex value of the character. Ampersand (&) was output literally.

What we do by default in version 1.1 (the SpecialEscapeURLs is set to false): Non-ASCII characters are output as `&#nnn`, where `nnn` is the decimal value of the character, and HTML special characters are output as `&xyz;`, where `xyz` is the named entity for this character (such as &quot; for "). Space is output as a literal space.

What we do in version 1.1 if you set the FormatterToHTML SpecialEscapeURLs property to true: Non-ASCII characters and space are output as `%hh`, where `hh`is the hex value of the character, and double quote is output as `&quot;` (instead of `%22`). Ampersand is output as a literal ampersand.

Given our reading of the XSLT and HTML specs, we are not sure this is appropriate output to support, so we are soliciting feedback from the XSL community.

Here is code fragment indicating one technique for setting SpecialEscapeURLs to true.

    // Manually set up a FormatterToHTML
    OutputFormat format = new OutputFormat( "html", "UTF-8", false );
    org.apache.xalan.xpath.xml.FormatterToHTML formatter =
                                          new FormatterToHTML();
    formatter.init(writer, format);

    // New! Turn on the new special HTML URL attr escaping
    formatter.setSpecialEscapeURLs(true);

    // Perform the process, using the Formatter as a target
    processor.process(new XSLTInputSource(xmlName),
                      new XSLTInputSource(xslName),
                      new XSLTResultTarget(formatter));

| Ant |

| We have upgraded support for using Apache Ant to build Xalan-Java. For the details, see Using Ant.

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