Running Multiple XSLT Engines with Ant

What is Ant?

Ant is a build utility produced as part of the Apache Jakarta project. It's broadly equivalent to Unix's make or nmake under Windows. make-like tools work by comparing the date of an output file to the date of the input files required to build it. If any of the input files is newer than the output file, the output file needs to be rebuilt. This is a simple rule, and one that generally produces the right results.

Unlike traditional make utilities, Ant is written in Java, so Ant is a good cross-platform solution for controlling automatic file building. That is good news for anyone developing cross-platform XSLT scripts because you only need to target one build environment. Anyone who has tried writing and maintaining equivalent Windows and Unix batch scripts knows how hard it is to get the same behavior across different platforms.

Ant and XSLT

So why would you use Ant and XSLT together? If all you are doing is applying a single XSLT stylesheet to a single XML input file, using a single XSLT engine, then there is probably nothing to be gained. However, if

• you need to apply one or more XSLT scripts to one or more XML input files in some sequence, in order to build your final output file(s);

• you need to run multiple XSLT engines on the same XML input file(s) as part of your regression or integration testing

then Ant is a good and quick way to implement the workflow you need to transform your input(s) into your output(s).

A Simple Example

Using Ant for a simple "1 input, 1 stylesheet, 1 output" transformation is overkill but also a good way to learn how to use Ant. Assume that the input is input.xml, the stylesheet is transform.xsl, and the output is output.html. A matching Ant 1.5 project file build.xml might look something like

<project default="do-it">
  <target name="do-it">
    <xslt
      processor="trax"in="input.xml"
	  style="transform.xsl"out="output.html"/>
  </target>
</project>

The root element of an Ant build file is project. It can contain a number of target elements. Its default attribute contains the name of the target to build if no targets are given on the command line. Since the example project file defaults to building the target do-it, the output file could be built equally using any of the following command lines:

$ ant 
$ ant do-it 
$ ant -buildfile build.xml 
$ ant -buildfile build.xml do-it

Unlike Unix's make and its clones, which can use filenames for targets, Ant only uses target names defined in the build file. So every target must have a unique name. Within a target, any number of tasks can be performed. The xslt task is included with Ant 1.5. With the processor attribute set to trax, the xslt task uses the default JAXP/TraX XSLT engine to perform the transformation.

A Complex Example

What about a more complicated XSLT workflow, in which there are three input files (in1.xml, in2.xml and in3.xml)? Each of these has the same kind of information, but the formats are different. So they are normalized to a common format by three separate stylesheets (norm1.xsl, norm2.xsl and norm3.xsl respectively). A standard merging stylesheet exists, merge.xsl, but it only merges two inputs (the usual input plus a filename passed as a parameter to the stylesheet). So it has to be used twice in order to merge the three normalized files. The merged sum of the three is sorted to produce the final output file, out.xml.

The following Ant build file does the trick:

<project default="sort">
  <target name="normalize">
    <xslt
      processor="trax"in="in1.xml"style="norm1.xsl"out="nm1.xml"/>
    <xslt
      processor="trax"in="in2.xml"style="norm2.xsl"out="nm2.xml"/>
    <xslt
      processor="trax"in="in3.xml"style="norm3.xsl"out="nm3.xml"/>
  </target>
  <target name="check12">
    <uptodate
      property="skip.merge12"targetfile="m12.xml">
      <srcfiles dir=".">
        <include name="nm1.xml"/>
        <include name="nm2.xml"/>
        <include name="merge.xsl"/>
      </srcfiles>
    </uptodate>
  </target>
  <target
    name="merge12"depends="normalize,check12"unless="skip.merge12">
    <xslt
      processor="trax"in="nm1.xml"style="merge.xsl"out="m12.xml"force="true">
      <param
        name="source2"expression="nm2.xml"/>
    </xslt>
  </target>
  <target name="check123">
    <uptodate
      property="skip.merge123"targetfile="123.xml">
      <srcfiles dir=".">
        <include name="m12.xml"/>
        <include name="nm3.xml"/>
        <include name="merge.xsl"/>
      </srcfiles>
    </uptodate>
  </target>
  <target
    name="merge123"depends="normalize,merge12,check123"unless="skip.merge123">
    <xslt
      processor="trax"in="m12.xml"style="merge.xsl"out="123.xml"force="true">
      <param
        name="source2"expression="nm3.xml"/>
    </xslt>
  </target>
  <target
    name="sort"depends="merge123">
    <xslt
      processor="trax"in="123.xml"style="sort.xsl"out="out.xml"/>
  </target>
  <target name="clean">
    <delete>
      <fileset dir=".">
        <include name="output.html"/>
        <include name="nm*.xml"/>
        <include name="m12.xml"/>
        <include name="123.xml"/>
        <include name="out.xml"/>
      </fileset>
    </delete>
  </target>
