The definitive sources are the W3C XSLT and XPath recommendations: XSL Transformations (XSLT) Version 1.0 and XML Path Language (XPath) Version 1.0.

For a brief listing of tutorials, discussion forums, and other materials, see Getting up to speed with XSLT.

xalan-dev and xalan-j-users are for Xalan-Java questions only. This is not the best forum to ask general XSLT questions. The Mulberry XSL Mailing List is an excellent place to ask XSLT questions; please search XSL Frequently Asked Questions to ensure your question has not been already asked.

TrAX is the Transformation API for XML. In November 2000, TrAX was revised and incorporated into JAXP, the JAVA API for XML Processing. JAXP (including TrAX) provides users a standard, vendor-neutral API for working with (and transforming) XML documents. You can use this API to build applications that are not bound to the particular implementation details of a given XML parser or XSL transformer.

Xalan-Java includes the JAXP packages, implements the TrAX portion of that API (javax.xml.transform....), and includes xercesImpl.jar from Xerces-Java, which implements the parser portion of the API (javax.xml.parser....).

For more information, see TRaX (Transformation API for XML) and Java API for XML Processing 1.1 Public Review 2.

Using the EnvironmentCheck utility: To help diagnose classpath problems and also determine which version of Xalan-Java is being used, try running Xalan-Java's environment checking utility, checked in at xml-xalan/java/src/org/apache/xalan/xslt/EnvironmentCheck.

You can run this utility from the command line as follows:

java org.apache.xalan.xslt.EnvironmentCheck [-out outFile]

You can also call this utility from within your application. For example,

boolean environmentOK = (new EnvironmentCheck()).checkEnvironment (yourPrintWriter);

Be sure to run EnvironmentCheck in the environment where you are experiencing the problem. For example, if you get a NoClassDefFound error from a command-line application, run EnvironmentCheck on the command line with exactly the same classpath. If the error occurs inside your Java application (or in a servlet, etc.), be sure to call the EnvironmentCheck checkEnvironment(...) method from within your running application.

Best of all, you can call checkEnvironment from a stylesheet using extensions:

	<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:xalan="http://xml.apache.org/xalan" exclude-result-prefixes="xalan"> <xsl:output indent="yes"/> <xsl:template match="/"> <out> <xsl:copy-of select="xalan:checkEnvironment()"/> </out> </xsl:template> </xsl:stylesheet>

Xalan-Java version 2.4.1 has been tested with Xerces-Java 2.2.0. See Status.

The Xalan-Java 1 compatibility API has been deprecated and now purged, so you must use the Xalan-Java 2 API. We strongly encourage you to use the JAVAX 1.1/TrAX API. For more information ,see the next FAQ.

The JDK 1.3 automatically places everything in the lib/ext directory in front of everything you place on the classpath. If this directory contains a version of DOM, JAXP, or Xerces that predates the Xalan-Java distribution you are using, you may have problems!

The IBM JDK 1.3 includes an earlier version of xerces.jar in the lib/ext directory, a version that does not implement the JAXP 1.1 interfaces and therefore does not work with the current Xalan-Java release. Accordingly, you must either purge the xerces.jar that is in that directory or replace it with the xercesImpl.jar that is included with the Xalan-Java distribution.

The SUN JDK 1.3 includes a pre-1.1 version of the JAXP in crimson.jar. Either purge the crimson.jar in that directory or overwrite it with a newer crimson.jar that includes and implements the JAXP 1.1 interfaces.

The Sun JDK 1.4 is packaged with an old version (2.2D11) of Xalan-Java. The JDK 1.4 will attempt to use this version instead of any on the classpath. Unfortunately, this causes problems when attempting to use a newer version of Xalan-Java with the Sun JDK 1.4.

You can always determine which version of Xalan-Java you are running by using the EnvironmentCheck class or by using the xalan:checkEnvironment extension function. It is highly recommended that you use this method to verify the version of Xalan-Java you are running, especially before opening a bug report.

There are several ways to use a later version of Xalan-Java and override the one packaged with the JDK:

• For the SUN JDK 1.4, use the Endorsed Standards Override Mechanism. Place the xalan.jar, xercesImpl.jar, and xml-apis.jar in the <java-home>\lib\endorsed directory, where <java-home> is where the runtime software is installed.
• Use the -Xbootclasspath java commandline option to prepend the new xalan.jar, xercesImpl.jar, and xml-apis.jar to the boot class path. When running Xalan:
  
  java -Xbootclasspath/p:<path> java.org.apache.xalan.xslt.Process
  
  where <path> is a colon seperated lists of the paths to the files xalan.jar, xercesImpl.jar, and xml-apis.jar (e.g. bin/xalan.jar:bin/xercesImpl.jar:bin/xml-apis.jar) containing the new-version of Xalan-Java.

