SAXON home page

Sample SAXON Applications

Several sample applications are included in the SAXON distribution.

Contents
TrAX Examples
Sample Servlet
The Book List Stylesheet
SQL Extensions
Shakespeare Example
Bible Example
JDOM Example

JAXP examples

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

A sample program that illustrates many features of the JAXP transformation interface is included in the distribution as TraxExamples.java. Source XML and XSL 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

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.


SaxonServlet

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:

http://server.com/servlets/SaxonServlet?source=doc.xml&style=sheet.xsl

Note: Internet Explorer may assume 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.

Security warning: if you implement a servlet that is prepared to execute untrusted stylesheets, be sure to disable the use of extension functions. Otherwise users will be able to submit stylesheets for execution that call arbitrary Java methods on your server, and these will typically have permissions to access private resources on the server machine.

The Book List Stylesheet

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:

java com.icl.saxon.StyleSheet data/books.xml styles/books.xsl >output.html

This produces an HTML page showing the data. (The output isn't very pretty, if you have time to write an improved version, please send it in).

The stylesheet takes a parameter named "top-author". This is the name of the "author of the week", and the default value is "Bonner". To run the stylesheet with a different top author, try:

java com.icl.saxon.StyleSheet data/books.xml styles/books.xsl top-author=Danzig >output.html

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

java  ShowBooks  samples/data/books.xml  >test1.html

An SQL style sheet

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 "/com.icl.saxon.sql.SQLElementFactory".

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

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:

java com.icl.saxon.StyleSheet data/books.xml styles/books-sql.xsl

The database will be populated with data from the books.xml document.


Shakespeare Example

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:

cd samples
java com.icl.saxon.StyleSheet data/othello.xml styles/play.xsl dir=playhtml

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.


The Bible

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://sunsite.unc.edu/pub/sun-info/standards/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. 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  com.icl.saxon.StyleSheet   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.

JDOM Example

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

To use this facility:

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.


Michael H. Kay
Saxonica Limited
22 June 2005