All the various APIs for invoking Saxon functionality start by creating a top-level object holding all the resources held by the application as a whole, and providing factory mechanisms for instantiating particular functionality and configuring its properties. These classes include the following:
|JAXP Schema Validation||
|JAXP XPath Evaluator||
In each case this top-level class encapsulates the class net.sf.saxon.Configuration (in Java)
Saxon.Hej.Configuration (C#). This contains all the current
settings of configuration options. All Saxon tasks, such as compiling and running queries and transformations, or building and validating source
documents, happen under the control of a
Configuration. Many resources are owned by the
Configuration, meaning that related
tasks must run under the same
Configuration. Most notably, the
Configuration holds a NamePool, which is a table allocating integer codes to the qualified names that appear in stylesheets, queries,
schemas, and source documents, and during the execution of a stylesheet or query all the resources used (for example, the stylesheet, all its input
documents, and any schemas it uses) must all use the same
NamePool to ensure that they all use the same integer codes for the same
qualified names. However, two Saxon tasks that are unrelated can run under different
There are subclasses of
Configuration containing resources associated with the capabilities of the different Saxon editions: specifically,
ProfessionalConfiguration and EnterpriseConfiguration. In many cases the
used as a factory class to deliver services associated with the different capability levels, for example the method
the query optimizer appropriate to the loaded Saxon edition.
Most applications will manipulate the configuration via the public API in the top-level processing class (for example
the s9api or Saxon.Api
Processor class); but applications wanting to take full advantage of Saxon's capabilities
will often find themselves exposing the lower-level
In the s9api interface on Java, configuration options can be set using a method call such as
processor.setConfigurationFeature(Feature.LINE_NUMBERING, true). The method definition uses Java
generics to ensure that the supplied property value is of the correct type for the selected feature.
In the Saxon.Api interface for C#, configuration options can be set using a method call such as
processor.SetProperty(Feature<bool>.LINE_NUMBERING, true). It's necessary to specify
the type of the value (here
bool) to make the method type-safe. There is also a method that accepts
the feature name as a string, for example
in this case the value must also be supplied as a string.
It's also possible to set the same properties by using lower-level methods on the
object itself. The properties all have names in the form of URIs (for example
and these names are useful when a property has to be set via an API that expects property names as strings (for example the
TransformerFactory). When boolean values need to be supplied as strings, Saxon accepts the values
"1" to represent true, and
"0" to represent false.
Many configuration options have direct setter and getter methods on the
Configuration object, for example
isAllowExternalFunctions(). Some other options have setters and getters on objects
reachable from the
Configuration, for example defaults for XSLT processing can be controlled using methods such as
getDefaultXsltCompilerInfo().setXsltVersion(), while defaults for XQuery processing can be controlled using methods such as
On command line interfaces such as
net.sf.saxon.Transform, there are several ways
of setting configuration options:
Some options have dedicated command-line arguments, for example
-tto switch on high-level progress messages.
Many options can be supplied using the form
nameis the part of the URI after the final "/", for example
allowExternalFunctions, and the
valuemust be supplied as a string. In such cases, and in other cases where values must be supplied as strings (for example the
xslt/factory/attributeelement in Ant), Saxon accepts the strings "true", "1", "yes", "on", or "false", "0", "no", "off", to represent booleans.
Options can be included in a configuration file, referenced on the command line using the option
-config:filename: for details see Configuration file.
-init:callbackallows reference to user-written code that is called to initialize the configuration programatically.
For SaxonJ, the value is the name of a user-written class that implements the interface net.sf.saxon.lib.Initializer.
For SaxonCS, the value is the filename of an assembly that contains a class that implements the interface Saxon.Api.IProcessorInitializer.
Sometimes Saxon is deeply embedded in some third-party application that
does not expose configuration interfaces, for example interfaces needed to enable the use
of Saxon extensions in a stylesheet or query. For this scenario, Saxon recognizes the
Java system property
SAXON_INITIALIZER: this may be set to the name of a user-written class
that implements the interface
net.sf.saxon.lib.Initializer, which is called when
Configuration is created.