Getting started with Saxon on the Java platform

Saxon doesn't come with a graphical user interface: it's designed to be integrated into other tools and applications. You will therefore start by using it from the operating system command line. On Windows, you may want to install a text editor such as jEdit that offers a more friendly command line than the standard DOS console provided by Microsoft. However, if you're not comfortable running applications from the command line, you might like to try the open-source Kernow product from Andrew Welch. This installs Saxon for you.

Alternatively, Saxon is integrated with popular XML development environments such as oXygen and Stylus Studio, which will handle all the installation dependencies.

1. Ensure that Java is installed. This must be Java JDK 1.5 (also known as J2SE 5.0) or later. To check that Java is installed, try typing java -version at the command prompt. If it is not installed, you can get the software from Oracle.

2. Download the Saxon software (you will typically start with the open-source version) from SourceForge. Because the software is pure Java, the same version applies whether you are using Java on Windows, Linux, or Mac OS/X.

3. The software comes as a zip file. Unzip it into a suitable directory, for example c:\saxon.

4. To check that the software is working, try running a simple query from the command line, as follows. The filename after the "-cp" flag should match the location where you installed the software. The file will be called saxon9he.jar for Saxon Home Edition, saxon9pe.jar for the Professional Edition, or saxon9ee.jar for the Enterprise Edition:

   java -cp c:\saxon\saxon9he.jar net.sf.saxon.Query -t -qs:"current-date()"

   Here java tells the operating system to run the Java virtual machine; the filename after -cp is known as the classpath, and tells Java where to find the Saxon application software; net.sf.saxon.Query is the Saxon entry point for the XQuery processor; the option -t tells Saxon to report what it is doing on the console; and the option -qs:current-date() tells Saxon to run the simple query current-date(), which returns the current date and displays the result on the console.

   If this doesn't work, there are three possible reasons: the operating system can't find the Java software; Java can't find the Saxon software; or Saxon has been invoked, but has failed to run your query. The error message should give you a clue which of these is the case.

5. As a first-time user, you will probably want to install the sample applications. These are packaged together with a copy of this documentation and Saxon-HE source code in the file saxon-resources9-n.zip. This can be downloaded from either the SourceForge or Saxonica sites. (It is the same file in both cases). Unzip the contents of this file into the same directory as the Saxon software. When you run a program that uses Saxon, this program as well as Saxon itself will need to be on the classpath. For more details of the classpath, see Installing (Java).

6. If you are using features specific to Saxon-PE or Saxon-EE, the commercial editions of Saxon, you will need to obtain a file containing a licence key. You can apply for a free 30-day license key by going to www.saxonica.com and clicking on "Evaluation Copy". The license key file will be sent by email within 24 hours. This file, called saxon-license.lic, should be placed in the same directory where the file saxon9pe.jar or saxon9ee.jar is found. When running Saxon from the command line, it is no longer necessary for the directory containing the license file to be on the classpath.

You can now run one of the sample stylesheets or queries that comes with in the saxon-resources download. Assuming you installed Saxon-HE into c:\saxon, make this your current directory, and type:

for XSLT (all on one line):

for XQuery (all on one line):

Now open c:\temp.html in your browser to check that it worked.

For more details on installing Saxon on the Java platform, see Installing (Java)