Sample SAXON Applications

Several sample applications are included in the SAXON distribution.

Note: the example commands here are for the Windows platform, using the SUN Java Virtual Machine. To use Microsoft's Java VM, substitute "jview" for "java". 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 has now been changed so filenames 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.

DTDGenerator

This is a utility which, given an XML document as input, produces a document type definition (DTD) as output.

See here for details.

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

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.

Book list

This is a very simple demonstration to illustrate several SAXON capabilities. 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 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

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 three new stylesheet elements: sql:connect, sql:insert, and sql:column:

sql:connect creates a database connection. It has attributes "database", "user", and "password", all of which are attribute value templates (so the values can be passed in as parameters). 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: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).

A specimen stylesheet that uses these XSL extension is books.sqlxsl. 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.
Execute the stylesheet from the command line, as follows:

java com.icl.saxon.StyleSheet data\books.xml books.sqlxsl

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

Shakespeare

This demonstration includes a set of related programs. They work 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.

Shakespeare play splitter

The Java application Loadplay.java splits a large XML document into several smaller linked XML documents.

LoadPlay is a free-standing Java application which you can run from the command line. It takes as input a full Shakespeare play (for example othello.xml which is included in the distribution) and splits it into a number of separate XML files, one for the "front material" of the play, and one for each scene in the play.

To run the program:

Ensure it is on your CLASSPATH
Ensure you have installed a SAX parser and registered it in the ParserManager.properties file
Change directory to the samples/data directory containing the file othello.xml
Enter the command line:
java LoadPlay othello

A directory called "othello" is created and the play and scene files are generated within it. The program creates an output directory with the same name (othello) as the input file (othello.xml). The parameter should therefore be the name of the play file without its ".xml" suffix.

Shakespeare servlets

There are two programs (ShowPlay and ShowScene) for displaying the generated plays and scenes at a web browser. They are written as Java servlets, and can be run in any web server that supports the servlet interface.

To run them, follow the following steps:

Ensure your web server is properly configured to run servlets
Copy the two files ShowPlay.class and ShowScene.class into the relevant servlets directory, which depends on which web server you are using. It may well be a directory called servlets.
Create an HTML page which references the ShowPlay servlet. It should contain a hyperlink such as:
<a href=servlets/ShowPlay?dir=plays&play=othello>Othello, the Moor of Venice</a>
Here the dir parameter is a directory containing all the Shakespeare plays, and the play parameter is a subdirectory containing the various XML files constituting the text of Othello, which you prevoiusly created using the LoadPlay program.
Select this HTML page from your browser and click on the link to Othello. You should be able to view the front page of the play, and browse through its individual scenes.

If you have problems getting this to work, and there seem to be no useful diagnostics visible at the web browser, check in the web server log files. Also, try getting any sample servlets supplied with the web server to work first: this will ensure that the environment is OK. The most likely cause of problems is that the code you need (servlets, SAXON, the XML parser) is not all on the class path used by the web server: this is not necessarily the same class path as you use from the command line.

The Bible

This application is included in two forms: a Java application and an XSL stylesheet. Both do exactly the same thing, and it is instructive to compare them. Both are in the samples directory: the java source is in java\RenderBible.java, the stylesheet in styles\bible.xsl

The application 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 application 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 Java application, make sure that RenderBible.class (issued in the samples directory) is on your class path, then from the command line execute:

java RenderBible nt.xml htmldir

where nt.xml is the file containing the input document and htmldir is the directory that will contain the 292 generated HTML files. The output directory will be created if it does not already exist.

To do the same thing with the XSL 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 XSL parameter "dir" to the value "htmldir", which is referenced within the stylesheet to select a directory for output files.

You can also try compiling the stylesheet. Proceed as follows:

Compile the stylesheet:
java com.icl.saxon.xslcomp.Compiler styles\bible.xsl dir=bibstyle
Compile the resulting java program:
javac bibstyle\Bible.java
Run the compiled stylesheet to render the source XML:
java Bible.class data\nt.xml dir=htmldir

This assumes that the bibstyle directory is on your CLASSPATH.

Michael H. Kay
13 April 2000