The following methods do not work:

• Using the CLASSPATH environment variable or using -classpath to place the new classes in the classpath.
• Using the -jar option to explicitly execute the classes inside the new jar files.

For each Xalan-Java download file in xalan-j distribution directory, there is a corresponding signature file. The signature file for xalan-j_2_0_1.tar.gz, for example, is xalan-j_2_0_1.tar.gz.sig.

The .sig files are PGP signatures of the actual .zip or .tar.gz download files. You can use these files to verify the authenticiy of the download. You do not need the .sig file to use the corresponding donwload file.

To check the authenticity of a Xalan-Java distribution, you need a copy of PGP which is available in a number of licenses, including some free non-commercial licenses, either from an mit.edu site or on the pgp.com site. Once you have a version of PGP installed, you should be able to 'verify the signature' of the .sig file, which basically verifies that the corresponding .zip or tar.gz file has not been changed since we signed it.

In the ongoing development of Xalan-Java, enhancing performance is the primary goal of the Xalan-Java team. Here are some preliminary suggestions for you to keep in mind as you set up your applications:

• Use a Templates object (with a different Transformers for each transformation) to perform multiple transformations with the same set of stylesheet instructions (see Multithreading).
  
  
• Set up your stylesheets to function efficiently.
  
  
• Don't use "//" (descendant axes) patterns near the root of a large document.
  
  
• Use xsl:key elements and the key() function as an efficient way to retrieve node sets.
  
  
• Where possible, use pattern matching rather than xsl:if or xsl:when statements.
  
  
• xsl:for-each is fast because it does not require pattern matching.
  
  
• Keep in mind that xsl:sort prevents incremental processing.
  
  
• When you create variables,
  <xsl:variable name="fooElem" select="foo"/>
  is usually faster than
  <xsl:variable name="fooElem"><xsl:value-of-select="foo"/></xsl:variable>
  
  
• Be careful using the last() function.
  
  
• The use of index predicates within match patterns can be expensive.
  
  
• Decoding and encoding is expensive.
  
  
• For the ultimate in server-side scalability, perform transform operations on the client. For examples, see appletXMLtoHTML and get-todo-list.

If you are looking for nodes in a namespace, the XPath expression must include a namespace prefix that you have mapped to the namespace with an xmlns declaration. If you have declared a default namespace, it does not have a prefix (see XPath Node Tests). In order to construct XPath expressions to retrieve nodes from this namespace, you must add a namespace declaration that provides a prefix you can include in the XPath expressions.

Suppose, for example, you you want to locate nodes in a default namespace declared as follows:
xmlns="http://my-namespace"

Add a nampespace declaration with a prefix:
xmlns:foo="http://my-namespace"

Then you can use foo: in your XPath expression.

Hint: Don't use default namespaces, and the problem doesn't arise.

If you use a TransformerFactory to process a stylesheet Source and generate a Transformer, the TransformerFactory instructs the SAXParserFactory to set the parser's namespaceAware property to true. But if you call the parser directly, you may need to set the namespaceAware property yourself. For example:

	javax.xml.parsers.SAXParserFactory spFactory = javax.xml.parsers.SAXParserFactory.newInstance(); spFactory.setNamespaceAware(true);

For more information about setting the namespaceAware property, and SAX2 vs. JAXP default settings, see JAXP FAQ: Warning about namespace processing defaults.

1. xalan.jar, xml-apis.jar, and xercesImpl.jar -- or the XML parser you are using -- must always be on the classpath.
   
   
2. To run the samples in the samples subdirectories, xalansamples.jar must be on the classpath. To run the servlet (in samples/servlet), xalanservlet.jar must be on the classpath along with the javax.servlet and javax.servlet.http packages. Sun distributes the javax.servlet packages in the JSWDK servlet.jar file.
   
   
3. To run extensions which use the component and script extension elements (including the samples in samples/extensions), bsf.jar must be on the classpath. To run extensions implemented in JavaScript, js.jar must also be on the classpath. For information on what you need to run extensions implemented in other scripting languages, see Supported languages.

For more information, see Setting up the system classpath.

This error occurs when Xalan-Java tries to add a Node to a Document node where it isn't allowed. For example, attempting to add non-whitespace text to the DOM Document node produces this error.

