net.sf.saxon.s9api

Class Processor

public class Processor extends Object

The Processor class serves three purposes: it allows global Saxon configuration options to be set; it acts as a factory for generating XQuery, XPath, and XSLT compilers; and it owns certain shared resources such as the Saxon NamePool and compiled schemas. This is the first object that a Saxon application should create. Once established, a Processor may be used in multiple threads.

It is possible to run more than one Saxon Processor concurrently, but only when running completely independent workloads. Nothing can be shared between Processor instances. Within a query or transformation, all source documents and schemas must be built using the same Processor, which must also be used to compile the query or stylesheet.

Constructor Summary
Processor(boolean licensedEdition)
Create a Processor
Processor(Source source)
Create a Processor configured according to the settings in a supplied configuration file.
Method Summary
ObjectgetConfigurationProperty(String name)
Get the value of a configuration property
StringgetSaxonProductVersion()
Get the user-visible Saxon product version, for example "9.0.0.1"
SchemaManagergetSchemaManager()
Get the associated SchemaManager.
ConfigurationgetUnderlyingConfiguration()
Get the underlying Configuration object that underpins this Processor.
StringgetXmlVersion()
Get the version of XML used by this Processor.
booleanisSchemaAware()
Test whether this processor is schema-aware
DocumentBuildernewDocumentBuilder()
Create a DocumentBuilder.
XPathCompilernewXPathCompiler()
Create an XPathCompiler.
XQueryCompilernewXQueryCompiler()
Create an XQueryCompiler.
XsltCompilernewXsltCompiler()
Create an XsltCompiler.
voidregisterExtensionFunction(ExtensionFunctionDefinition function)
Register an extension function that is to be made available within any stylesheet, query, or XPath expression compiled under the control of this processor.
voidsetConfigurationProperty(String name, Object value)
Set a configuration property
voidsetXmlVersion(String version)
Set the version of XML used by this Processor.
voidwriteXdmValue(XdmValue value, Destination destination)
Write an XdmValue to a given destination.

Constructor Detail

Processor

public Processor(boolean licensedEdition)
Create a Processor

Parameters: licensedEdition indicates whether the Processor requires features of Saxon that need a license file (that is, features not available in Saxon HE (Home Edition). If true, the method will look for a valid license file and instantiate a Configuration appropriate to the features that have been licensed, that is, a ProfessionalConfiguration or EnterpriseConfiguration. If no suitable license is found, the method falls back to creating an HE configuration (which is also the effect if the argument is set to false.)

Processor

public Processor(Source source)
Create a Processor configured according to the settings in a supplied configuration file.

Parameters: source the Source of the configuration file

Throws: SaxonApiException if the configuration file cannot be read, or its contents are invalid

Since: 9.2

Method Detail

getConfigurationProperty

public Object getConfigurationProperty(String name)
Get the value of a configuration property

Parameters: name the name of the option required. The names of the properties available are listed as constants in class FeatureKeys.

Returns: the value of the property, if one is set; or null if the property is unset and there is no default.

Throws: IllegalArgumentException if the property name is not recognized

getSaxonProductVersion

public String getSaxonProductVersion()
Get the user-visible Saxon product version, for example "9.0.0.1"

Returns: the Saxon product version, as a string

getSchemaManager

public SchemaManager getSchemaManager()
Get the associated SchemaManager. The SchemaManager provides capabilities to load and cache XML schema definitions. There is exactly one SchemaManager in a schema-aware Processor, and none in a Processor that is not schema-aware. The SchemaManager is created automatically by the system.

Returns: the associated SchemaManager, or null if the Processor is not schema-aware.

getUnderlyingConfiguration

public Configuration getUnderlyingConfiguration()
Get the underlying Configuration object that underpins this Processor. This method provides an escape hatch to internal Saxon implementation objects that offer a finer and lower-level degree of control than the s9api classes and methods. Some of these classes and methods may change from release to release.

Returns: the underlying Configuration object

getXmlVersion

public String getXmlVersion()
Get the version of XML used by this Processor. If the value is "1.0", then input documents must be XML 1.0 documents, and output documents will be serialized as XML 1.0. This option also affects the characters permitted to appear in queries and stylesheets, and the characters that can appear in names (for example, in path expressions).

Returns: one of the strings "1.0" or "1.1"

isSchemaAware

public boolean isSchemaAware()
Test whether this processor is schema-aware

Returns: true if this is a schema-aware processor, false otherwise

newDocumentBuilder

public DocumentBuilder newDocumentBuilder()
Create a DocumentBuilder. A DocumentBuilder is used to load source XML documents.

Returns: a newly created DocumentBuilder

newXPathCompiler

public XPathCompiler newXPathCompiler()
Create an XPathCompiler. An XPathCompiler is used to compile XPath expressions.

Returns: a newly created XPathCompiler

newXQueryCompiler

public XQueryCompiler newXQueryCompiler()
Create an XQueryCompiler. An XQueryCompiler is used to compile XQuery queries.

Returns: a newly created XQueryCompiler

Throws: UnsupportedOperationException if this version of the Saxon product does not support XQuery processing

newXsltCompiler

public XsltCompiler newXsltCompiler()
Create an XsltCompiler. An XsltCompiler is used to compile XSLT stylesheets.

Returns: a newly created XsltCompiler

Throws: UnsupportedOperationException if this version of the Saxon product does not support XSLT processing

registerExtensionFunction

public void registerExtensionFunction(ExtensionFunctionDefinition function)
Register an extension function that is to be made available within any stylesheet, query, or XPath expression compiled under the control of this processor. This method registers an extension function implemented as an instance of ExtensionFunctionCall, using an arbitrary name and namespace. This supplements the ability to call arbitrary Java methods using a namespace and local name that are related to the Java class and method name.

Parameters: function the class that implements the extension function. This must be a class that extends ExtensionFunctionCall, and it must have a public zero-argument constructor

Throws: IllegalArgumentException if the class cannot be instantiated or does not extend ExtensionFunctionCall

Since: 9.2

setConfigurationProperty

public void setConfigurationProperty(String name, Object value)
Set a configuration property

Parameters: name the name of the option to be set. The names of the options available are listed as constants in class FeatureKeys. value the value of the option to be set.

Throws: IllegalArgumentException if the property name is not recognized

setXmlVersion

public void setXmlVersion(String version)
Set the version of XML used by this Processor. If the value is set to "1.0", then output documents will be serialized as XML 1.0. This option also affects the characters permitted to appear in queries and stylesheets, and the characters that can appear in names (for example, in path expressions).

Note that source documents specifying xml version="1.0" or "1.1" are accepted regardless of this setting.

Parameters: version must be one of the strings "1.0" or "1.1"

Throws: IllegalArgumentException if any string other than "1.0" or "1.1" is supplied

writeXdmValue

public void writeXdmValue(XdmValue value, Destination destination)
Write an XdmValue to a given destination. The sequence represented by the XdmValue is "normalized" as defined in the serialization specification (this is equivalent to constructing a document node in XSLT or XQuery with this sequence as the content expression), and the resulting document is then copied to the destination. If the destination is a serializer this has the effect of serializing the sequence as described in the W3C specifications.

Parameters: value the value to be written destination the destination to which the value is to be written