Getting started with SaxonJ
Saxon doesn't come with a graphical user interface: it's a library designed to be integrated into other tools and applications. You will therefore start by using it from the operating system command line.
Alternatively, Saxon is integrated with popular XML development environments such as Oxygen XML Editor and Stylus Studio, which will handle all the installation dependencies.
Ensure that Java is installed. SaxonJ 12 is built and tested using Java 11, but should still be usable with Java 8 or later. If for some reason you need to run with an earlier Java release, SaxonJ 9.8 ran with Java SE 6 or later, while SaxonJ 11 ran with Java 8 or later. To check that Java is installed, try typing
java -versionat 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 SaxonJ-HE which you can download:
Alternatively, the commercial versions of the product (SaxonJ-PE and SaxonJ-EE) can be downloaded from www.saxonica.com/download/java.xml.
Because the software is pure Java, the same software is used whether you are running on Windows, Linux, or Mac OS/X.
The software comes as a zip file. Unzip it into a suitable directory, for example
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 calledjava -cp c:\saxon\saxon-he-12.0.jar net.sf.saxon.Query -t -qs:"current-date()"
saxon-he-12.0.jarfor Saxon Home Edition,
saxon-pe-12.0.jarfor the Professional Edition, or
saxon-ee-12.0.jarfor the Enterprise Edition (where the "12.0" in the name will change to "12.1", "12.2", etc. in subsequent maintenance releases):
- 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
- 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 may find it useful to install the sample applications. These are packaged together with a copy of this documentation in the file
saxon-resources-12.zip. This can be downloaded from either the GitHub Saxon-HE repository 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).
You might also like to experiment with the Gizmo tool. This is a simple interactive command-line application allowing you to display, search, and modify XML files from a terminal, as well as to invoke XSD validation and XSLT transformations. It is a useful testbed for trying out XPath expressions, or for examining the structure of unfamiliar XML documents.
If you are using features specific to SaxonJ-PE or SaxonJ-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, is best placed in the same directory where the file
saxon-ee-12.#.jaris 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 saxon-he-12.0.jar net.sf.saxon.Transform -t -s:samples\data\books.xml -xsl:samples\styles\books.xsl -o:c:\temp.html
for XQuery (all on one line):java -cp saxon-he-12.0.jar net.sf.saxon.Query -t -s:samples\data\books.xml -q:samples\query\books-to-html.xq -o:c:\temp.html
c:\temp.html in your browser to check that it worked.
For more details on installing SaxonJ, see Installing (Java).