Note: the example commands here are for the Windows platform, using the SUN
Java Virtual Machine. UNIX users will
have little difficulty in adapting the commands; the only real change is to use "/" instead
of "\" in path names (this affects the command line only: the Java code itself
should work on any platform). Running Java applications
on a Macintosh is a little more complicated, because of the absence of a
conventional command line.

This is a stylesheet whose output is a knight's tour of the chessboard (the knight can start
on any square, and has to visit each square exactly once). This was published as an example
stylesheet in my book XSLT Programmers Reference (Wrox Press)
but has been completely reworked so it now makes extensive use of XSLT 2.0 and XPath 2.0
features. It is worth studying this stylesheet as an introduction to the use of XSLT 2.0 functions,
and XPath 2.0 for and if expressions.

The stylesheet can be found in the file samples\tour.xsl. It takes no input
from the source document, so you can supply any XML document as input, for example the
stylesheet itself. You can run this example with a command of the form:

java -jar saxon7.jar -a samples\styles\tour.xsl start=e5 >tour.html

When you display the resulting HTML file in your browser it should look like this:

Knight's tour starting at e5

Saxon supports the Java JAXP 1.1 API, also known as TrAX (package javax.xml.transform)
for invoking the stylesheet processor.
This API is useful when you want to write your own Java applications that invoke Saxon.

A sample program that illustrates many features of the TrAX interface is included in
the distribution as TraxExamples.java. Source XML and XSLT files for use with this
program are included in the trax directory. To run the program, use the command:

cd $saxonhome/samples/trax
java TraxExamples

You can supply an argument to indicate which of the examples you want to run; see the source
code for details. By default, they are all executed in turn.

One of the examples shows how to use TrAX to process input from a third-party (non-Saxon)
DOM document, and how to
send output to a third-party DOM document. This example tests to see if either Crimson or
Xerces is present on the classpath; if not, it should fail cleanly. You will need to change the
source code and recompile if you want to
use it with a different DOM implementation.

This is a general-purpose servlet that takes the name of a source document and stylesheet
as URL parameters, and processes the stylesheet to create a result document which is sent back
to the browser for display. The result document may have any media type, though HTML and XML are
the most likely.

The servlet maintains a cache of prepared stylesheets; if the same stylesheet is used repeatedly,
it is only parsed and validated once, which will often greatly improve performance. Prepared style
sheets are thread-safe so they can be used to serve documents to several users concurrently.

The URLs for the source document and the stylesheet document are supplied in the URL,
which will typically take the form:

Note: Internet Explorer assumes that if the URL ends with ".xml" or ".xsl", as in
the above example, then the returned file will be XML - even if the media type in the HTTP header
is set to "text/html". You can prevent this behaviour by adding an extra dummy parameter, for example
"&x=y".

The source and style parameters identify the source document and stylesheet by URL.
These are interpreted relative to the servlet context. This means that specifying
say "style=/styles/styleone.xsl" in the URL will locate the stylesheet in this file relative to the
root directory for the web server.

The stylesheet is prepared the first time it is used, and held in memory in a cache. The cache may
be cleared (for example, if a stylesheet has been changed) using a URL such as:

http://server.com/servlets/SaxonServlet?clear-stylesheet-cache=yes

This code is provided purely as a sample, in the expectation that you will customise it to your
particular site requirements.

This is a very simple sample stylesheet to illustrate several Saxon extensions.
It uses the XML file books.xml (derived from a file issued originally by Microsoft).
You will find this in the samples\data directory. The DTD is in books.dtd

There is a style sheet books.xsl that can be used to display the data: run this as
follows, with the samples directory as the current directory:

It is possible (under those operating systems I know of) to write the author's name in quotes if
it contains spaces, e.g. top-author="A. A. Milne".

There is another style sheet, books-csv.xsl, which
converts the data into a comma-separated-values file.

There is also a Java program ShowBooks.java (in the samples\java directory) to process the books.xml
file without using XSL.
This can be run directly from the command line. It produces on the standard output an
HTML page showing the book list.

To run the application, first make sure the compiled program (ShowBooks.class) is on
the classpath, then execute

Saxon implements the element extensibility feature of the XSLT standard, allowing
you to extend the XSLT language by implementing your own stylesheet elements.
A specimen extension has been written to illustrate this feature: it
allows you to create stylesheets to load data into a relational database.

To use the SQL extension elements in a stylesheet, you need to define a namespace prefix
(for example "sql") in the extension-element-prefixes attribute of the xsl:stylesheet element,
and to map this prefix to namespace URI that ends in "/net.sf.saxon.sql.SQLElementFactory".

This extension defines five new stylesheet elements: sql:connect, sql:query,
sql:insert, sql:column, and sql:close:

sql:connect creates a database connection. It has attributes "driver", "database", "user", and "password",
all of which are attribute value templates (so the values can be passed in as parameters).
the driver attribute names the JDBC driver class to be used. The
database name must be name that JDBC can associate with an actual database, and in the sample
stylesheet this database must contain a a table "Book" with three character columns,
"Title", "Author", and "Category".

sql:query performs a query. The attributes are as follows:

table

The table to be queried (the contents of the FROM clause of the select statement).
This is mandatory, the value is an attribute value template.

column

