ASF: Download/Build & Dependencies

+ + + +	+Xalan XSL Transformer User's Guide +
Download/Build & Dependencies

Download/Build & Dependencies

+Downloading the latest release +
+Downloading what else you might need +
+Where do I get Xerces-Java? +
+How do I view Xalan code in a browser? +
+How do I download the latest development code to build myself? +
+Using ant +
+Rebuilding a sample application +
+Where do I download previous releases? +

Downloading the latest release

You can download the pre-built binary distributions from one of the + mirror sites at xalan-j distribution directory. +

+ +

Xalan-J has two processors, + an interpretive one, Xalan Interpretive, and a compiled one, Xalan Compiled (XSLTC). + Your choice of which binary distribution to download depends on which + of the processors you want to use. + There are 2 binary distributions available; you only need to choose one of them. + Both binary distributions contain xml-apis.jar and xercesImpl.jar from Xerces-Java 2.11.0.

The first binary distribution, xalan-j_2_7_2-bin.zip or + xalan-j_2_7_2-bin.tar.gz, + contains the Xalan Interpretive processor, the Xalan Compiled processor (XSLTC) and the + runtime support packages in a single jar, called xalan.jar. + The reason to use this distribution would be that you don't know + which processor you are going to use, or might be using both. +

The second binary distribution, xalan-j_2_7_2-bin-2jars.zip or + xalan-j_2_7_2-bin-2jars.tar.gz + contains the Xalan Interpretive processor in xalan.jar, and the Xalan Compiled + processor (XSLTC) and the runtime support packages in xsltc.jar. + The reason to using this distribution is that you want more control. + If you are using just XSLTC you can put xsltc.jar on the classpath + and not xalan.jar. If you are using just the interpretive processor + you can put xalan xalan.jar on the classpath and not xsltc.jar. Of course + you can put both xalan.jar and xsltc.jar from this distribution + on your classpath if you want to use both. +

+ + +

+ We provide two distributions: a binary distribution, and a source distribution. + You can also download a source distribution from one of the same + mirror sites at xalan-j distribution directory. The difference + is that a binary distribution contains -bin in its name, + whereas a source distribution contain -src in its name. +

+ +

To use Xalan-Java, you need the following which are available from + either a binary or source distribution:

+xml-apis.jar JAXP APIs
+xercesImpl.jar (or another XML Parser)
+xalan.jar +
+xsltc.jar the XSLTC processor, if you choose a 2jars distribution
+serializer.jar which are the serializer classes of + Xalan-Java

+ If you have downloaded a binary distribution, you already have a build + (you have the jars). This is also true for a source distribution, however + if you downloaded a source distribution, + you have the option to use Ant to build Xalan-Java, + including xalan.jar, xsltc.jar, serializer.jar + and other things, see Using Ant for more + details. +

+ + + +â +

+(top) +

Downloading what else you might need

To use Xalan-Java, you need the following:

The JDK or JRE 1.3.x, 1.4.x, or 5.x

+ You can get the JDK or JRE from + IBM developerWorks or java.sun.com. +

If you plan to run XSLT extensions + through extension functions or elements, and you want to implement + that support in languages + other than Java, then you will need an implementation of the Bean Scripting Framework (BSF). + An open source implementation is available for download from Apache. See the + Apache Jakarta + BSF project. If you plan to run XSLT extensions implemented in scripting + languages, you will need bsf.jar and one or more additional files as indicated in + extensions language requirements. +

+ + +â +

+(top) +

Where do I get Xerces-Java?

+ The Xalan-Java Version 2.7.2 has been tested with Xerces-Java 2.11.0. +

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

+ + + + + +

+ +	+ You can use Xalan-Java with other XML parsers that implement + the Java API for XML Processing (JAXP) 1.3. + See Plugging in the Transformer and XML parser. +

+ The Xalan-Java download includes xercesImpl.jar from Xerces-Java 2.11.0. In conjunction with xml-apis.jar, + this is all you need to run Xalan-Java with the Xerces-Java XML parser. You can, however, download the + complete Xerces-Java binary or source distribution from the xerces-j distribution directory. + If you cannot find Xerces-Java 2.11.0 at that location, have a look at the + Apache archive location for + Xerces Java. +

+ + + + + +