</project>

Ant takes account of timestamps on files, just like make. It will not run the transformation unless either the input file or the stylesheet is newer than the output file (which usually means that the input file or the stylesheet has been modified since the last build). So if in1.xml is modified, nm2.xml and nm3.xml will not be rebuilt. Alternatively, if in3.xml is modified, m12.xml will not be rebuilt. This can save a lot of development time is situations where one of the transformations takes much longer than the others.

Some things to note about this Ant project file include:

• The default target is sort. Sorting is the last thing that needs to be done, so making sort the default target means that the whole build process is carried out by default.

• The normalize target is used to run the three normalization stylesheets. Although you could use three separate targets, there is no need, since each xslt task only runs when its output (nm1.xml, nm2.xml, or nm3.xml) needs to be rebuilt.

• The merge.xsl stylesheet is special because one of its input filenames is passed as a stylesheet parameter. There is no way that the standard xslt can know this, so it is necessary to tell Ant explicitly when a rebuild is or is not required. The check12 target uses Ant's uptodate task to check whether m12.xml is newer than nm1.xml, nm2.xml, and merge.xsl. The result is stored in the Ant property skip.merge12.

  The merge12 target is used to merge nm1.xml and nm2.xml, but it only runs when skip.merge12 is false; that is, when m12.xml is not up to date. The xslt task which runs merge.xsl has an extra attribute force, which is set to true to override the default check for whether a rebuild is necessary.

  This complexity comes about purely because a filename has been passed to the stylesheet as a parameter. It is a special case, but one which is not too difficult to solve. The same logic applies to the targets check123 and merge123.

• Finally, the sort target, which is the default target for the project, applies sort.xsl to 123.xml to produce the end result, out.xml.

The files for this project are provided with the zipped examples. You now know everything you need to start using the standard Ant xslt task in your own projects. However, you should also take the time to read the full description of this task in the Ant documentation.

The Difficulty With Multiple XSLT Engines

XSLT stylesheets can provide a good cross-platform solution for manipulating XML, but different platforms use different XSLT engines. Sites that are using the Apache Web server often use Apache Xalan. Sites that are using PHP are likely to use Sablotron. Oracle sites often use the Oracle XDK (as this may be the only XSLT engine that the operations people will allow). Some XML consultants use and recommend Saxon. Microsoft sites generally use MSXML. Although these XSLT engines behave similarly, there are still some differences, so you need to plan to test with all of the XSLT engines that are likely to be used with your XSLT stylesheets. For this article, we will focus on the Java XSLT engines, since they are the ones supported natively by the Ant xslt task.

When testing with multiple engines, it's useful to be able to run the same test using each XSLT engine from within one Ant build file. But there's a problem: the JAXP/Trax interface uses the Java javax.xml.transform.TransformerFactory property to define which class should be instantiated as a factory for creating XSLT engines. In order to use the XSLT engine of your choice, this property needs to be set appropriately. However, there is no easy way to do that within Ant and, hence, no easy way to change XSLT engines within a single Ant build file. The best you can do is to launch a separate Java process and then call Ant from within that new process. To overcome this problem, the best solution is to create a new XSLT task for Ant, one which makes it easy to select the desired XSLT TransformerFactory.

mtxslt - The Solution

mtxslt (short for "multi-XSLT") is an Ant task that makes it easy to select several Java XSLT engines within an Ant build file. mtxslt extends the standard Ant xslt task while maintaining full compatibility with it. Anything that works with the xslt task also works with mtxslt.

With mtxslt, it is possible to ignore the value of the Java javax.xml.transform.TransformerFactory property and simply load a particular XSLT engine directly. mtxslt currently supports Xalan 2, Saxon 6/7, and Oracle XDK 9.

Pages: 1, 2

Next Page