Saxon.Api

 

 

Saxon.Api

Class Processor

public class Processor
extends net.sf.saxon.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. Most applications should only create one Processor object. Once established, a Processor may be used in multiple threads.

Constructor Summary
Processor ()

Create a new SaxonCS Processor. This Processor will have capabilities that depend on the version of the software that has been loaded, and on the features that have been licensed.

Processor (bool licensedEdition)

Create a Processor.

Processor (Stream configurationFile)

Deprecated Use the Processor(Stream, Uri) constructor instead.
Processor (Stream configurationFile, Uri baseUri)

Create a Processor, based on configuration information supplied in a configuration file.

Processor (net.sf.saxon.Configuration config)

Create a Processor, wrapping an existing instance of the internal Saxon class Configuration

 

Property Summary
 CollectionFinder CollectionFinder

A used-supplied function that is used to retrieve a resource collection given a collection URI.

 string Edition

Get the Saxon product edition (for example, "EE" for Enterprise Edition)

 TextWriter ErrorWriter

A TextWriter used as the destination of miscellaneous error, warning, and progress messages.

 net.sf.saxon.Configuration Implementation

The underlying Configuration object in the Saxon implementation

 string ProductTitle

Get the full name of the Saxon product version implemented by this Processor

 string ProductVersion

Get the Saxon product version number (for example, "9.2.0.2")

 SchemaManager SchemaManager

Gets the SchemaManager for this Processor.

 CollectionFinder StandardCollectionFinder

The standard (built-in) collection finder that is used by default if no user-defined collection finder has been supplied. This is exposed as a property of the Processor so that it can be invoked by a user-written collection finder.

 decimal XmlVersion

The XML version used in this Processor

 

Method Summary
 void DeclareCollation (Uri uri, CompareInfo compareInfo, CompareOptions options)

Create a collation based on a given CompareInfo and CompareOptions

 string GetMediaTypeForFileExtension (string extension)

Get the media type to be associated with a file extension by the standard collection handler

 string GetProperty (string name)

Get the value of a configuration property

 object GetProperty (Feature feature)

Get a property of the configuration.

 XdmFunctionItem GetSystemFunction (QName name, int arity)

Get the system function with a given name and arity

 DocumentBuilder NewDocumentBuilder ()

Create a new DocumentBuilder, which may be used to build XDM documents from a variety of XML-based sources.

 JsonBuilder NewJsonBuilder ()

Create a new JsonBuilder, which may be used to build XDM instances from input in JSON format.

 Serializer NewSerializer ()

Create a Serializer

 Serializer NewSerializer (TextWriter textWriter)

Create a Serializer initialized to write to a given TextWriter. Closing the writer after use is the responsibility of the caller.

 Serializer NewSerializer (Stream stream)

Create a Serializer initialized to write to a given output Stream. Closing the output stream after use is the responsibility of the caller.

 XPathCompiler NewXPathCompiler ()

Create a new XPathCompiler, which may be used to compile XPath expressions.

 XQueryCompiler NewXQueryCompiler ()

Create a new XQueryCompiler, which may be used to compile XQuery queries.

 XsltCompiler NewXsltCompiler ()

Create a new XsltCompiler, which may be used to compile XSLT stylesheets.

 XdmItemType ParseItemType (string input)

Construct an XdmItemType object by parsing an item type definition in XPath syntax

 XdmSequenceType ParseSequenceType (string input)

Construct an XdmSequenceType object by parsing a sequence type definition in XPath syntax

 void RegisterCollection (Uri collectionUri, IEnumerable<IResource> collection)

Register a specific collection URI

 void RegisterExtensionFunction (ExtensionFunctionDefinition function)

