Configuration interfaces

At the heart of Saxon is the object net.sf.saxon.Configuration. 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, com.saxonica.config.ProfessionalConfiguration and com.saxonica.config.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.

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().

The most general mechanism for getting and setting configuration properties, however, is provided by the methods getConfigurationProperty(Feature) and setConfigurationProperty(Feature, value). In these methods the property to be read or written is identified by a net.sf.saxon.lib.Feature object, typically one of the objects defined as static constants, for example Feature.ALLOW_EXTERNAL_FUNCTIONS. The Feature object is also parameterized by the type of value required, for example Feature.ALLOW_EXTERNAL_FUNCTIONS is a Feature<Boolean>. Internally, the Feature object defines both a unique integer code for the feature, and a unique string in the form of a URI (for example, "http://saxon.sf.net/feature/allowExternalFunctions"). In some interfaces, for example the JAXP TransformerFactory, configuration options are identified by strings, and the required strings can be accessed using the name property of the Feature, for example net.sf.saxon.lib.Feature.ALLOW_EXTERNAL_FUNCTIONS.name. For backwards compatibility reasons, these strings are also available as constants in the class net.sf.saxon.lib.FeatureKeys.

On command line interfaces such as net.sf.saxon.Transform, configuration 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.

For backwards compatibility, the Configuration class continues to support the methods getConfigurationProperty(name) and setConfigurationProperty(name, value). In these methods the name of the configuration property is always a string in the form of a URI (for example, "http://saxon.sf.net/feature/initialTemplate"), and the strings available are all defined by constants in the class net.sf.saxon.lib.FeatureKeys (for example, FeatureKeys.INITIAL_TEMPLATE). The value is of various types depending on the property. In the vast majority of cases, the property can be supplied as a string, or it has an alternative, equivalent property that can be supplied as a string. For properties that are essentially boolean in nature the value can be supplied either as one of the Java constants Boolean.TRUE or Boolean.FALSE, or as one of the strings "true", "1", "yes", "on", or "false", "0", "no", "off". These choices are designed to suit the conventions of different APIs in which the configuration options are exposed.

In many APIs for controlling Saxon activities, the Configuration object is not exposed directly, but is hidden below some similar object acting as the root object for that particular API. Many of these objects provide a direct way to set the configuration options. These are discussed in the following sections.