Configuration interfaces

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:

In each case this top-level class encapsulates the class net.sf.saxon.Configuration (in Java) or 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 Configuration objects.

There are subclasses of Configuration containing resources associated with the capabilities of the different Saxon editions: specifically, ProfessionalConfiguration and EnterpriseConfiguration. In many cases the Configuration is used as a factory class to deliver services associated with the different capability levels, for example the method getOptimizer() returns 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 Configuration object.

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 processor.SetProperty("http://saxon.sf.net/feature/linenumbering", "true"); 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 Configuration object itself. The properties all have names in the form of URIs (for example "http://saxon.sf.net/feature/linenumbering"), and these names are useful when a property has to be set via an API that expects property names as strings (for example the JAXP TransformerFactory). When boolean values need to be supplied as strings, Saxon accepts the values "true", "on", "yes", and "1" to represent true, and "false", "off", "no", and "0" to represent false.

Many configuration options have direct setter and getter methods on the Configuration object, for example setAllowExternalFunctions() and 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 getDefaultStaticQueryContext().setLanguageVersion().

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 -t to switch on high-level progress messages.

• Many options can be supplied using the form --name:value. Here name is the part of the URI after the final "/", for example allowExternalFunctions, and the value must be supplied as a string. In such cases, and in other cases where values must be supplied as strings (for example the xslt/factory/attribute element 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.

• The option -init:callback allows 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 a Saxon Configuration is created.