Package net.sf.saxon.s9api

Class Processor

java.lang.Object
net.sf.saxon.s9api.Processor
All Implemented Interfaces:
Configuration.ApiProvider
public class Processor extends Object implements Configuration.ApiProvider
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.

Internally, the Processor is a wrapper around a Saxon Configuration object, and the underlying Configuration is available via the getUnderlyingConfiguration() method. This exposes additional Saxon functionality; however, the details may be subject to change from one release to the next.

  • Constructor Details

    • Processor

      public Processor()
      Create a Processor according to the capabilities available.

      This will examine what software is installed, and whether or not a license key is available, and return the most capable configuration available within these constraints. For example if the software is Saxon-EE but the license only allows PE capability, it will return a processor with Saxon-PE capabilities.

      Since:
      12.0

    • Processor

      public Processor(boolean licensedEdition)
      Create a Processor, specifying whether a licensed configuration is required
      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 create a Configuration appropriate to the version of the software that is running: for example, if running Saxon-EE, it will create an EnterpriseConfiguration. The method does not at this stage check that a license is available, and in the absence of a license, it should run successfully provided no features that require licensing are actually used. If the argument is set to false, a plain Home Edition Configuration is created unconditionally.

    • Processor

      public Processor(Configuration config)
      Create a Processor based on an existing Configuration. This constructor is useful when new components of an application are to use s9api interfaces but existing components use older interfaces (for example, JAXP). It is also useful in cases where, for example, multiple configurations need to be built using the same configuration file or sharing license data: in such cases, the Configuration can be manually built, and then wrapped in a Processor.
      Parameters:
      config - the Configuration to be used by this Processor
      Since:
      9.3

    • Processor

      public Processor(Source source) throws SaxonApiException
      Create a Processor configured according to the settings in a supplied configuration file.
      Parameters:
      source - the Source of the configuration file (which is an XML document)
      Throws:
      SaxonApiException - if the configuration file cannot be read, or its contents are invalid
      Since:
      9.2

  • Method Details

    • newDocumentBuilder

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

    • newJsonBuilder

      public JsonBuilder newJsonBuilder()
      Create a JsonBuilder. A JsonBuilder is used to load source JSON documents.
      Returns:
      a newly created JsonBuilder
      Since:
      11

    • newXPathCompiler

      public XPathCompiler newXPathCompiler()
      Create an XPathCompiler. An XPathCompiler is used to compile XPath expressions.
      Returns:
      a newly created XPathCompiler

    • newXsltCompiler

      public XsltCompiler newXsltCompiler()
      Create an XsltCompiler. An XsltCompiler is used to compile XSLT stylesheets.
      Returns:
      a newly created XsltCompiler

    • newXQueryCompiler

      public XQueryCompiler newXQueryCompiler()
      Create an XQueryCompiler. An XQueryCompiler is used to compile XQuery queries.
      Returns:
      a newly created XQueryCompiler

    • newSerializer

      public Serializer newSerializer()
      Create a Serializer. A Serializer is a Destination for processes such as XSLT transformation, that renders the output as a readable file.
      Returns:
      a new Serializer
      Since:
      9.3

    • newSerializer

      public Serializer newSerializer(OutputStream stream)
      Create a Serializer initialized to write to a given OutputStream.

      Closing the output stream after use is the responsibility of the caller.

      Parameters:
      stream - The OutputStream to which the Serializer will write
      Returns:
      a new Serializer
      Since:
      9.3

    • newSerializer

      public Serializer newSerializer(Writer writer)
      Create a Serializer initialized to write to a given Writer.

      Closing the writer after use is the responsibility of the caller.

      Parameters:
      writer - The Writer to which the Serializer will write
      Returns:
      a new Serializer
      Since:
      9.3

    • newSerializer

      public Serializer newSerializer(File file)
      Create a Serializer initialized to write to a given File.
      Parameters:
      file - The File to which the Serializer will write
      Returns:
      a new Serializer
      Since:
      9.3

    • newPush

      public Push newPush(Destination destination) throws SaxonApiException
      Get a new Push provider. The returned Push object allows the client application to construct events (such as startElement(), text(), and endElement()) and send them to a specified Destination.
      Parameters:
      destination - the destination
      Returns:
      a new recipient of Push events.
      Throws:
      SaxonApiException - if the Destination is not able to handle the request.

    • registerExtensionFunction

      public void registerExtensionFunction(ExtensionFunction function)
      Register a simple external/extension function that is to be made available within any stylesheet, query, or XPath expression compiled under the control of this processor.

      This interface provides only for simple extension functions that have no side-effects and no dependencies on the static or dynamic context.

      Parameters:
      function - the implementation of the extension function.
      Since:
      9.4

    • 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 ExtensionFunctionDefinition, using an arbitrary name and namespace.

      This interface allows extension functions that have dependencies on the static or dynamic context. It also allows an extension function to declare that it has side-effects, in which case calls to the function will be optimized less aggressively than usual, although the semantics are still to some degree unpredictable.

      Parameters:
      function - the implementation of the extension function.
      Since:
      9.2

    • newXsdCompiler

      public XsdCompiler newXsdCompiler()
      Create an XsdCompiler. This provides capabilities to load XML schema definitions.
      Returns:
      a new XsdCompiler, provided the Saxon configuration is a licensed Saxon-EE configuration. In other cases, the method throws an exception.
      Throws:
      UnsupportedOperationException - if this is not a licensed Saxon-EE configuration.
      Since:
      13.0.

    • getSchemaManager

      @Deprecated public SchemaManager getSchemaManager()
      Deprecated.
      since 13.0. Use newXsdCompiler().
      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.

      The SchemaManager is retained in Saxon 13 to provide a degree of compatibility with older releases. However, the model of schema processing has changed. In previous releases, all compiled schema information was held globally in the Configuration (that is, at the level of the Processor. From Saxon 13, schemas are more modular, which means that it becomes an application responsibility to ensure that the correct schema is used for each aspect of processing. To take advantage of this flexibility, use of the central SchemaManager should be replaced with the XsdCompiler.

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

    • isSchemaAware

      public boolean isSchemaAware()
      Test whether this processor is schema-aware
      Returns:
      true if this processor is licensed for schema processing, false otherwise

    • 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

    • getSaxonEdition

      public String getSaxonEdition()
      Get the short name of the Saxon product edition, for example "EE". This represents the kind of configuration that has been created, rather than the software that has been installed; for example it is possible to instantiate an "HE" configuration even when using the "PE" or "EE" software.
      Returns:
      the Saxon edition code: "EE", "PE", or "HE"

    • 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

    • 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"

    • setConfigurationProperty

      public void setConfigurationProperty(String name, Object value)
      Set a configuration property. This method is useful when it is necessary to identify configuration properties by name; however, the method setConfigurationProperty(Feature, Object) is preferred because it is more efficient and offers better type safety.
      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 or if the supplied value is not a valid value for the named property.

    • getConfigurationProperty

      @Deprecated public Object getConfigurationProperty(String name)
      Deprecated.
      since 9.9 - use getConfigurationProperty(Feature)
      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

    • setConfigurationProperty

      public <T> void setConfigurationProperty(Feature<T> feature, T value)
      Set a configuration property
      Type Parameters:
      T - the type of the value required by the feature (often boolean or string)
      Parameters:
      feature - the option to be set. The names of the options available are listed as constants in class Feature.
      value - the value of the option to be set (which must be of the appropriate type for the particular feature.
      Throws:
      IllegalArgumentException - if the supplied value is not a valid value for the selected feature.
      Since:
      9.9 introduced to give a faster and type-safe alternative to setConfigurationProperty(String, Object)

    • getConfigurationProperty

      public <T> T getConfigurationProperty(Feature<T> feature)
      Get the value of a configuration property
      Type Parameters:
      T - the type of the feature (often boolean or string)
      Parameters:
      feature - the option required. The names of the properties available are listed as constants in class Feature.
      Returns:
      the value of the property, if one is set; or null if the property is unset and there is no default.
      Since:
      9.9 introduced to give a faster and type-safe alternative to getConfigurationProperty(String)

    • declareCollation

      public void declareCollation(String uri, Comparator<? super String> collation)
      Bind a collation URI to a collation
      Parameters:
      uri - the absolute collation URI
      collation - a Comparator object that implements the required collation
      Throws:
      IllegalArgumentException - if an attempt is made to rebind the standard URI for the Unicode codepoint collation or the HTML5 case-blind collation
      Since:
      9.6. Changed in 9.8 to allow any Comparator to be supplied as a collation

    • registerCollection

      public void registerCollection(String collectionURI, ResourceCollection collection)
      Register a specific URI and bind it to a specific ResourceCollection. A collection that is registered in this way will be returned prior to calling any registered CollectionFinder. This method should only be used while the configuration is being initialized for use; the effect of adding or replacing collections dynamically while a configuration is in use is undefined.

      Registered collections take priority over any user-supplied CollectionFinder; if a collection URI has been registered, then it is used before the user-supplied CollectionFinder is invoked.

      Parameters:
      collectionURI - the collection URI to be registered. Must not be null.
      collection - the ResourceCollection to be associated with this URI. Must not be null.
      Since:
      11.0

    • setCatalogFiles

      public void setCatalogFiles(String... fileNames)
      Supply one or more resource catalog files to be used for URI resolution.

      The call has no effect if the CommonResourceResolver registered with the Configuration does not use catalog files.

      Parameters:
      fileNames - the files to be used. If no files are supplied, the call removes any existing catalog files that were previously registered.

    • 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

    • writeXdmValue

      public void writeXdmValue(XdmValue value, Destination destination) throws SaxonApiException
      Write an XdmValue to a given destination.

      If the destination is a Serializer then the method processor.writeXdmValue(V, S) is equivalent to calling S.serializeXdmValue(V).

      In other cases, 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. Note that the construction of a document tree will fail if the sequence contains items such as maps and arrays.

      Parameters:
      value - the value to be written
      destination - the destination to which the value is to be written
      Throws:
      SaxonApiException - if any failure occurs, for example a serialization error

    • getLegacySchema

      protected XsdSchema getLegacySchema()
      Get any schema that has been created using the now-deprecated SchemaManager API
      Returns:
      any schema that has been created using the SchemaManager API, or null if absent