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.

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

  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 saxon-he-12.0.jar for Saxon Home Edition, saxon-pe-12.0.jar for the Professional Edition, or saxon-ee-12.0.jar for the Enterprise Edition (where the "12.0" in the name will change to "12.1", "12.2", etc. in subsequent maintenance releases):

    java -cp c:\saxon\saxon-he-12.0.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
    • 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 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 download site (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. 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.

  7. 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-pe-12.#.jar or saxon-ee-12.#.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 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

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

For more details on installing SaxonJ, see Installing (Java).