+ +	+ If you plan to use a different XML parser, see Plugging + in a Transformer and XML parser. +

+ + +â +

+(top) +

How do I view Xalan code in a browser?

+ If you wish to view some of Xalan's files in a browser without downloading the + whole project you can view it at + http://svn.apache.org/viewvc/xalan/ + or at + http://svn.apache.org/repos/asf/xalan/. + The link with "viewvc" in it is slightly prettier. +

+ The java/trunk and test/trunk subdirectories are the ones with the latest development code. +

+ + + +â +

+(top) +

How do I download the latest development code to build myself?

+ If you have downloaded a source distribution, or obtained source code + using subversion, this section may be of interest to you. +

+ If you wish to download Xalan and build it yourself, perhaps because you want to + apply a patch and test it, you will need a subversion client and anonymous access + to the repository. + Don't worry, everyone has anonymous access. + You can find pre-built binaries of subversion clients for different + operating systems here: + + http://subversion.tigris.org/project_packages.html#binary-packages. + See + + http://www.apache.org/dev/version-control.html + for more information on Apache and subversion. +

+ Once the subverion client is installed on your local machine you + can use the command line client program svn + to get the latest Xalan-J using a command line something like this: +

+    svn checkout http://svn.apache.org/repos/asf/xalan/java/trunk java    
+

+ where the argument after checkout is the Subversion repository location, + in this case the location of the latest development code, and the last argument, + in this case java is the location of the local directory that the repository is + copied to. +

+ Similarly for the test harness, you can download the latest test harness with a Subversion command + something like this: +

+    svn checkout http://svn.apache.org/repos/asf/xalan/test/trunk test    
+

+ Those two commands will put a copy of the latest parts in the local + directories java and test, + which are sibling directories. If you + want to test your build with + the test harness provided with Xalan then it is easiest if you keep the + local directory names + as suggested. With your paths set up to compile Java code, go into the local java + directory and issue these two commands: +

+  build clean
+  build  
+

+ The build.bat batch file, or build.sh shell script (depending on + your operating system use ant and the buildfile build.xml. See + the section Using ant for more information. +

+ Other useful targets may be xsltc.jar or serializer.jar. + If you want to test the jars you just built in the directory java/build, change to + directory test and issue this command: +

+  build jar
+  build smoketest
+

+ The first target, jar builds the test harness and only needs to be done + once after the test repository is checked out. The second target, smoketest, + runs the Xalan-J intepretive smoketest. + Running the build smoketest or other targets in the test directory + automatically looks for the jars in the directory ../java/build + and that is why it is easiest to download the projects into suggested sibling + directories with the given names. +

+ Towards the end of the console output you will see two CONGRATULATIONS! messages if all + goes well. The end of the console output should look like this: +

+    .
+    .
+    .
+minitest-pass:
+     [echo]  [minitest] CONGRATULATIONS! The Minitest passed!
+     [echo]  [minitest] See details in smoketest/Minitest.xml
+
+smoketest-notpass:
+
+smoketest-pass:
+     [echo]  [minitest] CONGRATULATIONS! The Smoketest passed!
+     [echo]  [minitest] Details are in smoketest/results-conf.xml, smoketest/results-api.xml, smoketest/extensions/results-extensions.xml
+
+smoketest:
+
+BUILD SUCCESSFUL
+Total time: 2 minutes 4 seconds
+build completed! 
+

+ Don't be fooled by the BUILD SUCCESSFUL messages, look for the two CONGRATULATIONS! + messages. If you run the smoketest for XSLTC with build smoketest.xsltc you wil + only get one CONGRATULATIONS! message if all goes well. +

+ + +â +

+(top) +

Using Ant To Build

+ If you have downloaded a source distribution, or obtained source code + using subversion, this section may be of interest to you. +

+ +

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

Set the JAVA_HOME environment variable to the JDK root directory.
+
+ JDK 1.3.1 or higher is required to build Xalan-Java. You must put tools.jar from the JDK + bin directory on the classpath.
+
+
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).

+ +

The Xalan-Java source code tree is in the src directory. +

+ If you are using Ant, the target is jar (the default). +

