The following sections provide detailed information about how to download, install, and run five popular XSLT processors with command-line interfaces: Instant Saxon, Saxon, MSXSL, Xalan C++, and jd.xslt. You also learn how to transform XML documents using the graphical tools xmlspy and xRay2. Both xmlspy and xRay2 are XML editors with XSLT capabilities and run only on Windows. A.1.1 Installing and Running JavaAs a first step, you need to get the latest version of the Java Runtime Environment (JRE) or SDK (which includes a JRE) on your machine. To do so, go to http://java.sun.com/downloads. A JRE provides a Java virtual machine (JVM), a Java interpreter (java), and other necessities, but not tools like the Java compiler javac or a JAR (Java Archive) tool such as jar. To get the JRE from the Sun Java site, search for JavaVM, click it, and then click the download button that appears. This will automatically download and install the latest JRE. If you already have the latest JRE installed, this will be detected and you will be alerted about it. You can test to find out whether a JRE is working on your machine by typing this command at a command or shell prompt: java -version If you get something back like the following, you are in good shape: java version "1.4.1_01" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01) Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode) To get a Java SDK, search for the download of your choice on the Sun Java site, such as J2SE 1.4.1, and then select Allplatforms in the text pull-down box. Click the Go button. Under the SDK columns, click the Download link for the appropriate platform, such as Linuxself-extracting file. Fill out the information form if you wish, or just click the download link again. Accept the license by clicking the Accept button. Finally, click the download link, and save the archive to the directory of your choice. After downloading the archive file, follow the installation instructions provided by Sun. (These instructions may vary over time.) A.1.1.1 Setting the path variableAfter the installation is complete, you must place the Java bin directory in your path environment variable. You can add the location to the path using one of the following methods. A.1.1.1.1 The path environment variable on WindowsSupposing the bin directory is located at C:\Java\j2sdk1.4.1_01\bin, on Windows, you could temporarily set the path environment variable at a command prompt with this line: path %path%;c:\Java\j2sdk1.4.1_01\bin This command adds the path C:\Java\j2sdk1.4.1_01\bin, which contains the executable file javac.exe, to your current path variable, represented by the substitution variable %path%. Another method for amending your path variable is adding this command line to your autoexec.bat file so that the new path is set each time you boot your computer. On Windows 2000 or XP Professional, you can also set the path variable by choosing Start Control Panel System Advanced Environment Variables, and then adding the path to your user or system variables in the Environment Variables dialog box. A.1.1.1.2 The path environment variable on UnixSupposing that the bin directory is located at /usr/mike/j2sdk1.4.1_01/bin on a Unix system, you could temporarily set the path environment variable at a bash shell prompt with this line: path="/usr/mike/j2sdk1.4.1_01/bin:$PATH" This command adds the path /usr/mike/java/j2sdk1.4.1_01/bin, which contains the executable file javac.exe, to your current path variable, represented by the substitution variable $PATH. You could also add this command line to your /etc/profile or ~/.profile file, so that the new path is set each time you boot your computer. A.1.1.2 Running the Java compilerWith the bin directory in the path variable, you are ready to put its content to use. Type the following at a command prompt or shell: javac If the path is working right, it will return advice that looks somewhat like this: Usage: javac <options> <source files> where possible options include: -g Generate all debugging info -g:none Generate no debugging info -g:{lines,vars,source} Generate only some debugging info -O Optimize; may hinder debugging or enlarge class file -nowarn Generate no warnings -verbose Output messages about what the compiler is doing -deprecation Output source locations where deprecated APIs are used -classpath <path> Specify where to find user class files -sourcepath <path> Specify where to find input source files -bootclasspath <path> Override location of bootstrap class files -extdirs <dirs> Override location of installed extensions -d <directory> Specify where to place generated class files -encoding <encoding> Specify character encoding used by source files -source <release> Provide source compatibility with specified release -target <release> Generate class files for specific VM version -help Print a synopsis of standard options A.1.2 Using the ClasspathWhen dealing with Java, you also have to deal with the classpath. The classpath is the path that enables a Java interpreter to see the classes that it is trying to execute. When running Java from the command line, Java classes can be included using the -cp or -classpath command-line options. For example, you could place the jar file saxon7.jar in the classpath with something like this: java -cp c:\lib\saxon7.jar net.sf.saxon.Transform test.xml test.xsl You can also place a JAR file in the classpath using this command on Windows: set CLASSPATH=".;c:\lib\saxon7.jar;%CLASSPATH%" The dot (.) refers to the current directory (the Java interpreter needs to be told explicitly to look in the current directory for classes). %CLASSPATH% adds the current classpath to the new value of CLASSPATH. Or type something like this command on Unix: classpath="/usr/lib/saxon7.jar:$CLASSPATH" Another convenient way to handle the classpath is to place a copy of the desired JAR file in the jre/lib directory where your JRE is installed. For example, if your JRE is installed under C:\j2sdk1.4.1_01, it will have the subdirectory jre/lib, which holds various resources. A.1.2.1 The jar methodIf you use the -jar option, however, you can just use a regular path or the path environment variable to find a JAR file. For example, if the JAR file were in the current directory, you could simply type: java -jar saxon7.jar Or, if it were in C:\Temp, you could use: java -jar c:\lib\saxon7.jar This assumes that the manifest file in the JAR has a Main-Class field that tells the Java interpreter where the class holding the main( ) method is. For more information on running JAR-package software, see http://java.sun.com/docs/books/tutorial/jar/basics/run.html. If you would like more help understanding how the Java classpath works and how Java finds classes to run, see http://java.sun.com/j2se/1.4.1/docs/tooldocs/findingclasses.html. For help setting the classpath for Windows, see http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/classpath.html; for help setting the classpath for Solaris or a similar Unix system, see http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/classpath.html. A.1.3 Installing and Running Instant SaxonSaxon is a free, open source XSLT processor created and maintained by Michael Kay and hosted at http://saxon.sourceforge.net. Instant Saxon is a Windows 32 executable version of Saxon, that is, in essence, a parcel of Java classes packaged together in an .exe file. The last release of Instant Saxon at this writing was Version 6.5.3 (August 2003). Michael Kay's Saxon, including Instant Saxon, was the first compliant XSLT 1.0 processor and was released 17 days after the XSLT and XPath recommendations were published in late 1999. Michael Kay is the current editor of the XSLT 2.0 specification, and he's one of the editors of XPath 2.0. Both programs are under development at the W3C. (Blessedly, he was also a technical editor for this book.)
A.1.3.1 Downloading Instant SaxonFollow these steps (they may vary over time):
A.1.3.2 Running Instant SaxonDisplay usage information for Instant Saxon by entering the following at a Windows command prompt: saxon Without any parameters, you should see this usage synopsis: No source file name SAXON 6.5.3 from Michael Kay Usage: saxon [options] source-doc style-doc {param=value}... Options: -a Use xml-stylesheet PI, not style-doc argument -ds Use standard tree data structure -dt Use tinytree data structure (default) -o filename Send output to named file or directory -m classname Use specified Emitter class for xsl:message output -r classname Use specified URIResolver class -t Display version and timing information -T Set standard TraceListener -TL classname Set a specific TraceListener -u Names are URLs not filenames -w0 Recover silently from recoverable errors -w1 Report recoverable errors and continue (default) -w2 Treat recoverable errors as fatal -x classname Use specified SAX parser for source file -y classname Use specified SAX parser for stylesheet -? Display this message Normally, Instant Saxon expects at least two parameters: the name of the source document followed by the name of the stylesheet. Supply the names of the document and stylesheet discussed earlier on the command line, like this: saxon test.xml test.xsl Any file named test, regardless of the file suffix, is fictitious and used only as an example in this appendix. To direct Instant Saxon's output to a file, use the -o option: saxon -o test.out test.xml test.xsl To use an XML document that contains an XML stylesheet PI, use the -a option, followed by the filename: saxon -a test.xml The XML stylesheet PI contains a reference to a stylesheet and will look something like: <?xml-stylesheet href="test.xsl" type="text/xsl"?> For version and timing information, try the -t option: saxon -t test.xml test.xsl If the source document has an associated DTD, you can validate it at runtime with the -v option: saxon -v test.xml test.xsl A DTD will be associated with the XML document by a document type declaration, which will look something like: <!DOCTYPE test SYSTEM "test.dtd"> A.1.4 Installing and Running Saxon (Full Java Version)Saxon is a free, open source XSLT processor that, like Instant Saxon, was created by Michael Kay and hosted at http://saxon.sourceforge.net. The recommended version of Saxon for XSLT 1.0 is Version 6.5.3. The latest version at the time of this writing is 7.7, which partially supports the working drafts for XSLT 2.0 and XPath 2.0. By the time you read this, Saxon may have gone beyond Version 7.7.
A.1.4.1 Downloading SaxonTo download Saxon, follow these steps (which may vary over time):
You can use the full Java version of Saxon on any platform that supports Java, including Windows or a Unix environment such as Linux, Solaris, or Mac OS X. This requires that you have at least a JRE or JVM installed for Version 1.4 or higher. If you don't have Java on your system, you can download an SDK or JRE from http://sun.java.com. You will find installation instructions earlier in this appendix in , Section A.1.1. A.1.4.2 Running SaxonYou can download Saxon from http://saxon.sourceforge.net, or copy the file saxon7.jar from C:\LearningXSLT\examples\ch16 (Version 7.7 of saxon7.jar exists in examples/ch16, but you may want a more recent version, if one is available). Placing the JAR file in your working directory obviates the need to deal with the classpath (see Section A.1.2, earlier in this appendix). This file contains the Java class files that will enable you to transform documents using Saxon. Assuming that saxon7.jar is in your current directory, you can enter the line: java -jar saxon7.jar This should yield the following output if you used no arguments: No source file name SAXON 7.7 from Michael Kay Usage: java net.sf.saxon.Transform [options] source-doc style-doc {param=value}... Options: -a Use xml-stylesheet PI, not style-doc argument -ds Use standard tree data structure -dt Use tinytree data structure (default) -im modename Start transformation in specified mode -o filename Send output to named file or directory -m classname Use specified Emitter class for xsl:message output -r classname Use specified URIResolver class -t Display version and timing information -T Set standard TraceListener -TJ Trace calls to external Java functions -TL classname Set a specific TraceListener -u Names are URLs not filenames -v Validate source document -w0 Recover silently from recoverable errors -w1 Report recoverable errors and continue (default) -w2 Treat recoverable errors as fatal -x classname Use specified SAX parser for source file -y classname Use specified SAX parser for stylesheet -? Display this message param=value Set stylesheet parameter !option=value Set serialization option You can use saxon7.jar with the same arguments as you did with Instant Saxon. For example, to transform test.xml with test.xsl, type the following: java -jar saxon7.jar test.xml test.xsl To send output to a file, use the -o option: java -jar saxon7.jar -o test.out test.xml test.xsl If a document contains an XML stylesheet PI, you can use the -a option: java -jar saxon7.jar -a test.xml The XML stylesheet PI contains a reference to a stylesheet and will look something like: <?xml-stylesheet href="test.xsl" type="text/xsl"?> For version and timing information, use the -t option: java -jar saxon7.jar -t test.xml test.xsl If the source document has an associated DTD, you can validate it at runtime with the -v option: java -jar saxon7.jar -v test.xml test.xsl A DTD will be associated with the XML document by a document type declaration, which will look something like this: <!DOCTYPE test SYSTEM "test.dtd"> A.1.4.3 Using a Windows batch file with SaxonYou can use a batch file on Windows to run Saxon's full Java version. You can copy the following lines and place them in a batch file named sp.bat: @echo off java -jar "C:\LearningXSLT\examples\ch16\saxon7.jar" %1 %2 %3 %4 %5 %6 %7 %8 %9 This assumes that you have set up the directory C:\LearningXSLT\examples\ch16 (among other directories) for the example files. You can change the location of saxon7.jar in the batch file to match your own directory structure. If you are working on Windows 2000 Professional or XP Professional, you can delete the replaceable parameters %1 thorough %9 and use %* in their place. You could then run Saxon by typing: sp test.xml test.xsl A.1.4.4 Using a Unix shell script with SaxonIf you're on a Unix system, you could copy the following into a file named sp.sh: #! /bin/sh java -jar ~/learningxslt/examples/saxon/saxon.jar $* This script assumes that you have set up a directory called learningxslt in your home directory (something like /usr/mike, which is represented by ~/). You can change the location of saxon7.jar in the batch file to match your own set up. You could then run Saxon by typing: sp.sh test.xml test.xsl A.1.5 Installing and Running MSXSLMSXSL is Microsoft's free command-line XSLT processor, available at http://msdn.microsoft.com/downloads/. MSXSL is a Windows 32 executable that requires MSXML 4.0 (msxml4.dll). This processor is incredibly small (25 KB) and is one of the fastest around, probably because it is compiled natively on Windows and uses the XSLT library included in MSXML. You can also download the source code. By default, MSXSL uses UTF-16 output. You have to use the encoding attribute on an output element in a stylesheet to override this, which you probably will want to do because UTF-16 doesn't always produce very attractive output in a command window. A.1.5.1 Downloading MSXSLFollow these steps (they may vary over time):
A.1.5.2 Running MSXSLTo see the display usage information for MSXSL, enter the following at a Windows command prompt: msxsl -? With the -? option, you will see this usage information: Microsoft (R) XSLT Processor Version 4.0 Usage: MSXSL source stylesheet [options] [param=value...] [xmlns:prefix=uri...] Options: -? Show this message -o filename Write output to named file -m startMode Start the transform in this mode -xw Strip non-significant whitespace from source and stylesheet -xe Do not resolve external definitions during parse phase -v Validate documents during parse phase -t Show load and transformation timings -pi Get stylesheet URL from xml-stylesheet PI in source document -u version Use a specific version of MSXML: '2.6', '3.0', '4.0' - Dash used as source argument loads XML from stdin - Dash used as stylesheet argument loads XSL from stdin MSXSL takes at least two arguments: the name of the XML source document followed by the name of the stylesheet. On the command line, type: msxsl test.xml test.xsl To direct output to a file, use the -o option: msxsl -o test.out test.xml test.xsl To transform an XML document that contains an XML stylesheet PI, use the -pi option, followed by an appropriate filename: msxsl -pi test.xml The XML stylesheet PI contains a reference to a stylesheet and will look something like: <?xml-stylesheet href="test.xsl" type="text/xsl"?> For timings, try the -t option: msxsl -t test.xml test.xsl If the source document has a DTD, you can validate it with the -v option: msxsl -v test.xml test.xsl A DTD will be associated with the XML document by a document type declaration, which will look something like: <!DOCTYPE test SYSTEM "test.dtd"> A.1.6 Installing and Running Xalan C++Xalan C++ is an open source XSLT processor hosted by Apache. To run, Xalan C++ also requires the C++ version of Apache's XML parser Xerces. Both Xerces C++ and Xalan C++ are available for download from the Apache site (http://xml.apache.org). A.1.6.1 Downloading and installing Xalan C++Follow these steps (which may vary over time) to install Xalan C++:
To use xalan.exe, you need to add its location to the path, as well as to the location of the Xerces bin directory. If you are working on Windows, follow the instructions in Section A.1.6.2. If you are working on a Unix platform, see Section A.1.6.3. A.1.6.2 Setting the path variable for Xalan on WindowsIf, for example, you installed (actually unzipped) the Xalan C++ archive in the root directory on Windows (C:\), the location for xalan.exe would be something like C:\xml-xalan\c\Build\Win32\VC6\Release. So in order to add this to the path, you could enter the following line: path %path%;"C:\xml-xalan\c\Build\Win32\VC6\Release" This command appends the path C:\xml-xalan\c\Build\Win32\VC6\Release, which contains the executable file xalan.exe, to your current path variable, represented by the substitution variable %path%. If you want, you could add this command line to your autoexec.bat file, so that the new path is set each time you boot your computer. The C++ version of Xerces must also be in the path. If you unzipped Xerces in the root directory, the location for the Xerces dynamic-link libraries would be at C:\xerces-c2_2_0-win32\bin. Add this location to your path as you did with Xalan. On Windows 2000 or XP Professional, you can also set the path variable by choosing Start Control Panel System Advanced Environment Variables, and then adding the path to your user or system variables in the Environment Variables dialog box. With xalan.exe in the path variable, you are ready to put it to use. A.1.6.3 Setting the path variable for Xalan on a Unix platformIf you installed or unzipped the Xalan C++ in your home directory on a Unix platform (such as in /usr/mike), the location for xalan.exe would be something like /usr/mike/xml-xalan/c/Build/Win32/VC6/Release. To add this location to the path, enter the following line: path="/usr/mike/xml-xalan/c/Build/Win32/VC6/Release:$PATH" This command adds /usr/mike/xml-xalan/c/Build/Win32/VC6/Release, which contains the executable file xalan.exe, to your current path variable. (The path variable is represented by $PATH.) If you want, you could add this command line to your /etc/profile or ~/.profile file, so that the new path is set each time you boot your computer. Xerces must also be in the path in order for Xalan to work. If you unzipped Xerces in your home directory on Unix, the location for the Xerces dynamic-link libraries would be at something like /usr/mike/xerces-c2_2_0-win32/bin. Add this location to your path as you did Xalan, and you'll be ready to run. A.1.6.4 Running Xalan C++With Xalan C++ and Xerces C++ installed and the proper directories in the path, you can begin using Xalan. To start, just type the name of the program on a command line: xalan If Xalan works, you will see the following usage information on the screen: Xalan version 1.5.0 Xerces version 2.2.0 Usage: Xalan [options] source stylesheet Options: -a Use xml-stylesheet PI, not the 'stylesheet' argument -e encoding Force the specified encoding for the output. -i integer Indent the specified amount. -m Omit the META tag in HTML output. -o filename Write output to the specified file. -p name expression Sets a stylesheet parameter. -u Disable escaping of URLs in HTML output. -v Validates source documents. -? Display this message. - A dash as the 'source' argument reads from stdin. - A dash as the 'stylesheet' argument reads from stdin. ('-' cannot be used for both arguments.) Xalan takes at least two parameters: the name of the source document followed by the name of the stylesheet, like this: xalan test.xml test.xsl To direct Xalan's output to a file, use the -o option: xalan -o test.out test.xml test.xsl Use an XML document that contains an XML stylesheet PI, and then use the -a option, followed by the filename: xalan -a test.xml The XML stylesheet PI contains a reference to a stylesheet and will look something like: <?xml-stylesheet href="test.xsl" type="text/xsl"?> To set the number of spaces used for the indentation of output, use the -i option, followed by an integer (2 means the output will be indented by two spaces for each element level of the XML document): xalan -i 2 test.xml test.xsl If the source document has an associated DTD, you can validate it at runtime with the -v option: xalan -v test.xml test.xsl A DTD will be associated with the XML document by a document type declaration, which will look something like: <!DOCTYPE test SYSTEM "test.dtd"> |