The error can also occur when a Document node is created with the DOMImplementation createDocument() method, which takes a qualified name as an argument and creates an element node. If you then pass the returned Document node to Xalan-Java, you get a "DOM006 Hierarchy request error" when Xalan-Java tries to add a second element to the Document node. The solution is to either use the DocumentBuilder newDocument() method to create a Document that does not contain an element node, or use a DocumentFragment. It should be noted that the DocumentBuilder newDocument() method is "Non-preferred" according to the JAXP 1.1 documentation.

We have seen this probem arise for two quite different reasons:

• SAX1 interfaces are on your classpath in front of the SAX2 interfaces provided with your XML parser.
  
  or
  
  
• The parser you are using to process a stylesheet Source and generate a Transformer does not have the namespaceAware property set to true.

SAX1 on the classpath

SAX1 should not be on your classpath. The SAX1 interfaces and implementations of the SAX1 SAXPparser are not namespace aware.

To help diagnose your classpath, you can use the EnvironmentCheck utility. If you are running under JDK 1.3, see Issues running Xalan-Java on JDK 1.3. If you are running a servlet, make sure the servlet engine is not placing SAX1 on the classpath.

When you create a Transformer, you must use a namespace-aware parser to parse the stylesheet.

There are two common causes for this error.

1. Using the wrong URI for the xsl: prefix will cause this message. URIs, and namespace URIs in particular, are case sensitive. Ensure the URI for the xsl namespace is "http://www.w3.org/1999/XSL/Transform".
2. The parser you are using to process a stylesheet Source and generate a Transformer does not have the namespaceAware property set to true.
   When you create a Transformer, you must use a namespace-aware parser to parse the stylesheet.

That may not be our fault. As of JDK 1.3.x, many Java Virtual Machine publishers reduced the default size of a thread's call stack from 1MB to 256KB. This allows more threads to run simultaneously, but it means that each thread is more limited in how deeply its function calls can be nested.

Some JVMs may offer an option that allows you to raise this limit. For example, in Sun JDK 1.3.1 you can start JVM with the -Xss1m option to allow each thread to use a full megabyte. In IBM's JDK you can start with the -Xss1m and -Xoss1m options. Other JVMs may set this in other ways, or may not allow you to control it at all; check the documentation on your system for details.

Note too that on some platforms 1MB is an architectural upper limit on the stack size, so setting -Xss2m (or equivalent) may not allow deeper recusion than -Xss1m.

As a general rule, Xalan-Java currently caches all of the documents that you read in with the document() function during a transformation.

If your objective is to transform a series of documents, you can break the process into a series of transformations. The PipeDocument extension element provides one strategy for batching a series of parallel transformations.

Another alternative is to place your document() call in the select attribute of an xsl:for-each instruction element and use a custom PI (Processing Instruction) to turn off document caching. Include an XPath expression in your document() call if you do not need to process the entire document.

Sample stylesheet fragment:

	<xsl:template match="doc"> <xsl:for-each select="document(@href)/bar/zulu"> <?xalan:doc-cache-off?> <!-- process each document --> <xsl:for-each> </xsl:template>

PIs do not ordinarily uses namespaces, so "xalan:" is a 'fake' namespace we have included to indicate that this is not a standard PI.

If you include an XPath expression in your document() call, you can also turn on incremental transform to eliminate the need to read in the entire document. In fact, you can take advantage of the incremental transform feature even if you are not turning off document caching.

