Tracing XSLT events with Xalan

By Brian Schaffner

The Xalan XSLT processor has become the de facto standard for many XML applications. This particular processor is popular because it offers a standard interface and reliable processing in a "freely-available" package.

Xalan also offers some nonstandard extensions of XSLT. One of the more interesting features is Xalan's trace extensions. Let's look at how you can implement a trace within your XSLT processes.

A sample run-through

Due to space considerations, we won't include sample XML and XSL documents in this article. However, we're using some documents that are reasonably simple, so you should be able to duplicate the effect using your own XML and XSL source files.

Let's start by talking about what a trace is and how it works within Xalan. A trace is a mechanism that provides hooks, or callbacks, when particular events occur.

For example, in a SAX parser, you register your handler functions to facilitate the parsing of XML documents as XML events occur; with a Xalan trace, you register a trace class that implements the TraceListener interface. When the processor encounters various XSL events, it sends them to the TraceListener by calling the methods of the TraceListener's interface.

Two ways to use TraceListeners

There are two approaches to using TraceListeners in your code. First, you can use the existing PrintTraceListener class, which is provided in the Xalan package. You could also implement your own TraceListener class and handle events yourself. The PrintTraceListener class is a bit easier to use, particularly if you're just getting into XSL tracing--so we'll only show you that method here.

For reference, you could also create your own class that implements the TraceListener interface. You then provide whatever functionality you need within the TraceListener's defined methods and register your TraceListener just as you would for the PrintTraceListener, which we'll show you below.

PrintTraceListener

The PrintTraceListener class is pretty easy to use. You basically instantiate the PrintTraceListener class with a PrintWriter, set some options, and hook the PrintTraceListener into the processor. Listing A shows a simple implementation of the PrintTraceListener class. Click here.

In this example, we use the System.out PrintStream to instantiate a new PrintWriter class, which is used to instantiate the PrintTraceListener. This allows us to see the output of the PrintTraceListener on the console screen. You could also create a PrintWriter that was attached to a file if you wanted to send the results there rather than to the screen. Notice that once we instantiate the PrintTraceListener, we set two members to true.

We have to do three things in order to hook our trace class into the XSL process. We need to register the trace class with the trace manager. The trace manager is specific to the Xalan processor; therefore, we need to get the underlying implementation for the Transformer class.

The three lines below, which were extracted from the above source, illustrate getting the implementation by casting the Transformer class, finding the TraceManager class within the implementation, and registering our PrintTraceListener via the TraceManager's addTraceListener method.

The Xalan debugger interface provides a mechanism for tracing events as they occur during the processing of XSL stylesheets. For a simple approach, you can use the PrintTraceListener implementation of the TraceListener interface to capture the events. You can also build your own class based on the TraceListener interface. This would allow you to perform more sophisticated event tracing.

For more details, check out the PrintTraceListener JavaDoc documentation.