+ +

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Ant Target +	+What Ant does +
compile	compiles Xalan-Java in build/classes.
jar (the default)	creates xalan.jar and serializer.jar in the build directory
serializer.jar	creates serializer.jar in the build directory
xsltc.jar	creates xsltc.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
fulldist	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 without 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, and xml-apis.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 jar utility to store the resulting .class files in xalan.jar +

+ + + +â +

+(top) +

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, serializer.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. These packages are available via + the servlet.jar file found in Apache Tomcat ( see The Jakarta Site - Apache Tomcat ).

After recompiling a sample, you can use the 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.

+ + +â +

+(top) +

Where do I download previous releases?

+ To access previous releases, see the xalan-j archive directory. +

+ + +

+(top) +

+ + + +	+Xalan XSL Transformer User's Guide +
Xalan-Java DTM

+â +

+(top) +

Introduction

The Document Table Model (DTM) is an interface to a Document Model designed specifically for + the needs of our XPath and XSLT implementations. The motivation behind this model is to optimize + performance and minimize storage.

Specifically, DTM avoids the overhead of instantiating the objects the standard DOM requires to + represent a tree of nodes. DTM uses unique integer "handles" to identify nodes, integer ID values + to represent URLs, local names, and expanded names, and integer index and length references to a + string buffer to represent the text value of each node.

In general, the "read" APIs to DTM resemble those of the W3C Document Object Model + (DOM) interface. However, in place of the DOM object tree of nodes, DTM + uses integer arrays and string pools to represent the structure and content of the XML document to + be transformed. DTM also structures the document's contents slightly differently, to better match + the XPath data model; some details and constraints present in a standard DOM are suppressed, and a + few XPath-specific features are added.

DTM is intended to be a read-only model, and so does not attempt to replicate the DOM's write or + create-node operations.

The details of constructing a DTM vary depending on which implementation of this API you are + using. Two reference implementations are currently available:

SAX2DTM (built via a SAX stream)
DOM2DTM (which provides DTM access to an existing DOM)

Both DTMs can be built incrementally (see incremental transforms). + When operating incrementally, the DTM allows the Xalan-Java processor to begin reading the DTM and + performing the transformation while the DTM is still being assembled (for example, while the parser + is still parsing the XML source), and attempts to do only as much work as is needed to support the + read requests actually made by the XPath or XSLT processor.

For the convenience of user-written extensions, a proxy mechanism presents the contents of the + DTM as a read-only subset of the DOM.

+ + +â +

+(top) +

DTM performance settings

Xalan-Java implements two DTM performance features that you can control with the TransformerFactory + setAttribute(String name, Object value) method.

+ + + + + + + + + + + + + + + + +

Attribute name (URL)	Default setting	Description
"http://xml.apache.org/xalan/features/incremental"	false	+incremental transforms +
"http://xml.apache.org/xalan/features/optimize"	true	+optimized transforms +

Both of these DTM settings are described below.

+ +

+ â +

+(top) +

'http://xml.apache.org/xalan/features/incremental'

Set this feature to true to enable incremental transformations. If set to false (the default), + the transform and the parse are performed on the same thread.

+ + + + + +

When set to true: If the parser is Xerces, we perform an incremental transform on a single + thread using the Xerces "parse on demand" feature. If the parser is not Xerces, we run the + transform in one thread and the parse in another. Exception: if the parser is not Xerces + and the XML source is a DOMSource, setting this feature to true has no effect.

+ + + + + +

+ +	The incremental feature is not currently supported by the XSLT Compiling processor, XSLTC.

Example: setting incremental transforms to true (for the XSLT Interpretive processor):

javax.xml.transform.TransformerFactory tFactory =
+            javax.xml.transform.TransformerFactory.newInstance();
+ // setAttribute() takes a String and an Object.            
+  tFactory.setAttribute
+            ("http://xml.apache.org/xalan/features/incremental", 
+             java.lang.Boolean.TRUE);
+  ...

+ + + â +

+(top) +

'http://xml.apache.org/xalan/features/optimize'

When set to true (the default), this feature enables optimizations that may involve structural + rewrites of the stylesheet. Any tool that requires direct access to the stylesheet structure + should set this feature to false.

+ + + +

+(top) +

DTM node location tracking setting

The DTM also provides a setting that you can use to track location information for each node in + the source document. See "http://apache.org/xalan/features/source_location" +

+ +

+(top) +