Register an extension function with the Processor. This interface provides rich capability for defining extension functions with complex requirements, for example accessing information in the static and dynamic context, and declaring the presence of side-effects. For simpler extension functions use an ExtensionFunction in preference.

 void RegisterExtensionFunction (QName name, XdmItemType type, Func 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

 void RegisterFileExtension (string extension, string mediaType)

Set the media type to be associated with a file extension by the standard collection handler

 void SetCatalogFiles (string[] fileNames)

Set one or more catalog files to be used for resolving URIs

 void SetProperty (string name, string value)

Set a configuration property

 void SetProperty (Feature feature, object value)

Set a configuration property. This method provides a type-safe way of setting properties of any type: for example a boolean property can be set by calling SetProperty(Feature<bool>.ALLOW_SYNTAX_EXTENSIONS, true).

 void SetResourceResolver (ResourceResolver resolver, bool combine)

Set a resource resolver to be used to resolve URIs referring to external resources.

 void WriteXdmValue (XdmValue sequence, IDestination destination)

Copy an XdmValue to an XmlDestination

 

Constructor Detail

Processor

public Processor()

Create a new SaxonCS Processor. This Processor will have capabilities that depend on the version of the software that has been loaded, and on the features that have been licensed.

Processor

public Processor(bool licensedEdition)

Create a Processor.

Parameters:

licensedEdition - Must be set to true (kept for future use).

Processor

public Processor(Stream configurationFile)

Deprecated Use the Processor(Stream, Uri) constructor instead.

Create a Processor, based on configuration information supplied in a configuration file.

Parameters:

configurationFile - A stream holding the text of the XML configuration file. Details of the file format can be found in the Saxon documentation.

Processor

public Processor(Stream configurationFile,
                 Uri baseUri)

Create a Processor, based on configuration information supplied in a configuration file.

Parameters:

configurationFile - A stream holding the text of the XML configuration file. Details of the file format can be found in the Saxon documentation.
baseUri - baseUri of the configuration file used for resolving any relative URIs in the file

Throws:

SaxonApiException - if the configuration file is invalid or sets properties not available in this Saxon version

Processor

public Processor(net.sf.saxon.Configuration config)

Create a Processor, wrapping an existing instance of the internal Saxon class Configuration

This method can be used to create two Processor objects that share the same underlying Configuration, though this is not usually advisable, because most changes to one Processor actually modify the Configuration and hence affect the other Processor.

As an alternative to this method, consider using the Processor that was originally used to construct the Configuration, which will often be available via Configuration.getProcessor().

Parameters:

config - The Configuration to be wrapped.

Property Detail

CollectionFinder

public CollectionFinder CollectionFinder {get; set; }

A used-supplied function that is used to retrieve a resource collection given a collection URI.

If no collection finder is supplied, then the built-in collection finder is used. The built-in collection finder recognizes various kinds of collection including directory collections and catalog collections. A user-defined collection finder can delegate to the built-in collection finder by invoking the function available as Processor.StandardCollectionFinder.

A collection finder should be set only while the processor is being initialized; the effect of changing the collection finder (or changing any data on which it depends) while queries or transformations are in progress is undefined.

The collection finder returns a set of IResource objects. Typically a used-defined class implementing IResource is used. An IResource has a resource URI, a content type (MIME or media type), and a method to deliver the resource content as an XdmItem. Typically fetching the resource over the network, and parsing it according to the rules of the relevant content type, is delayed until the GetXdmItem method is called.

For deterministic results, and for W3C conformance, it is recommended that the supplied function should be deterministic: repeated calls for the same collection URI should deliver the same set of resources. However, this requirement can lead to high memory requirements, so Saxon does not enforce it.

The CollectionFinder registered with a processor is available to all queries and stylesheets running under the control of that processor.

Edition

public string Edition {get; }

Get the Saxon product edition (for example, "EE" for Enterprise Edition)

ErrorWriter

public TextWriter ErrorWriter {get; set; }

A TextWriter used as the destination of miscellaneous error, warning, and progress messages.

By default the Console.Error is used for all such messages.

A user can supply their own TextWriter to redirect error messages from the standard output.

Implementation

public net.sf.saxon.Configuration Implementation {get; }

The underlying Configuration object in the Saxon implementation

This property provides access to internal methods in the Saxon engine that are not specifically exposed in the SaxonCS API. In general these methods should be considered to be less stable than the classes in the Saxon.Api namespace.

The internal methods follow Java naming conventions rather than .NET conventions.

Information about the returned net.sf.saxon.Configuration object (and the objects it provides access to) is included in the Saxon JavaDoc documentation.

ProductTitle

public string ProductTitle {get; }

Get the full name of the Saxon product version implemented by this Processor

ProductVersion

public string ProductVersion {get; }

Get the Saxon product version number (for example, "9.2.0.2")

SchemaManager

public SchemaManager SchemaManager {get; }

Gets the SchemaManager for this Processor.

StandardCollectionFinder

public CollectionFinder StandardCollectionFinder {get; }

The standard (built-in) collection finder that is used by default if no user-defined collection finder has been supplied. This is exposed as a property of the Processor so that it can be invoked by a user-written collection finder.

XmlVersion

public decimal XmlVersion {get; set; }

The XML version used in this Processor

The value must be 1.0 or 1.1, as a decimal. The default version is currently 1.0, but may change in the future.

Method Detail

DeclareCollation

public void DeclareCollation(Uri uri,
CompareInfo compareInfo,
CompareOptions options)

Create a collation based on a given CompareInfo and CompareOptions

Parameters:

uri - The collation URI to be used within an XPath expression to refer to this collation
compareInfo - The CompareInfo, which determines the language-specific collation rules to be used
options - Options to be used in performing comparisons, for example whether they are to be case-blind and/or accent-blind

GetMediaTypeForFileExtension

public string GetMediaTypeForFileExtension(string extension)

Get the media type to be associated with a file extension by the standard collection handler

Parameters:

extension - the file extension, for example "xml". The value "" gets the default media type to be used for unregistered file extensions. The default media type is also returned if the supplied file extension is not registered

Returns:

the corresponding media type, for example "application/xml". The choice of media type determines how a resource with this extension gets parsed, when the file appears as part of a collection.

GetProperty

public string GetProperty(string name)

Get the value of a configuration property

This method provides the ability to get named properties of the configuration. The property names are supplied as strings, whose values can be found in the Java class net.sf.saxon.lib.FeatureKeys. The property values are always returned as strings. Properties whose values are other types are returned by converting the value to a string. Note that on/off properties are returned using the strings "true" and "false".

Method added in Saxon 9.1

Parameters:

name - The property name

Returns:

The property value, as a string; or null if the property is unset.

GetProperty

public object GetProperty(Feature feature)

Get a property of the configuration.

In earlier versions of SaxonCS this method attempted to achieve type-safety by returning a generic type. This has been abandoned - see bug 5183

Parameters:

feature - the required property.

Returns:

the value of the property

GetSystemFunction

public XdmFunctionItem GetSystemFunction(QName name,
int arity)

Get the system function with a given name and arity

Parameters:

name - The required function name
arity - The required arity

Returns:

The system function if it exists, or null otherwise

NewDocumentBuilder

public DocumentBuilder NewDocumentBuilder()

Create a new DocumentBuilder, which may be used to build XDM documents from a variety of XML-based sources.

Returns:

A new DocumentBuilder

NewJsonBuilder

public JsonBuilder NewJsonBuilder()

Create a new JsonBuilder, which may be used to build XDM instances from input in JSON format.

Returns:

A new JsonBuilder

NewSerializer

public Serializer NewSerializer()

Create a Serializer

Returns:

a new Serializer

NewSerializer

public Serializer NewSerializer(TextWriter textWriter)

Create a Serializer initialized to write to a given TextWriter. Closing the writer after use is the responsibility of the caller.

Parameters:

textWriter - The TextWriter to which the Serializer will write

Returns:

a new Serializer

NewSerializer

public Serializer NewSerializer(Stream stream)

Create a Serializer initialized to write to a given output Stream. Closing the output stream after use is the responsibility of the caller.

Parameters:

stream - The output Stream to which the Serializer will write

Returns:

a new Serializer

NewXPathCompiler

public XPathCompiler NewXPathCompiler()

Create a new XPathCompiler, which may be used to compile XPath expressions.

The returned XPathCompiler retains a live link to the Processor, and may be affected by subsequent changes to the Processor.

Returns:

A new XPathCompiler

NewXQueryCompiler

public XQueryCompiler NewXQueryCompiler()

Create a new XQueryCompiler, which may be used to compile XQuery queries.

The returned XQueryCompiler retains a live link to the Processor, and may be affected by subsequent changes to the Processor.

Returns:

A new XQueryCompiler

NewXsltCompiler

public XsltCompiler NewXsltCompiler()

Create a new XsltCompiler, which may be used to compile XSLT stylesheets.

The returned XsltCompiler retains a live link to the Processor, and may be affected by subsequent changes to the Processor.

Returns:

A new XsltCompiler

ParseItemType

public XdmItemType ParseItemType(string input)
throws
SaxonApiException

Construct an XdmItemType object by parsing an item type definition in XPath syntax

Experimental XPath 4.0 syntax is accepted provided that the configuration feature XQUERY_VERSION is set to "4.0"

Parameters:

input - The input string, in XPath syntax (for example array(xs:integer)). The only namespace prefix recognized is "xs", representing the XML Schema namespace.

Throws:

SaxonApiException - If the syntax of the input is invalid, or if there are references to undeclared schema types

ParseSequenceType

public XdmSequenceType ParseSequenceType(string input)
throws
SaxonApiException

Construct an XdmSequenceType object by parsing a sequence type definition in XPath syntax

Experimental XPath 4.0 syntax is accepted provided that the configuration feature XQUERY_VERSION is set to "4.0"

Parameters:

input - The input string, in XPath syntax (for example array(xs:integer)*). The only namespace prefix recognized is "xs", representing the XML Schema namespace.

Throws:

SaxonApiException - If the syntax of the input is invalid, or if there are references to undeclared schema types

RegisterCollection

public void RegisterCollection(Uri collectionUri,
IEnumerable<IResource> collection)

Register a specific collection URI

Registered collections take priority over any a user-supplied CollectionFinder

Parameters:

collectionUri - The collection URI
collection - The contents of the collection

RegisterExtensionFunction

public void RegisterExtensionFunction(ExtensionFunctionDefinition function)

Register an extension function with the Processor. This interface provides rich capability for defining extension functions with complex requirements, for example accessing information in the static and dynamic context, and declaring the presence of side-effects. For simpler extension functions use an ExtensionFunction in preference.

Parameters:

function -  An object that defines the extension function, including its name, arity, arguments types, and a reference to the class that implements the extension function call. This function becomes available for use in all queries, stylesheets, and XPath expressions compiled under the control of this Processor.

RegisterExtensionFunction

public void RegisterExtensionFunction(QName name,
XdmItemType type,
Func 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

Parameters:

name - The name of the function, as a QName
type - The type of the function, for example ParseItemType("function(xs:double) as xs:double"). This must be a specific function type.
function - The body of the function, supplied typically as a lambda expression. This interface provides only for extensions that have no side-effects and no dependencies on the static or dynamic context. It does however allow the type signature of the function to be defined.

RegisterFileExtension

public void RegisterFileExtension(string extension,
string mediaType)

Set the media type to be associated with a file extension by the standard collection handler

Parameters:

extension - the file extension, for example "xml". The value "" sets the default media type to be used for unregistered file extensions
mediaType - the corresponding media type, for example "application/xml". The choice of media type determines how a resource with this extension gets parsed, when the file appears as part of a collection

SetCatalogFiles

public void SetCatalogFiles(string[] fileNames)

Set one or more catalog files to be used for resolving URIs

The call has no effect unless the configuration is using a resolver capable of using catalogs. It generally won't work if SetResourceResolver has been called to set a different configuration-level resolver. However you can call this method to set catalogs for use by the standard resolver, and then subsequently call SetResourceResolver with combine=true to combine a user-defined resolver for specific URIs with a catalog-based resolver for others.

Parameters:

fileNames - A list of filenames. (Often a single filename.) The call has no effect if the list is empty. Relative filenames are interpreted relative to the current working directory.

SetProperty

public void SetProperty(string name,
string value)

Set a configuration property

This method provides the ability to set named properties of the configuration. The property names are set as strings, whose values can be found in the Java class net.sf.saxon.lib.FeatureKeys. The property values are always strings. Properties whose values are other types are not available via this interface: however all properties have an effective equivalent whose value is a string. Note that on/off properties are set using the strings "true" and "false".

Method added in Saxon 9.1

Parameters:

name - The property name
value - The property value

SetProperty

public void SetProperty(Feature feature,
object value)

Set a configuration property. This method provides a type-safe way of setting properties of any type: for example a boolean property can be set by calling SetProperty(Feature<bool>.ALLOW_SYNTAX_EXTENSIONS, true).

Parameters:

feature - The property feature
value - The property value

SetResourceResolver

public void SetResourceResolver(ResourceResolver resolver,
bool combine)

Set a resource resolver to be used to resolve URIs referring to external resources.

This resolver is used for all resources within the scope of the Processor, unless a more specific resolver is allocated for example at the level of an XsltCompiler or XQueryEvaluator.

If the resolver returns null, then "direct URI resolution" (using the native methods supported by the platform) is used as a fallback.

Parameters:

resolver - The resource resolver to be used
combine - If true, then the existing resource resolver registered at configuration level is used as a fallback when the new resource resolver returns null.

WriteXdmValue

public void WriteXdmValue(XdmValue sequence,
IDestination destination)

Copy an XdmValue to an XmlDestination

In principle this method can be used to copy any kind of XdmValue to any kind of XmlDestination. However, some kinds of destination may not accept arbitrary sequences of items; for example, some may reject function items. Some destinations perform sequence normalization, as defined in the W3C serialization specification, to convert the supplied sequence to a well-formed XML document; it is a property of the chosen XmlDestination whether it does this or not.

Parameters:

sequence - The value to be written
destination - The destination to which the value should be written