You can also increase your jvm heap size with the -Xmx or -mx flag, depending on which JVM you are using (you can include both flags, and the JVM will ignore the one it doesn't understand). For example, to give your JVM 64 meg, try
java -Xmx64m -mx64m Class

Xalan often requires legal URLs as system identifiers, not local pathnames (this is partly due to underlying parsers requiring this). A simple (but not always correct!) way to change a local pathname into a URL in Java 1.1x is:

	public static String filenameToURL(String filename) { File f = new File(filename); String tmp = f.getAbsolutePath(); if (File.separatorChar == '\\') { tmp = tmp.replace('\\', '/'); } // Note: gives incorrect results when filename already begins with file:/// return "file:///" + tmp; }

For a slightly more detailed example, see org.apache.xml.utils.SystemIDResolver.

Xalan-Java supports two strategies for chaining together a series of transformations such that the output of each transformation provides input for the next transformation.

• For each transformation in the series, you can set one SAX ContentHandler to process the input, and another ContenHandler to process the output.
  
  
• You can also set up a series of parent-child relationships between an XMLReader and one or more XMLFilters.

For the details and links to examples, see Using transformation output as input for another transformation.

An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, right?

The XSLT Recommendation includes a DTD Fragment for XSL Stylesheets with some indications of what you need to do to create a complete DTD for a given stylesheet. Keep in mind that stylesheets can include literal result elements and produce output that is not valid XML.

You can use the xsl:stylesheet doctype defined in xsl-html40s.dtd for stylesheets that generate HTML.

If you use a character output stream to instantiate the StreamResult object which holds the transformation output, the Writer uses its own encoding, not the encoding you specify in the stylesheet.

If you want to use the stylesheet output encoding, do not use StreamResult(java.io.Writer) to instantiate the holder for the output. Alternatively, you can specify the encoding when you create a Writer (java.io.OutputStreamWriter). Once the Writer exists, you cannot change its encoding.

Use or mimic the command-line processor ( org.apache.xalan.xslt.Process).

A TransformerException generally wraps another exception, often a SAXParseException. The command-line processor uses the static org.apache.xml.utils.DefaultErrorHandler printLocation() method to chase down the exception cause and get a SourceLocatorthat can usually report line and column number.

Suppose you wanted to modify the ValidateXMLInput sample in the samples/Validate subdirectory to include line and column numbers . All you need to do is call DefaultErrorHandler.printLocation() in the the Handler internal class error() and warning() methods. For example, replace

	public void error (SAXParseException spe) throws SAXException { System.out.println("SAXParseException error: " + spe.getMessage()); }

with

	public void error (SAXParseException spe) throws SAXException { PrintWriter pw = new PrintWriter(System.out, true); org.apache.xml.utils.DefaultErrorHandler.printLocation(pw, spe); pw.println("SAXParseException error: " + spe.getMessage()); }

You can also replicate code from the printLocation() method to obtain a SourceLocator, and then use the SourceLocator getLineNumber() and getColumnNumber() methods. The getRootSourceLocator() method below returns a SourceLocator.

	import javax.xml.transform.SourceLocator; import javax.xml.transform.TransformerException; import org.xml.sax.SAXException; import org.xml.sax.SAXParseException; import org.apache.xml.utils.SAXSourceLocator; import org.apache.xml.utils.WrappedRuntimeException; .... public static SourceLocator getRootSourceLocator(Throwable exception) { SourceLocator locator = null; Throwable cause = exception; // Try to find the locator closest to the cause. do { if(cause instanceof SAXParseException) { locator = new SAXSourceLocator((SAXParseException)cause); } else if (cause instanceof TransformerException) { SourceLocator causeLocator = ((TransformerException)cause).getLocator(); if(null != causeLocator) locator = causeLocator; } if(cause instanceof TransformerException) cause = ((TransformerException)cause).getCause(); else if(cause instanceof WrappedRuntimeException) cause = ((WrappedRuntimeException)cause).getException(); else if(cause instanceof SAXException) cause = ((SAXException)cause).getException(); else cause = null; } while(null != cause); return locator; }

Xalan-Java exception handling: The exception architecture in Xalan-Java and with transforms in general is tricky because of multiple layers of exception handling, involving movement back and forth between SAX and Transformer exceptions and across pipes. Xalan-Java often uses a WrappedRuntimeException to throw over many layers of checked exceptions, in order not to have every possible checked exception be declared for every function in the stack, which means it has to catch this exception at the upper levels and unwrap the exception to pass it on as a TransformerException. A JAXP 1.1 TransformerException often wraps another exception. Two of the TransformerException structures that are frequently used to construct contained exceptions in JAXP 1.1 do not set the locator. The locator is not set because we don't know the type of exception that the Throwable argument represents. The solution is to chase up the contained exceptions to find the root cause, which will usually have a location set for you. This can be somewhat tricky, as not all the exceptions may be TransformerExceptions. A good sample is in the DefaultHandler static printLocation() method, which the Xalan-Java command-line processor uses to report errors. You can also roll your own functions along the lines of the getRootSourceLocator() example above.

If you install xalan.jar in the servlet engine's lib directory (e.g., tomcat/lib), as opposed to the servlet's lib directory, then the Xalan-Java classes are loaded by a classloader that does not see the classes in the servlet's classloader (i.e., the extension classes, if you placed them there). The Xalan-Java classes try to load the extension classes using their own classloader, and that attempt fails.

Workaround: place xalan.jar in the servlet's lib directory and NOT in the servlet engine's lib directory. Another workaround is to place the extension classes also in the servlet engine's lib directory, but you generally want to avoid cluttering that directory.

Thanks to Gunnlauger Thor Briem (gthb@dimon.is) for providing this information.