The columns to be retrieved (the contents of the SELECT clause of the select statement).
May be "*" to retrieve all columns. This is mandatory, the value is an attribute value template.

where

The conditions to be applied (the contents of the WHERE clause of the select statement).
This is optional, if present the value is an attribute value template.

row-tag

The element name to be used to contain each row. Must be a simple name (no colon
allowed). Default is "row".

column-tag

The element name to be used to contain each column. Must be a simple name (no colon
allowed). Default is "col".

sql:insert performs an SQL INSERT statement. This causes a row to be added to the table identified
by the "table" attribute.

sql:column is used as a child element of sql:insert, and identifies the name and value of a column
to be included in the INSERT statement. The name of the column is identified by the "name" attribute,
the value may be indicated either by evaluating the expression contained in the "select" attribute, or
as the expanded contents of the sql:column element. The value is always interpreted as a String.
(Remember this is purely a demonstration of extensibility, in a real system there would be a need to
cater for SQL columns of other data types).

sql:close closes the database connection.

A specimen stylesheet that uses these XSL extension is books-sql.xsl. This loads the contents
of the books.xml file into a database table.

To run this stylesheet you will need to do the following:

Create a database (e.g. Microsoft Access) containing a table "Book" with three character columns,
"Title", "Author", and "Category".

Register this database as a JDBC data source. (If you use Microsoft Access, register it as an
ODBC data source called, say, Books, and then it will automatically be available under JDBC as
"jdbc:odbc:Books".

Modify the <sql:connect> element in the stylesheet to specify the correct JDBC connection
name for the database, and if necessary to supply a username and password. Alternatively you can
supply the driver class, database name, username, and password as parameters on the command line.

This example works on an input file
containing a Shakespeare play. You can use any of the Shakespeare plays in Jon Bosak's
distribution at
http://metalab.unc.edu/bosak/xml/eg/shaks200.zip,
but for convenience one of them, Othello, is included in the Saxon distribution
(in the samples\data directory).

Shakespeare stylesheet

There is an XSL stylesheet, play.xsl, which processes an input play in XML and
generates a set of linked HTML files (one for the play and one for each scene) in an
output directory. To run this, create a directory (say playhtml) and execute the following
from the command line:

The last parameter sets the value of the constant dir to the value playhtml;
this constant is referenced from the style sheet when creating output files.

As well as showing how to produce multiple output files using the new XSLT 2.0
xsl:result-document element, this example stylesheet shows how to use
saxon:preview to reduce the memory requirements when processing the
source document sequentially.

The stylesheet bible.xsl takes as input an XML file containing the text of the Old
or New Testament. These files are not included in the Saxon distribution for space
reasons, but can be downloaded from
http://metalab.unc.edu/bosak/xml/eg/rel200.zip
or from various mirror sites. They were prepared by Jon Bosak.

The output of the stylesheet is a set of 292 HTML files in a single
directory, which together provide a frames-oriented rendition of the text. You can see the
result (for the New Testament) at http://www.wokchorsoc.freeserve.co.uk/bible-nt/index.html.
The application also works with the Old Testament text, but not with the other religious
texts included in Jon Bosak's distribution.

To run the stylesheet first create an output
directory (say htmldir), then execute the following from the command line:

java net.sf.saxon.Transform
data\nt.xml styles\bible.xsl dir=htmldir

The final parameter sets the value of the XSLT parameter "dir" to
the value "htmldir", which is referenced within the stylesheet to select a
directory for output files.

The directory samples/applet contains two demonstrations showing how to use
Saxon from an applet embedded in an HTML page. Note that because this release
of Saxon requires JDK 1.2 or later, you cannot run these applets with the default
Microsoft JVM used by Internet Explorer. Instead, you will have to download and
install the Sun Java plugin, obtainable from
http://java.sun.com/getjava.

The subdirectory /demo contains a demonstration taken straight from the Xalan
sample application, showing a window with three frames, containing the source document,
stylesheet, and result. Click on "index.html" to open this in the browser, then click on the
"Transform" button to run a transformation. Note that the HTML page is written in such
a way that expects the saxon7.jar file to be located in the same directory as the HTML
files; you will need to change the HTML to reflect its actual location. The SUN Java VM
uses a security architecture that is fussy about where the file is located, even when
you are running everything on your local machine: I found I had to move saxon7.jar into
the data directory to make it work.

The subdirectory /family-tree contains a demonstration showing some members of
the Kennedy family; open the HTML file to view the data. This demonstration is adapted
from the one in my book XSLT Programmer's Reference. It illustrates how repeated
transformations using the same source document and the same stylesheet can be used to
browse around a data-set, without making repeated visits to the server.

Saxon includes an adapter that allows the source tree to be a JDOM document.

To use this facility:

The JAR file saxon-jdom.jar must be on the classpath

JDOM version 0.7 must be installed and on the classpath

You must be using JDK 1.2 or later.

The sample application JDOMExample.java illustrates how a JDOM tree can be used
with Saxon. It combines two scenarios: running XPath expressions directly against a
JDOM tree, from the Java application; and invoking a transformation with the JDOM document
supplied as the Source object.

The application is designed to take two arguments, the books.xml file
in the samples/data directory, and the total.xsl file in the samples/styles
directory. The application builds a JDOM tree, modifies it in situ to add extra
attributes, and then references these attributes from the stylesheet.