Running Saxon XSLT Transformations from Ant
It is possible to run a Saxon transformation from Ant using the standard xslt task, by
using the trax
processor and with an appropriate classpath
that
forces Saxon to be selected. This can now be used to provide the ability to take advantage
of the full range of capabilities offered by XSLT 3.0 in general and Saxon in particular
(for example, schema aware processing and multiple output files).
To ensure that Saxon is the chosen XSLT processor it is safest to use the <factory name="factory-class">
element in the the Ant task. The relevant factory classes are:
-
net.sf.saxon.TransformerFactory
for Saxon-HE -
com.saxonica.config.ProfessionalTransformerFactory
for Saxon-HE -
com.saxonica.config.EnterpriseTransformerFactory
for Saxon-EE -
com.saxonica.config.StreamingTransformerFactory
for a streaming transformation in Saxon-EE. Note that if this option is selected, the global context item for the transformation (used when a global variable initializer references the context item) will be absent, so any reference to "." in a global variable throws an error.
Saxon-specific configuration options can be specified using the attribute
child of the factory
element. For example, the following switches on Saxon
tracing (the equivalent of the -T
option on the command line):
For a full list of feature names, see Configuration Features or the Javadoc documentation of class net.sf.saxon.lib.FeatureKeys.
A particularly useful feature for use with Ant is
http://saxon.sf.net/feature/ignoreSAXSourceParser
. When Ant invokes Saxon,
it normally does so supplying a SAXSource
object with a contained
XMLReader
. Saxon will not normally change the properties of an
XMLReader
supplied by the application. However, allowing Saxon to supply
its own XMLReader
can be much more efficient, especially in the case where
there are references to W3C-defined HTML or SVG DTD and entity files: Saxon has internal
copies of these files, but can only use them if it is allowed to configure the parser
accordingly. Setting this property authorises Saxon to ignore the parser supplied by Ant
and use its own.
It is possible to get detailed control of the configuration by specifying the name of a Saxon configuration file using this mechanism, for example:
<factory name="com.saxonica.config.EnterpriseTransformerFactory"> <attribute name="http://saxon.sf.net/feature/configuration-file" value="config-de.xml"/> </factory>In this case this must be the first attribute.
The initial template and initial mode for the transformation can be specified using the
attribute names http://saxon.sf.net/feature/initialTemplate
and
http://saxon.sf.net/feature/initialMode
respectively. The value is a QName
in Clark notation (that is {uri}local
).
Note that names in Clark notation may also be used for the qualified names of stylesheet parameters and serialization options.
Note that an Ant transformation always has an input file. If necessary, a dummy file can be specified.
There is a history of bugs in successive releases of Ant that mean not all these features
work in every Ant version. In particular, the classpath
attribute of the
xslt
task element has been unreliable: the safest approach is to ensure
that the Jar files needed to run Saxon are present on the externally-specified classpath
(the classpath at the point where Ant is invoked), rather than relying on the task-specific
classpath.