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.
-
Ensure that Java is installed. This must be Java SE 6 (also known as JDK 1.6) 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. -
Download the Saxon software (you will typically start with the open-source version Saxon-HE) from SourceForge. Alternatively, the commercial versions of the product (Saxon-PE and Saxon-EE) can be downloaded from www.saxonica.com. Because the software is pure Java, the same version applies whether you are using Java on Windows, Linux, or Mac OS/X.
-
The software comes as a zip file. Unzip it into a suitable directory, for example
c:\saxon
. -
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
java -cp c:\saxon\saxon9he.jar net.sf.saxon.Query -t -qs:"current-date()"saxon9he.jar
for Saxon Home Edition,saxon9pe.jar
for the Professional Edition, orsaxon9ee.jar
for the Enterprise Edition: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.
-
As a first-time user, you will probably want to install the sample applications. These are packaged together with a copy of this documentation 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). -
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 evaluation license key by going to www.saxonica.com and clicking on "Download / Evaluation License". 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 filesaxon9pe.jar
orsaxon9ee.jar
is found. When running Saxon from the command line, it not usually necessary for the directory containing the license file to be on the classpath. For more details on Saxon license keys, see the Saxon Licenses section.
You can now run one of the sample stylesheets or queries that comes with 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):
java -cp saxon9he.jar net.sf.saxon.Transform -t -s:samples\data\books.xml -xsl:samples\styles\books.xsl -o:c:\temp.htmlfor XQuery (all on one line):
java -cp saxon9he.jar net.sf.saxon.Query -t -s:samples\data\books.xml -q:samples\query\books-to-html.xq -o:c:\temp.htmlNow 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).