Class Configuration
- All Implemented Interfaces:
Serializable
,SourceResolver
,NotationSet
As well as holding configuration settings, this class acts as a factory for classes providing service in particular areas: error handling, URI resolution, and the like. Some of these services are chosen on the basis of the current platform (Java or .NET), some vary depending whether the environment is schema-aware or not.
The Configuration
provides access to a NamePool
which is used to manage
all the names used in stylesheets, queries, schemas, and source and documents: the NamePool
allocates integer codes to these names allowing efficient storage and comparison. Normally
there will be a one-to-one relationship between a NamePool
and a Configuration
.
It is possible, however, for several Configuration
objects to share the same
NamePool
. Until Saxon 8.9, by default all Configuration
objects
shared a single NamePool
unless configured otherwise; this changed in 8.9 so that
the default is to allocate a new NamePool
for each Configuration
.
The Configuration
establishes the scope within which node identity is managed.
Every document belongs to a Configuration
, and every node has a distinct identity
within that Configuration
. In consequence, it is not possible for any query or
transformation to manipulate multiple documents unless they all belong to the same
Configuration
.
Saxon-EE has a subclass of the Configuration
class which provides the additional
services needed for schema-aware processing. The com.saxonica.config.EnterpriseConfiguration
also holds a cache of loaded schema components used for compiling schema-aware transformations
and queries, and for validating instance documents.
Since Saxon 8.4, the JavaDoc documentation for Saxon attempts to identify interfaces that are considered stable, and will only be changed in a backwards-incompatible way if there is an overriding reason to do so. These interfaces and methods are labelled with the JavaDoc "since" tag. The value 8.n indicates a method in this category that was introduced in Saxon version 8.n: or in the case of 8.4, that was present in Saxon 8.4 and possibly in earlier releases. (In some cases, these methods have been unchanged for a long time.) Methods without a "since" tag, although public, are provided for internal use or for use by advanced users, and are subject to change from one release to the next. The presence of a "since" tag on a class or interface indicates that there are one or more methods in the class that are considered stable; it does not mean that all methods are stable.
- Since:
- 8.4
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
This class contains constants representing features of the software that may or may not be licensed. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final Class<? extends Configuration>
static final int
Constant indicating that when a recoverable error occurs, the processor should not attempt to take the defined recovery action, but should terminate with an error.static final int
Constant indicating that the host language is Java: that is, this is a free-standing Java application with no XSLT or XQuery contentprotected int
protected Optimizer
static final int
Constant indicating that the processor should take the recovery action when a recoverable error occurs, with no warning message.static final int
Constant indicating that the processor should produce a warning when a recoverable error occurs, and should then take the recovery action and continue.static final String
protected VendorFunctionLibrary
static final int
Constant indicating that the "host language" is XML Schemastatic final int
Constant indicating the XML Version 1.0static final int
Constant indicating the XML Version 1.1static final int
Constant indicating that the host language is XPATH itself - that is, a free-standing XPath environmentstatic final int
Constant indicating that the host language is XQuerystatic final int
Language versions for XML Schemastatic final int
protected int
static final int
Constant indicating that the host language is XSLT -
Constructor Summary
ConstructorsConstructorDescriptionCreate a non-schema-aware configuration object with default settings for all options. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Add the registered extension binders to a function library.void
addSchemaForBuiltInNamespace
(String namespace) Add a built-in schema for a given namespace.void
addSchemaSource
(Source schemaSource) Load a schema, which will be available for use by all subsequent operations using this Configuration.void
addSchemaSource
(Source schemaSource, ErrorListener errorListener) Load a schema, which will be available for use by all subsequent operations using this EnterpriseConfiguration.buildDocument
(Source source) Build a document tree, using options set on this Configuration and on the supplied source object.buildDocument
(Source source, ParseOptions parseOptions) Build a document, using specified options for parsing and building.void
checkLicensedFeature
(int feature, String name) Check whether a particular feature is licensed, with a fatal error if it is notvoid
checkTypeDerivationIsOK
(SchemaType derived, SchemaType base, int block) Check that a type is validly derived from another type, following the rules for the Schema Component Constraint "Is Type Derivation OK (Simple)" (3.14.6) or "Is Type Derivation OK (Complex)" (3.4.6) as appropriate.void
Remove all schema components that have been loaded into this Configuration.void
Display a message about the license statusvoid
exportComponents
(Receiver out) Export a precompiled Schema Component Model containing all the components (except built-in components) that have been loaded into this Processor.protected void
finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.getAnnotationStripper
(Receiver destination) Add to a pipeline a receiver that strips all type annotations.getAttributeDeclaration
(int fingerprint) Get a global attribute declaration.Get the CharacterSetFactory.getClass
(String className, boolean tracing, ClassLoader classLoader) Load a class using the class name provided.Get the collation map, which can be used to register named collations (and a default collation) at the Configuration level.Get the collation URI resolver associated with this configuration.Get the collection URI resolver associated with this configuration.static Configuration
getConfiguration
(XPathContext context) Get the configuration, given the context.Get a property of the configurationGet an XPathContext object with sufficient capability to perform comparisons and conversionsGet the conversion rules used to convert between atomic types.Get the debugger in use.Get the URI of the default collection.Get the default country to be used for number and date formatting when no country is specified.Get the default language.Get the default serialization propertiesGet the default options for XQuery compilationGet the default options for XSLT compilationGet the document number allocator.getDocumentValidator
(Receiver receiver, String systemId, int validationMode, int stripSpace, SchemaType schemaType, int topLevelElementName) Get a document-level validator to add to a Receiver pipeline.int
Get the level of DOM interface to be usedGet the DynamicLoader used by this Configuration.Get the edition code identifying this configuration: "HE", "PE" or "EE"getElementDeclaration
(int fingerprint) Get a global element declaration.Get a global element declaration.getElementValidator
(SequenceReceiver receiver, NodeName elemName, int locationId, SchemaType schemaType, int validation) Get a Receiver that can be used to validate an element, and that passes the validated element on to a target receiver.Get the ErrorListener used in this configuration.Iterator<? extends SchemaType>
Get the set of complex types that have been defined as extensions of a given type.getExternalObjectModel
(Class nodeClass) Get the external object model that recognizes a particular class of node, if availableGet the external object model with a given URI, if registeredGet all the registered external object models.protected ExternalObjectType
getExternalObjectType
(int fingerprint) Get the external object type corresponding to a fingerprint if it is indeed an external object type, otherwise return nullGet the global document pool.int
Get the host language used in this configuration.Get the set of namespaces of imported schemasgetInstance
(String className, ClassLoader classLoader) Instantiate a class using the class name provided.Get the IntegratedFunction library containing integrated extension functionsstatic Locale
Get a locale given a language code in XML format.Get the localizer factory in useGet the name of the class that will be instantiated to create a MessageEmitter, to process the output of xsl:message instructions in XSLT.Get the user-defined ModuleURIResolver for resolving URIs used in "import module" declarations in the XQuery prolog; returns null if none has been explicitly set.Get a class that can be used to check names against the selected XML versionGet the target namepool to be used for stylesheets/queries and for source documents.Get the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.Get the parsing and document building options defined in this configurationstatic Platform
Get the Platform to be used for platform-dependent methodsGet the Processor object that created this Configuration in the relevant API.Get a message used to identify this product when a transformation is run using the -t optionint
Determine how recoverable run-time errors are to be handled.getSchemaType
(int fingerprint) Get the top-level schema type definition with a given fingerprint.Get the user-defined SchemaURIResolver for resolving URIs used in "import schema" declarations; if none has been explicitly set, returns null.int
Ask whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation, and if so, in what validation modeGet the SerializerFactory.Get a parser for source documents.Get the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions).Get the current SourceResolver.Get the standard error output to be used in all cases where no more specific destination is defined.Get the standard system-defined ModuleURIResolver for resolving URIs used in "import module" declarations in the XQuery prolog.int
Set which kinds of whitespace-only text node should be stripped.Get the parser for stylesheet documents.Get the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules.Get the system-defined URI Resolver.Get the TraceListener used for run-time tracing of instruction execution.Get the name of the trace listener class to be used for run-time tracing of instruction execution.int
Get the Tree Model used by this Configuration.final TypeHierarchy
Get the TypeHierarchy: a cache holding type informationGet the URIResolver used in this configurationGet the FunctionLibrary used to bind calls on Saxon-defined extension functions.int
Get the XML version to be used by default for validating characters and namesint
Get the version of XML Schema to be usedvoid
importComponents
(Source source) Import a precompiled Schema Component Model from a given Source.protected void
init()
protected Object
instantiateClassName
(String propertyName, Object value, Class requiredClass) boolean
Determine whether calls to external Java functions are permitted.boolean
isCompatible
(Configuration other) Determine whether two Configurations are compatible.boolean
Determine whether compile-time generation of trace code was requestedboolean
This option is set to indicate that bytecode generation should be run in debugging mode.boolean
isDeclaredNotation
(String uri, String local) Ask whether a given notation has been declared in the schemaboolean
This option is set to indicate that bytecode generation should be run in display mode.boolean
Determine whether elements and attributes that have a fixed or default value are to be expanded.boolean
isGenerateByteCode
(int hostLanguage) Ask whether bytecode should be generated.boolean
Determine whether lazy construction mode is on or off.boolean
isLicensedFeature
(int feature) Determine if a particular feature is licensed.boolean
Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.boolean
Determine whether multithreading optimizations are allowedboolean
Test whether optimizer tracing is on or offboolean
Ask whether attribute types obtained from a DTD are to be used to set type annotations on the resulting nodesboolean
isSchemaAvailable
(String targetNamespace) Determine whether the Configuration contains a cached schema for a given target namespaceboolean
isSchemaAware
(int language) Deprecated.since 9.2: use isLicensedFeature() insteadboolean
Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.boolean
isTiming()
Determine whether brief progress messages and timing information will be output to System.err.boolean
Determine whether calls on external functions are to be traced for diagnostic purposes.boolean
Determine whether the XML parser for source documents will be asked to perform validation of source documentsboolean
Determine whether schema validation failures on result documents are to be treated as fatal errors or as warnings.boolean
Determine whether a warning is to be output when running against a stylesheet labelled as version="1.0".boolean
Test whether or not source documents (including stylesheets and schemas) are to have XInclude processing applied to them, or notvoid
loadSchema
(String absoluteURI) Simple interface to load a schema documentstatic InputStream
locateResource
(String filename, List<String> messages, List<ClassLoader> loaders) Read a resource file issued with the Saxon productmakeClosure
(Expression expression, int ref, XPathContext context) Make a Closure, given the expected reference countCreate a document projector for a given path map.makeEmitter
(String clarkName, Properties props) Load a named output emitter or SAX2 ContentHandler and check it is OK.static Configuration
makeLicensedConfiguration
(ClassLoader classLoader, String className) Static method to instantiate a professional or enterprise configuration.makeNumberer
(String language, String country) Load a Numberer class for a given language and check it is OK.makeParser
(String className) Create a new SAX XMLReader object using the class name provided.Make a PipelineConfiguration from the properties of this Configurationstatic Configuration
makeSchemaAwareConfiguration
(ClassLoader loader, String className) Deprecated.since 9.2.makeSequenceExtent
(Expression expression, int ref, XPathContext context) Make a SequenceExtent, given the expected reference countFactory method to create a SlotManager.makeStreamingTransformer
(XPathContext context, Mode mode) Create a streaming transformerFactory method to get the StyleNodeFactory, used for constructing elements in a stylesheet documentGet or create the TraceListener used for run-time tracing of instruction execution.makeTraceListener
(String className) Create an instance of a TraceListener with a specified class namemakeUnconstructedDocument
(DocumentInstr instr, XPathContext context) Make an "unconstructed" (that is, lazily-constructed) document nodemakeUnconstructedElement
(ElementCreator instr, XPathContext context) Make an "unconstructed" (that is, lazily-constructed) element nodemakeURIResolver
(String className) Create an instance of a URIResolver with a specified class name.protected void
Throw an error indicating that a request cannot be satisfied because it requires the schema-aware edition of Saxonstatic Configuration
Factory method to create a Configuration, of the class specified in the edition.properties properties file: that is, the type of Configuration appropriate to the edition of the software being used.newExpressionParser
(String language, boolean updating, DecimalValue languageVersion) Make an expression Parser for a specified version of XPath or XQueryGet a new Pending Update ListGet a new StaticQueryContext (which is also the factory class for creating a query parser)newUserFunction
(boolean memoFunction) Make a UserFunction object.Factory method to get an Optimizer.static Configuration
readConfiguration
(Source source) Factory method to construct a Configuration object by reading a configuration file.protected Configuration
readConfigurationFile
(Source source) Read the configuration file an construct a new Configuration (the real one)readInlineSchema
(NodeInfo root, String expected, ErrorListener errorListener) Read an inline schema from a stylesheet.void
readMultipleSchemas
(PipelineConfiguration pipe, String baseURI, Collection schemaLocations, String expected) Read schemas from a list of schema locations.readSchema
(PipelineConfiguration pipe, String baseURI, String schemaLocation, String expected) Read a schema from a given schema locationvoid
Register an extension function that is to be made available within any stylesheet, query, or XPath expression compiled under the control of this processor.void
Register an external object model with this Configuration.void
Report a fatal errorprotected boolean
requireBoolean
(String propertyName, Object value) Validate a property value where the required type is booleanprotected String
requireString
(String propertyName, Object value) resolveSource
(Source source, Configuration config) Resolve a Source.void
reuseSourceParser
(XMLReader parser) Return a source parser to the pool, for reusevoid
reuseStyleParser
(XMLReader parser) Return a stylesheet (or schema) parser to the pool, for reusevoid
sealNamespace
(String namespace) Mark a schema namespace as being sealed.void
setAllowExternalFunctions
(boolean allowExternalFunctions) Determine whether calls to external Java functions are permitted.void
setCollationURIResolver
(CollationURIResolver resolver) Set a CollationURIResolver to be used to resolve collation URIs (that is, to take a URI identifying a collation, and return the corresponding collation).void
Set a CollectionURIResolver to be used to resolve collection URIs (that is, the URI supplied in a call to the collection() function).void
setCompileWithTracing
(boolean trace) Request compile-time generation of trace code (or not)void
setConfigurationProperty
(String name, Object value) Set a property of the configuration.void
Set the conversion rules to be used to convert between atomic types.void
setDebugBytecode
(boolean debugBytecode) This option is set to indicate that bytecode generation should be run in debugging mode.void
setDebugger
(Debugger debugger) Set the debugger to be used.void
Set the default collection.void
setDefaultCountry
(String country) Set the default country to be used for number and date formatting when no country is specified.void
setDefaultLanguage
(String language) Set the default language to be used for number and date formatting when no language is specified.void
Set the default serialization propertiesvoid
setDisplayBytecode
(boolean displayBytecode) This option is set to indicate that bytecode generation should be run in display mode.void
Set the document number allocator.void
setDOMLevel
(int level) Set the level of DOM interface to be usedvoid
setDynamicLoader
(DynamicLoader dynamicLoader) Set the DynamicLoader to be used.void
setErrorListener
(ErrorListener listener) Set the ErrorListener to be used in this configuration.void
setExpandAttributeDefaults
(boolean expand) Indicate whether attributes that have a fixed or default value are to be expanded when generating a final result tree.void
setGenerateByteCode
(boolean compileToBytecode) Say whether bytecode should be generated.void
setHostLanguage
(int hostLanguage) Set the host language used in this configuration.void
setLazyConstructionMode
(boolean lazy) Set lazy construction mode on or off.void
setLineNumbering
(boolean lineNumbering) Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.void
setLocalizerFactory
(LocalizerFactory factory) Set the localizer factory to be usedvoid
setMessageEmitterClass
(String messageReceiverClassName) Set the name of the class that will be instantiated to to process the output of xsl:message instructions in XSLT.void
setModuleURIResolver
(String className) Create and register an instance of a ModuleURIResolver with a specified class name.void
setModuleURIResolver
(ModuleURIResolver resolver) Set a user-defined ModuleURIResolver for resolving URIs used in "import module" declarations in an XQuery prolog.void
setMultiThreading
(boolean multithreading) Set whether multithreading optimizations are allowed.void
setNamePool
(NamePool targetNamePool) Set the NamePool to be used for stylesheets/queries and for source documents.void
setOptimizerTracing
(boolean trace) Set optimizer tracing on or offvoid
setOutputURIResolver
(OutputURIResolver outputURIResolver) Set the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.void
Set the URIResolver to a URI resolver that allows query parameters after the URI, and in the case of Saxon-EE, that inteprets the file extension .ptreevoid
setProcessor
(Object processor) Save the Processor object that owns this Configuration in the relevant API.void
setRecoveryPolicy
(int recoveryPolicy) Determine how recoverable run-time errors are to be handled.void
setRetainDTDAttributeTypes
(boolean useTypes) Deprecated.since 9.2 This feature was dropped from the final XDM specification and will be dropped in a future Saxon release.void
setSchemaURIResolver
(SchemaURIResolver resolver) Set a user-defined SchemaURIResolver for resolving URIs used in "import schema" declarations.void
setSchemaValidationMode
(int validationMode) Say whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation, and if so, in what validation mode.void
setSerializerFactory
(SerializerFactory factory) Set a custom SerializerFactory.void
setSourceParserClass
(String sourceParserClass) Set the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions).void
setSourceResolver
(SourceResolver resolver) Supply a SourceResolver.void
Set the standard error output to be used in all cases where no more specific destination is defined.void
setStripsAllWhiteSpace
(boolean stripsAllWhiteSpace) Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.void
setStripsWhiteSpace
(int kind) Set which kinds of whitespace-only text node should be stripped.void
setStyleParserClass
(String parser) Set the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules.void
setTiming
(boolean timing) Determine whether brief progress messages and timing information will be output to System.err.void
setTraceExternalFunctions
(boolean traceExternalFunctions) Determine whether calls on external functions are to be traced for diagnostic purposes.void
setTraceListener
(TraceListener traceListener) Set the TraceListener to be used for run-time tracing of instruction execution.void
setTraceListenerClass
(String className) Set the name of the trace listener class to be used for run-time tracing of instruction execution.void
setTreeModel
(int treeModel) Set the Tree Model used by this Configuration.void
setURIResolver
(URIResolver resolver) Set the URIResolver to be used in this configuration.void
setValidation
(boolean validation) Determine whether the XML parser for source documents will be asked to perform DTD validation of source documentsvoid
setValidationWarnings
(boolean warn) Indicate whether schema validation failures on result documents are to be treated as fatal errors or as warnings.void
setVersionWarning
(boolean warn) Determine whether a warning is to be output when the version attribute of the stylesheet does not match the XSLT processor version.void
setXIncludeAware
(boolean state) Set whether or not source documents (including stylesheets and schemas) are have XInclude processing applied to them, or not.void
setXMLVersion
(int version) Set the XML version to be used by default for validating characters and names.Get a NodeInfo corresponding to a DOM or other external Node, either by wrapping or unwrapping the external Node.boolean
Ask whether the typed value cache should be used for the TinyTreevalidateAttribute
(int nameCode, CharSequence value, int validation) Validate an attribute value.
-
Field Details
-
configurationClass
-
softwareEdition
-
xsdVersion
protected int xsdVersion -
vendorFunctionLibrary
-
optimizer
-
optimizationLevel
protected int optimizationLevel -
RECOVER_SILENTLY
public static final int RECOVER_SILENTLYConstant indicating that the processor should take the recovery action when a recoverable error occurs, with no warning message.- See Also:
-
RECOVER_WITH_WARNINGS
public static final int RECOVER_WITH_WARNINGSConstant indicating that the processor should produce a warning when a recoverable error occurs, and should then take the recovery action and continue.- See Also:
-
DO_NOT_RECOVER
public static final int DO_NOT_RECOVERConstant indicating that when a recoverable error occurs, the processor should not attempt to take the defined recovery action, but should terminate with an error.- See Also:
-
XML10
public static final int XML10Constant indicating the XML Version 1.0- See Also:
-
XML11
public static final int XML11Constant indicating the XML Version 1.1- See Also:
-
XSLT
public static final int XSLTConstant indicating that the host language is XSLT- See Also:
-
XQUERY
public static final int XQUERYConstant indicating that the host language is XQuery- See Also:
-
XML_SCHEMA
public static final int XML_SCHEMAConstant indicating that the "host language" is XML Schema- See Also:
-
JAVA_APPLICATION
public static final int JAVA_APPLICATIONConstant indicating that the host language is Java: that is, this is a free-standing Java application with no XSLT or XQuery content- See Also:
-
XPATH
public static final int XPATHConstant indicating that the host language is XPATH itself - that is, a free-standing XPath environment- See Also:
-
XSD10
public static final int XSD10Language versions for XML Schema- See Also:
-
XSD11
public static final int XSD11- See Also:
-
-
Constructor Details
-
Configuration
public Configuration()Create a non-schema-aware configuration object with default settings for all options.- Since:
- 8.4
-
-
Method Details
-
locateResource
public static InputStream locateResource(String filename, List<String> messages, List<ClassLoader> loaders) Read a resource file issued with the Saxon product- Parameters:
filename
- the filename of the file to be readmessages
- List to be populated with messages in the event of failureloaders
- List to be populated with the ClassLoader that succeeded in loading the resource- Returns:
- an InputStream for reading the file/resource
-
readConfiguration
Factory method to construct a Configuration object by reading a configuration file.- Parameters:
source
- Source object containing the configuration file- Returns:
- the resulting Configuration
- Throws:
XPathException
- if the configuration file cannot be read or is invalid
-
readConfigurationFile
Read the configuration file an construct a new Configuration (the real one)- Parameters:
source
- the source of the configuration file- Returns:
- the Configuration that will be used for real work
- Throws:
XPathException
- if the configuration file cannot be read or is invalid
-
newConfiguration
Factory method to create a Configuration, of the class specified in the edition.properties properties file: that is, the type of Configuration appropriate to the edition of the software being used. This method does not check that the Configuration is licensed.- Returns:
- a Configuration object of the class appropriate to the Saxon edition in use.
- Since:
- 9.2
-
init
protected void init() -
makeLicensedConfiguration
public static Configuration makeLicensedConfiguration(ClassLoader classLoader, String className) throws RuntimeException Static method to instantiate a professional or enterprise configuration.This method fails if the specified configuration class cannot be loaded, but it does not check whether there is a license available.
- Parameters:
classLoader
- - the class loader to be used. If null, the context class loader for the current thread is used.className
- - the name of the configuration class. Defaults to "com.saxonica.config.ProfessionalConfiguration" if null is supplied. This allows an assembly qualified name to be supplied under .NET. The class, once instantiated, must be an instance of Configuration.- Returns:
- the new ProfessionalConfiguration or EnterpriseConfiguration
- Throws:
RuntimeException
- if the required Saxon edition cannot be loaded- Since:
- 9.2 (renamed from makeSchemaAwareConfiguration)
-
makeSchemaAwareConfiguration
Deprecated.since 9.2. UsemakeLicensedConfiguration(java.lang.ClassLoader, java.lang.String)
instead.Make an enterprise configuration- Parameters:
loader
- the class loader (or null)className
- the name of the configuration class (or null)- Returns:
- the same result as
makeLicensedConfiguration(java.lang.ClassLoader, java.lang.String)
-
getEditionCode
Get the edition code identifying this configuration: "HE", "PE" or "EE"- Returns:
- the code identifying the Saxon edition associated with this configuration
-
setProcessor
Save the Processor object that owns this Configuration in the relevant API.- Parameters:
processor
- This can be any object, but it is actually used to hold one of the following:- When using the Java s9api interface, the
net.sf.saxon.s9api.Processor
- When using the .NET interface, the
Saxon.Api.Processor
- When using the JAXP transformation interface, the JAXP
TransformerFactory
- When using the JAXP XPath interface, the JAXP
XPathFactory
- When using the JAXP Schema interface, the JAXP
SchemaFactory
- When using XQJ, the
XQDataSource
- When using the Java s9api interface, the
- Since:
- 9.2
-
getProcessor
Get the Processor object that created this Configuration in the relevant API.The main purpose of this interface is to allow extension functions called from a stylesheet or query to get access to the originating processor. This is particularly useful when methods are static as there is then limited scope for passing data from the calling application to the code of the extension function.
- Returns:
- the processor that was supplied to the
setProcessor(Object)
method, or null if this method has not been called. In practice this property is used to hold one of the following:- When using the Java s9api interface, the
net.sf.saxon.s9api.Processor
- When using the .NET interface, the
Saxon.Api.Processor
- When using the JAXP transformation interface, the JAXP
TransformerFactory
- When using the JAXP XPath interface, the JAXP
XPathFactory
- When using the JAXP Schema interface, the JAXP
SchemaFactory
- When using XQJ, the
XQDataSource
- When using the Java s9api interface, the
- Since:
- 9.2
-
getProductTitle
Get a message used to identify this product when a transformation is run using the -t option- Returns:
- A string containing both the product name and the product version
- Since:
- 8.4
-
checkLicensedFeature
Check whether a particular feature is licensed, with a fatal error if it is not- Parameters:
feature
- the feature in question, identified by a constant in classConfiguration.LicenseFeature
name
- the name of the feature for use in diagnostics- Throws:
LicenseException
- if the feature is not licensed. This is a RunTimeException, so it will normally be fatal.
-
isLicensedFeature
public boolean isLicensedFeature(int feature) Determine if a particular feature is licensed.- Parameters:
feature
- the feature in question, identified by a constant in classConfiguration.LicenseFeature
- Returns:
- true if the feature is licensed, false if it is not.
-
isSchemaAware
public boolean isSchemaAware(int language) Deprecated.since 9.2: use isLicensedFeature() insteadDetermine if the configuration is schema-aware, for the given host language- Parameters:
language
- the required host language: XSLT, XQUERY, or XML_SCHEMA- Returns:
- true if the configuration is schema-aware
- Since:
- 8.4
-
displayLicenseMessage
public void displayLicenseMessage()Display a message about the license status -
getHostLanguage
public int getHostLanguage()Get the host language used in this configuration. The typical values are XSLT and XQUERY. The values XML_SCHEMA and JAVA_APPLICATION may also be encountered. This method is problematic because it is possible to run multiple transformations or queries within the same configuration. The method is therefore best avoided. Instead, useContainer.getHostLanguage()
. Internally its only use is in deciding (in Saxon-EE only) which error listener to use by default at compile time, and since the standard XSLT and XQuery listeners have no differences when used for static errors, the choice is immaterial.- Returns:
- Configuration.XSLT or Configuration.XQUERY
-
setHostLanguage
public void setHostLanguage(int hostLanguage) Set the host language used in this configuration. The possible values are XSLT and XQUERY.- Parameters:
hostLanguage
- Configuration.XSLT or Configuration.XQUERY
-
getPlatform
Get the Platform to be used for platform-dependent methods- Returns:
- the platform to be used
-
setDynamicLoader
Set the DynamicLoader to be used. By default an instance ofDynamicLoader
is used for all dynamic loading of Java classes. This method allows the actions of the standard DynamicLoader to be overridden- Parameters:
dynamicLoader
- the DynamicLoader to be used by this Configuration
-
getDynamicLoader
Get the DynamicLoader used by this Configuration. By default the standard system-supplied dynamic loader is returned.- Returns:
- the DynamicLoader in use - either a user-supplied DynamicLoader, or the standard one supplied by the system.
-
getClass
public Class getClass(String className, boolean tracing, ClassLoader classLoader) throws XPathException Load a class using the class name provided. Note that the method does not check that the object is of the right class. This method is intended for internal use only. The call is delegated to theDynamicLoader
, which may be overridden by a user-definedDynamicLoader
.- Parameters:
className
- A string containing the name of the class, for example "com.microstar.sax.LarkDriver"tracing
- true if diagnostic tracing is requiredclassLoader
- The ClassLoader to be used to load the class, or null to use the ClassLoader selected by the DynamicLoader.- Returns:
- an instance of the class named, or null if it is not loadable.
- Throws:
XPathException
- if the class cannot be loaded.
-
getInstance
Instantiate a class using the class name provided. Note that the method does not check that the object is of the right class. This method is intended for internal use only. The call is delegated to theDynamicLoader
, which may be overridden by a user-definedDynamicLoader
. Diagnostic output is produced if the option "isTiming" is set (corresponding to the -t option on the command line).- Parameters:
className
- A string containing the name of the class, for example "com.microstar.sax.LarkDriver"classLoader
- The ClassLoader to be used to load the class, or null to use the ClassLoader selected by the DynamicLoader.- Returns:
- an instance of the class named, or null if it is not loadable.
- Throws:
XPathException
- if the class cannot be loaded.
-
getURIResolver
Get the URIResolver used in this configuration- Returns:
- the URIResolver. If no URIResolver has been set explicitly, the default URIResolver is used.
- Since:
- 8.4
-
setURIResolver
Set the URIResolver to be used in this configuration. This will be used to resolve the URIs used statically (e.g. by xsl:include) and also the URIs used dynamically by functions such as document() and doc(). Note that the URIResolver does not resolve the URI in the sense of RFC 2396 (which is also the sense in which the resolve-uri() function uses the term): rather it dereferences an absolute URI to obtain an actual resource, which is returned as a Source object.- Parameters:
resolver
- The URIResolver to be used.- Since:
- 8.4
-
setParameterizedURIResolver
public void setParameterizedURIResolver()Set the URIResolver to a URI resolver that allows query parameters after the URI, and in the case of Saxon-EE, that inteprets the file extension .ptree -
getSystemURIResolver
Get the system-defined URI Resolver. This is used when the user-defined URI resolver returns null as the result of the resolve() method- Returns:
- the system-defined URI resolver
-
makeURIResolver
Create an instance of a URIResolver with a specified class name. Note that this method does not register the URIResolver with this Configuration.- Parameters:
className
- The fully-qualified name of the URIResolver class- Returns:
- The newly created URIResolver
- Throws:
TransformerException
- if the requested class does not implement the javax.xml.transform.URIResolver interface
-
getErrorListener
Get the ErrorListener used in this configuration. If no ErrorListener has been supplied explicitly, the default ErrorListener is used.- Returns:
- the ErrorListener.
- Since:
- 8.4
-
setErrorListener
Set the ErrorListener to be used in this configuration. The ErrorListener is informed of all static and dynamic errors detected, and can decide whether run-time warnings are to be treated as fatal.- Parameters:
listener
- the ErrorListener to be used- Since:
- 8.4
-
reportFatalError
Report a fatal error- Parameters:
err
- the exception to be reported
-
setStandardErrorOutput
Set the standard error output to be used in all cases where no more specific destination is defined. This defaults to System.err.- Parameters:
out
- the stream to be used for error output where no more specific destination has been supplied- Since:
- 9.3
-
getStandardErrorOutput
Get the standard error output to be used in all cases where no more specific destination is defined. This defaults to System.err.- Returns:
- the stream to be used for error output where no more specific destination has been supplied
- Since:
- 9.3
-
setMultiThreading
public void setMultiThreading(boolean multithreading) Set whether multithreading optimizations are allowed. Note that Saxon only uses multi-threading if explicitly requested using thesaxon:threads
attribute ofxsl:for-each
. However, it can be disabled by setting this option to false.- Parameters:
multithreading
- true if multithreading optimizations are allowed. Default is true for Saxon-EE, false for Saxon-HE and Saxon-PE
-
isMultiThreading
public boolean isMultiThreading()Determine whether multithreading optimizations are allowed- Returns:
- true if multithreading optimizations are allowed
-
setXMLVersion
public void setXMLVersion(int version) Set the XML version to be used by default for validating characters and names. Note that source documents specifying xml version="1.0" or "1.1" are accepted regardless of this setting. The effect of this switch is to change the validation rules for types such as Name and NCName, to change the meaning of \i and \c in regular expressions, and to determine whether the serializer allows XML 1.1 documents to be constructed.- Parameters:
version
- one of the constants XML10 or XML11- Since:
- 8.6
-
getXMLVersion
public int getXMLVersion()Get the XML version to be used by default for validating characters and names -
getParseOptions
Get the parsing and document building options defined in this configuration- Returns:
- the parsing and document building options. Note that any changes to tgethis ParseOptions object will be reflected back in the Configuration; if changes are to be made locally, the caller should create a copy.
- Since:
- 9.2
-
getNameChecker
Get a class that can be used to check names against the selected XML version- Returns:
- a class that can be used for name checking
- Since:
- 8.6
-
setConversionRules
Set the conversion rules to be used to convert between atomic types. By default, The rules depend on the versions of XML and XSD in use by the configuration.- Parameters:
rules
- the conversion rules to be used- Since:
- 9.3
-
getConversionRules
Get the conversion rules used to convert between atomic types. By default, the rules depend on the versions of XML and XSD in use by the configuration- Returns:
- the appropriate conversion rules
- Since:
- 9.3
-
getXsdVersion
public int getXsdVersion()Get the version of XML Schema to be used -
getConversionContext
Get an XPathContext object with sufficient capability to perform comparisons and conversions- Returns:
- a dynamic context for performing conversions
-
getTreeModel
public int getTreeModel()Get the Tree Model used by this Configuration. This is eitherBuilder.LINKED_TREE
,Builder.TINY_TREE
, orBuilder.TINY_TREE_CONDENSED
. The default isBuilder.TINY_TREE
.- Returns:
- the selected Tree Model
- Since:
- 8.4 (Condensed tinytree added in 9.2)
-
setTreeModel
public void setTreeModel(int treeModel) Set the Tree Model used by this Configuration. This is eitherBuilder.LINKED_TREE
orBuilder.TINY_TREE
, orBuilder.TINY_TREE_CONDENSED
. The default isBuilder.TINY_TREE
.- Parameters:
treeModel
- the integer constant representing the selected Tree Model- Since:
- 8.4 (Condensed tinytree added in 9.2)
-
useTypedValueCache
public boolean useTypedValueCache()Ask whether the typed value cache should be used for the TinyTree- Returns:
- true (the default) if the cache should be used, false otherwise
-
isLineNumbering
public boolean isLineNumbering()Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.- Returns:
- true if line numbers are maintained in source documents
- Since:
- 8.4
-
setLineNumbering
public void setLineNumbering(boolean lineNumbering) Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.- Parameters:
lineNumbering
- true if line numbers are maintained in source documents- Since:
- 8.4
-
setXIncludeAware
public void setXIncludeAware(boolean state) Set whether or not source documents (including stylesheets and schemas) are have XInclude processing applied to them, or not. Default is false.- Parameters:
state
- true if XInclude elements are to be expanded, false if not- Since:
- 8.9
-
isXIncludeAware
public boolean isXIncludeAware()Test whether or not source documents (including stylesheets and schemas) are to have XInclude processing applied to them, or not- Returns:
- true if XInclude elements are to be expanded, false if not
- Since:
- 8.9
-
getTraceListener
Get the TraceListener used for run-time tracing of instruction execution.- Returns:
- the TraceListener that was set using
setTraceListener(net.sf.saxon.lib.TraceListener)
if set. Otherwise, returns null. - Since:
- 8.4. Modified in 9.1.
-
makeTraceListener
Get or create the TraceListener used for run-time tracing of instruction execution.- Returns:
- If a TraceListener has been set using
setTraceListener(net.sf.saxon.lib.TraceListener)
, returns that TraceListener. Otherwise, if a TraceListener class has been set usingsetTraceListenerClass(String)
, returns a newly created instance of that class. Otherwise, returns null. - Throws:
XPathException
- if the supplied TraceListenerClass cannot be instantiated as an instance of TraceListener- Since:
- 9.1.
-
setTraceListener
Set the TraceListener to be used for run-time tracing of instruction execution.Note: this method should not be used if the Configuration is multithreading. In that situation, use
setCompileWithTracing(boolean)
to force stylesheets and queries to be compiled with trace code enabled, and useController.addTraceListener(net.sf.saxon.lib.TraceListener)
to supply a TraceListener at run time.- Parameters:
traceListener
- The TraceListener to be used. If null is supplied, any existing TraceListener is removed- Since:
- 8.4
-
setTraceListenerClass
Set the name of the trace listener class to be used for run-time tracing of instruction execution. A new instance of this class will be created for each query or transformation that requires tracing. The class must be an instance ofTraceListener
.- Parameters:
className
- the name of the trace listener class. If null, any existing trace listener is removed from the configuration.- Throws:
IllegalArgumentException
- if the class cannot be instantiated or does not implement TraceListener- Since:
- 9.1. Changed in 9.4 to allow null to be supplied.
-
getTraceListenerClass
Get the name of the trace listener class to be used for run-time tracing of instruction execution. A new instance of this class will be created for each query or transformation that requires tracing. The class must be an instance ofTraceListener
.- Returns:
- the name of the trace listener class, or null if no trace listener class has been nominated.
- Since:
- 9.1
-
isCompileWithTracing
public boolean isCompileWithTracing()Determine whether compile-time generation of trace code was requested- Returns:
- true if compile-time generation of code was requested
- Since:
- 8.8
-
setCompileWithTracing
public void setCompileWithTracing(boolean trace) Request compile-time generation of trace code (or not)- Parameters:
trace
- true if compile-time generation of trace code is required- Since:
- 8.8
-
setOptimizerTracing
public void setOptimizerTracing(boolean trace) Set optimizer tracing on or off- Parameters:
trace
- set to true to switch optimizer tracing on, false to switch it off
-
isOptimizerTracing
public boolean isOptimizerTracing()Test whether optimizer tracing is on or off- Returns:
- true if optimizer tracing is switched on
-
makeTraceListener
Create an instance of a TraceListener with a specified class name- Parameters:
className
- The fully qualified class name of the TraceListener to be constructed- Returns:
- the newly constructed TraceListener
- Throws:
XPathException
- if the requested class does not implement the net.sf.saxon.trace.TraceListener interface
-
registerExtensionFunction
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 ofExtensionFunctionDefinition
, 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 object that implements the extension function.- Since:
- 9.2
-
getIntegratedFunctionLibrary
Get the IntegratedFunction library containing integrated extension functions- Returns:
- the IntegratedFunctionLibrary
- Since:
- 9.2
-
getVendorFunctionLibrary
Get the FunctionLibrary used to bind calls on Saxon-defined extension functions. This method is intended for internal use only.- Returns:
- the FunctionLibrary used for extension functions in the Saxon library.
-
addExtensionBinders
Add the registered extension binders to a function library. This method is intended primarily for internal use- Parameters:
list
- the function library list
-
newUserFunction
Make a UserFunction object. This method is for internal use.- Parameters:
memoFunction
- true if the function is to be a memo function, This option is ignored in Saxon-HE.- Returns:
- a new UserFunction object
-
setCollationURIResolver
Set a CollationURIResolver to be used to resolve collation URIs (that is, to take a URI identifying a collation, and return the corresponding collation). Note that Saxon attempts first to resolve a collation URI using the resolver registered with the Controller; if that returns null, it tries again using the resolver registered with the Configuration. Note that it is undefined whether collation URIs are resolved at compile time or at run-time. It is therefore inadvisable to change the CollationURIResolver after compiling a query or stylesheet and before running it.- Parameters:
resolver
- the collation URI resolver to be used. This replaces any collation URI resolver previously registered.- Since:
- 8.5
-
getCollationURIResolver
Get the collation URI resolver associated with this configuration. This will return the CollationURIResolver previously set using thesetCollationURIResolver(net.sf.saxon.lib.CollationURIResolver)
method; if this has not been called, it returns the system-defined collation URI resolver- Returns:
- the registered CollationURIResolver
- Since:
- 8.5
-
getCollationMap
Get the collation map, which can be used to register named collations (and a default collation) at the Configuration level. Any collations registered in this collation map apply to all queries, stylesheets, and Xpath expressions compiled under this collation. The effective contents of the collation map are the contents at the time the query or stylesheet is compiled.- Returns:
- the collation map
-
setDefaultCollection
Set the default collection.If no default collection URI is specified, then a request for the default collection is handled by calling the registered collection URI resolver with an argument of null.
- Parameters:
uri
- the URI of the default collection. Calling the collection() function with no arguments is equivalent to calling collection() with this URI as an argument. The URI will be dereferenced by passing it to the registered CollectionURIResolver. If null is supplied, any existing default collection is removed.- Since:
- 9.2
-
getDefaultCollection
Get the URI of the default collection. Returns null if no default collection URI has been registered.- Returns:
- the default collection URI. This is dereferenced in the same way as a normal collection URI (via the CollectionURIResolver) to return a sequence of nodes
- Since:
- 9.2
-
setCollectionURIResolver
Set a CollectionURIResolver to be used to resolve collection URIs (that is, the URI supplied in a call to the collection() function). Collection URIs are always resolved at run-time, using the CollectionURIResolver in force at the time the collection() function is called.- Parameters:
resolver
- the collection URI resolver to be used. This replaces any collection URI resolver previously registered. The value must not be null.- Since:
- 8.5
-
getCollectionURIResolver
Get the collection URI resolver associated with this configuration. This will return the CollectionURIResolver previously set using thesetCollectionURIResolver(net.sf.saxon.lib.CollectionURIResolver)
method; if this has not been called, it returns the system-defined collection URI resolver- Returns:
- the registered CollectionURIResolver
- Since:
- 8.5
-
setLocalizerFactory
Set the localizer factory to be used- Parameters:
factory
- the LocalizerFactory- Since:
- 9.2
-
getLocalizerFactory
Get the localizer factory in use- Returns:
- the LocalizerFactory, if any. If none has been set, returns null.
- Since:
- 9.2
-
setDefaultLanguage
Set the default language to be used for number and date formatting when no language is specified. If none is set explicitly, the default Locale for the Java Virtual Machine is used.- Parameters:
language
- the default language to be used, as an ISO code for example "en" or "fr-CA"- Since:
- 9.2
-
getDefaultLanguage
Get the default language. Unless an explicit default is set, this will be the language of the default Locale for the Java Virtual Machine- Returns:
- the default language
- Since:
- 9.2
-
setDefaultCountry
Set the default country to be used for number and date formatting when no country is specified. If none is set explicitly, the default Locale for the Java Virtual Machine is used.- Parameters:
country
- the default country to be used, as an ISO code for example "US" or "GB"- Since:
- 9.2
-
getDefaultCountry
Get the default country to be used for number and date formatting when no country is specified. If none is set explicitly, the default Locale for the Java Virtual Machine is used.- Returns:
- the default country to be used, as an ISO code for example "US" or "GB"
- Since:
- 9.2
-
makeNumberer
Load a Numberer class for a given language and check it is OK. This method is provided primarily for internal use.- Parameters:
language
- the language for which a Numberer is required. May be null, indicating default languagecountry
- the country for which a Numberer is required. May be null, indicating default country- Returns:
- a suitable numberer. If no specific numberer is available for the language, the default numberer (normally English) is used.
-
setModuleURIResolver
Set a user-defined ModuleURIResolver for resolving URIs used in "import module" declarations in an XQuery prolog. This acts as the default value for the ModuleURIResolver in the StaticQueryContext, and may be overridden by a more specific ModuleURIResolver nominated as part of the StaticQueryContext.- Parameters:
resolver
- the URI resolver for XQuery modules. May be null, in which case any existing Module URI Resolver is removed from the configuration
-
setModuleURIResolver
Create and register an instance of a ModuleURIResolver with a specified class name. This will be used for resolving URIs in XQuery "import module" declarations, unless a more specific ModuleURIResolver has been nominated as part of the StaticQueryContext.- Parameters:
className
- The fully-qualified name of the LocationHintResolver class- Throws:
TransformerException
- if the requested class does not implement the net.sf.saxon.LocationHintResolver interface
-
getModuleURIResolver
Get the user-defined ModuleURIResolver for resolving URIs used in "import module" declarations in the XQuery prolog; returns null if none has been explicitly set.- Returns:
- the resolver for Module URIs
-
getStandardModuleURIResolver
Get the standard system-defined ModuleURIResolver for resolving URIs used in "import module" declarations in the XQuery prolog.- Returns:
- the standard system-defined ModuleURIResolver for resolving URIs
-
setSchemaURIResolver
Set a user-defined SchemaURIResolver for resolving URIs used in "import schema" declarations.- Parameters:
resolver
- the URI resolver used for import schema declarations. May be null, in which case any existing URI resolver is removed from the Configuration.
-
getSchemaURIResolver
Get the user-defined SchemaURIResolver for resolving URIs used in "import schema" declarations; if none has been explicitly set, returns null.- Returns:
- the user-defined SchemaURIResolver for resolving URIs
-
getDefaultXsltCompilerInfo
Get the default options for XSLT compilation- Returns:
- the default options for XSLT compilation. The CompilerInfo object will reflect any options set using other methods available for this Configuration object
-
getDefaultStaticQueryContext
Get the default options for XQuery compilation- Returns:
- the default XQuery static context for this configuration
-
getRecoveryPolicy
public int getRecoveryPolicy()Determine how recoverable run-time errors are to be handled. This applies only if the standard ErrorListener is used.- Returns:
- the current recovery policy. The options are
RECOVER_SILENTLY
,RECOVER_WITH_WARNINGS
, orDO_NOT_RECOVER
. - Since:
- 8.4
-
setRecoveryPolicy
public void setRecoveryPolicy(int recoveryPolicy) Determine how recoverable run-time errors are to be handled. This applies only if the standard ErrorListener is used. The recovery policy applies to errors classified in the XSLT 2.0 specification as recoverable dynamic errors, but only in those cases where Saxon provides a choice over how the error is handled: in some cases, Saxon makes the decision itself.- Parameters:
recoveryPolicy
- the recovery policy to be used. The options areRECOVER_SILENTLY
,RECOVER_WITH_WARNINGS
, orDO_NOT_RECOVER
.- Since:
- 8.4
-
getMessageEmitterClass
Get the name of the class that will be instantiated to create a MessageEmitter, to process the output of xsl:message instructions in XSLT.- Returns:
- the full class name of the message emitter class.
- Since:
- 8.4
-
setMessageEmitterClass
Set the name of the class that will be instantiated to to process the output of xsl:message instructions in XSLT.- Parameters:
messageReceiverClassName
- the full class name of the message receiver. This must implement net.sf.saxon.event.Receiver.- Since:
- 8.4
-
getSourceParserClass
Get the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions). This method is retained in Saxon for backwards compatibility, but the preferred way of choosing an XML parser is to use JAXP interfaces, for example by supplying a JAXP Source object initialized with an appropriate implementation of org.xml.sax.XMLReader.- Returns:
- the fully qualified name of the XML parser class
-
setSourceParserClass
Set the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions). This method is retained in Saxon for backwards compatibility, but the preferred way of choosing an XML parser is to use JAXP interfaces, for example by supplying a JAXP Source object initialized with an appropriate implementation of org.xml.sax.XMLReader.- Parameters:
sourceParserClass
- the fully qualified name of the XML parser class. This must implement the SAX2 XMLReader interface.
-
getStyleParserClass
Get the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules. This method is retained in Saxon for backwards compatibility, but the preferred way of choosing an XML parser is to use JAXP interfaces, for example by supplying a JAXP Source object initialized with an appropriate implementation of org.xml.sax.XMLReader.- Returns:
- the fully qualified name of the XML parser class
-
setStyleParserClass
Set the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules. This method is retained in Saxon for backwards compatibility, but the preferred way of choosing an XML parser is to use JAXP interfaces, for example by supplying a JAXP Source object initialized with an appropriate implementation of org.xml.sax.XMLReader.- Parameters:
parser
- the fully qualified name of the XML parser class
-
getOutputURIResolver
Get the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.- Returns:
- the OutputURIResolver. If none has been supplied explicitly, the default OutputURIResolver is returned.
- Since:
- 8.4
-
setOutputURIResolver
Set the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.- Parameters:
outputURIResolver
- the OutputURIResolver to be used.- Since:
- 8.4
-
setSerializerFactory
Set a custom SerializerFactory. This will be used to create a serializer for a given set of output properties and result destination.- Parameters:
factory
- a custom SerializerFactory- Since:
- 8.8
-
getSerializerFactory
Get the SerializerFactory. This returns the standard built-in SerializerFactory, unless a custom SerializerFactory has been registered.- Returns:
- the SerializerFactory in use
- Since:
- 8.8
-
getCharacterSetFactory
Get the CharacterSetFactory. Note: at present this cannot be changed.- Returns:
- the CharacterSetFactory in use.
- Since:
- 9.2
-
setDefaultSerializationProperties
Set the default serialization properties- Parameters:
props
- the default properties
-
getDefaultSerializationProperties
Get the default serialization properties- Returns:
- the default properties
-
isTiming
public boolean isTiming()Determine whether brief progress messages and timing information will be output to System.err. This method is provided largely for internal use. Progress messages are normally controlled directly from the command line interfaces, and are not normally used when driving Saxon from the Java API.- Returns:
- true if these messages are to be output.
-
setTiming
public void setTiming(boolean timing) Determine whether brief progress messages and timing information will be output to System.err. This method is provided largely for internal use. Progress messages are normally controlled directly from the command line interfaces, and are not normally used when- Parameters:
timing
- true if these messages are to be output.
-
isVersionWarning
public boolean isVersionWarning()Determine whether a warning is to be output when running against a stylesheet labelled as version="1.0". The XSLT specification requires such a warning unless the user disables it.- Returns:
- true if these messages are to be output.
- Since:
- 8.4
-
setVersionWarning
public void setVersionWarning(boolean warn) Determine whether a warning is to be output when the version attribute of the stylesheet does not match the XSLT processor version. (In the case where the stylesheet version is "1.0", the XSLT specification requires such a warning unless the user disables it.)- Parameters:
warn
- true if these warning messages are to be output.- Since:
- 8.4
-
isAllowExternalFunctions
public boolean isAllowExternalFunctions()Determine whether calls to external Java functions are permitted.- Returns:
- true if such calls are permitted.
- Since:
- 8.4
-
setAllowExternalFunctions
public void setAllowExternalFunctions(boolean allowExternalFunctions) Determine whether calls to external Java functions are permitted. Allowing external function calls is potentially a security risk if the stylesheet or Query is untrusted, as it allows arbitrary Java methods to be invoked, which can examine or modify the contents of filestore and other resources on the machine where the query/stylesheet is executed.Setting the value to false disallows all of the following:
- Calls to Java extension functions
- Use of the XSLT system-property() function to access Java system properties
- Use of a relative URI in the
xsl:result-document
instruction - Calls to XSLT extension instructions
Note that this option does not disable use of the
doc()
function or similar functions to access the filestore of the machine where the transformation or query is running. That should be done using a user-suppliedURIResolver
- Parameters:
allowExternalFunctions
- true if external function calls are to be permitted.- Since:
- 8.4
-
isTraceExternalFunctions
public boolean isTraceExternalFunctions()Determine whether calls on external functions are to be traced for diagnostic purposes.- Returns:
- true if tracing is enabled for calls to external Java functions
-
setRetainDTDAttributeTypes
public void setRetainDTDAttributeTypes(boolean useTypes) throws TransformerFactoryConfigurationError Deprecated.since 9.2 This feature was dropped from the final XDM specification and will be dropped in a future Saxon release. The facility is supported only in Saxon-EE. Use an XSD schema to define the attribute types instead.Say whether attribute types obtained from a DTD are to be used to set type annotations on the resulting nodes.- Parameters:
useTypes
- set to true if DTD types are to be taken into account- Throws:
TransformerFactoryConfigurationError
- if called in Saxon-HE- Since:
- 8.4
-
isRetainDTDAttributeTypes
public boolean isRetainDTDAttributeTypes()Ask whether attribute types obtained from a DTD are to be used to set type annotations on the resulting nodes- Returns:
- true if DTD types are to be taken into account
- Since:
- 8.4
-
setTraceExternalFunctions
public void setTraceExternalFunctions(boolean traceExternalFunctions) Determine whether calls on external functions are to be traced for diagnostic purposes.- Parameters:
traceExternalFunctions
- true if tracing is to be enabled for calls to external Java functions
-
isValidation
public boolean isValidation()Determine whether the XML parser for source documents will be asked to perform validation of source documents- Returns:
- true if DTD validation is requested.
- Since:
- 8.4
-
setValidation
public void setValidation(boolean validation) Determine whether the XML parser for source documents will be asked to perform DTD validation of source documents- Parameters:
validation
- true if DTD validation is to be requested.- Since:
- 8.4
-
makeDocumentProjector
Create a document projector for a given path map. Document projection is available only in Saxon-EE, so the Saxon-B version of this method throws an exception- Parameters:
map
- the path map used to control document projection- Returns:
- a push filter that implements document projection
- Throws:
UnsupportedOperationException
- if this is not a schema-aware configuration, or if no Saxon-EE license is available
-
getSchemaValidationMode
public int getSchemaValidationMode()Ask whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation, and if so, in what validation mode- Returns:
- the schema validation mode previously set using setSchemaValidationMode(),
or the default mode
Validation.STRIP
otherwise.
-
setSchemaValidationMode
public void setSchemaValidationMode(int validationMode) Say whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation, and if so, in what validation mode. This value may be overridden at the level of a Controller for an individual transformation or query.- Parameters:
validationMode
- the validation (or construction) mode to be used for source documents. One ofValidation.STRIP
,Validation.PRESERVE
,Validation.STRICT
,Validation.LAX
- Since:
- 8.4
-
setValidationWarnings
public void setValidationWarnings(boolean warn) Indicate whether schema validation failures on result documents are to be treated as fatal errors or as warnings.- Parameters:
warn
- true if schema validation failures are to be treated as warnings; false if they are to be treated as fatal errors.- Since:
- 8.4
-
isValidationWarnings
public boolean isValidationWarnings()Determine whether schema validation failures on result documents are to be treated as fatal errors or as warnings.- Returns:
- true if validation errors are to be treated as warnings (that is, the validation failure is reported but processing continues as normal); false if validation errors are fatal.
- Since:
- 8.4
-
setExpandAttributeDefaults
public void setExpandAttributeDefaults(boolean expand) Indicate whether attributes that have a fixed or default value are to be expanded when generating a final result tree. By default (and for conformance with the W3C specifications) it is required that fixed and default values should be expanded. However, there are use cases for example when generating XHTML when this serves no useful purpose and merely bloats the output.This option can be overridden at the level of a PipelineConfiguration
- Parameters:
expand
- true if fixed and default values are to be expanded as required by the W3C specifications; false if this action is to be disabled. Note that this only affects the validation of final result trees; it is not possible to suppress expansion of fixed or default values on input documents, as this would make the type annotations on input nodes unsound.- Since:
- 9.0
-
isExpandAttributeDefaults
public boolean isExpandAttributeDefaults()Determine whether elements and attributes that have a fixed or default value are to be expanded. This option applies both to DTD-defined attribute defaults and to schema-defined defaults for elements and attributes. If an XML parser is used that does not report whether defaults have been used, this option is ignored. *This option can be overridden at the level of a PipelineConfiguration
- Returns:
- true if elements and attributes that have a fixed or default value are to be expanded, false if defaults are not to be expanded. The default value is true. Note that the setting "false" is potentially non-conformant with the W3C specifications.
- Since:
- 9.0
-
getNamePool
Get the target namepool to be used for stylesheets/queries and for source documents.- Returns:
- the target name pool. If no NamePool has been specified explicitly, the default NamePool is returned.
- Since:
- 8.4
-
setNamePool
Set the NamePool to be used for stylesheets/queries and for source documents.Using this method allows several Configurations to share the same NamePool. This was the normal default arrangement until Saxon 8.9, which changed the default so that each Configuration uses its own NamePool.
Sharing a NamePool creates a potential bottleneck, since changes to the namepool are synchronized.
- Parameters:
targetNamePool
- The NamePool to be used.- Since:
- 8.4
-
getTypeHierarchy
Get the TypeHierarchy: a cache holding type information- Returns:
- the type hierarchy cache
-
getDocumentNumberAllocator
Get the document number allocator. The document number allocator is used to allocate a unique number to each document built under this configuration. The document number forms the basis of all tests for node identity; it is therefore essential that when two documents are accessed in the same XPath expression, they have distinct document numbers. Normally this is ensured by building them under the same Configuration. Using this method together withsetDocumentNumberAllocator(net.sf.saxon.tree.util.DocumentNumberAllocator)
, however, it is possible to have two different Configurations that share a single DocumentNumberAllocator- Returns:
- the current DocumentNumberAllocator
- Since:
- 9.0
-
setDocumentNumberAllocator
Set the document number allocator. The document number allocator is used to allocate a unique number to each document built under this configuration. The document number forms the basis of all tests for node identity; it is therefore essential that when two documents are accessed in the same XPath expression, they have distinct document numbers. Normally this is ensured by building them under the same Configuration. Using this method together withgetDocumentNumberAllocator()
, however, it is possible to have two different Configurations that share a single DocumentNumberAllocatorThis method is for advanced applications only. Misuse of the method can cause problems with node identity. The method should not be used except while initializing a Configuration, and it should be used only to arrange for two different configurations to share the same DocumentNumberAllocators. In this case they should also share the same NamePool.
- Parameters:
allocator
- the DocumentNumberAllocator to be used- Since:
- 9.0
-
isCompatible
Determine whether two Configurations are compatible. When queries, transformations, and path expressions are run, all the Configurations used to build the documents and to compile the queries and stylesheets must be compatible. Two Configurations are compatible if they share the same NamePool and the same DocumentNumberAllocator.- Parameters:
other
- the other Configuration to be compared with this one- Returns:
- true if the two configurations are compatible
-
getGlobalDocumentPool
Get the global document pool. This is used for documents preloaded during query or stylesheet compilation. The user application can preload documents into the global pool, where they will be found if any query or stylesheet requests the specified document using the doc() or document() function.- Returns:
- the global document pool
- Since:
- 9.1
-
isStripsAllWhiteSpace
public boolean isStripsAllWhiteSpace()Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.- Returns:
- true if all whitespace-only text nodes are stripped.
- Since:
- 8.4
-
setStripsAllWhiteSpace
public void setStripsAllWhiteSpace(boolean stripsAllWhiteSpace) Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.- Parameters:
stripsAllWhiteSpace
- if all whitespace-only text nodes are to be stripped.- Since:
- 8.4
-
setStripsWhiteSpace
public void setStripsWhiteSpace(int kind) Set which kinds of whitespace-only text node should be stripped.- Parameters:
kind
- the kind of whitespace-only text node that should be stripped when building a source tree. One ofWhitespace.NONE
(none),Whitespace.ALL
(all), orWhitespace.IGNORABLE
(element-content whitespace as defined in a DTD or schema)
-
getStripsWhiteSpace
public int getStripsWhiteSpace()Set which kinds of whitespace-only text node should be stripped.- Returns:
- kind the kind of whitespace-only text node that should be stripped when building
a source tree. One of
Whitespace.NONE
(none),Whitespace.ALL
(all), orWhitespace.IGNORABLE
(element-content whitespace as defined in a DTD or schema)
-
getSourceParser
Get a parser for source documents. The parser is allocated from a pool if any are available from the pool: the client should ideally return the parser to the pool after use, so that it can be reused. This method is intended primarily for internal use.- Returns:
- a parser, in which the namespace properties must be set as follows:
namespaces=true; namespace-prefixes=false. The DTD validation feature of the parser will be set
on or off depending on the
setValidation(boolean)
setting. - Throws:
TransformerFactoryConfigurationError
- if a failure occurs configuring the parser for use.
-
reuseSourceParser
Return a source parser to the pool, for reuse- Parameters:
parser
- The parser: the caller must not supply a parser that was obtained by any mechanism other than calling the getSourceParser() method. Must not be null.
-
getStyleParser
Get the parser for stylesheet documents. This parser is also used for schema documents. This method is intended for internal use only.- Returns:
- an XML parser (a SAX2 parser) that can be used for stylesheets and schema documents
- Throws:
TransformerFactoryConfigurationError
- if an error occurs configuring the parser
-
reuseStyleParser
Return a stylesheet (or schema) parser to the pool, for reuse- Parameters:
parser
- The parser: the caller must not supply a parser that was obtained by any mechanism other than calling the getStyleParser() method.
-
loadSchema
Simple interface to load a schema document- Parameters:
absoluteURI
- the absolute URI of the location of the schema document- Throws:
SchemaException
- if the schema document at the given location cannot be read or is invalid
-
readSchema
public String readSchema(PipelineConfiguration pipe, String baseURI, String schemaLocation, String expected) throws SchemaException Read a schema from a given schema location This method is intended for internal use.- Parameters:
pipe
- the PipelineConfigurationbaseURI
- the base URI of the instruction requesting the reading of the schemaschemaLocation
- the location of the schema to be readexpected
- The expected targetNamespace of the schema being read, or null if there is no expectation- Returns:
- the target namespace of the schema; null if there is no expectation
- Throws:
UnsupportedOperationException
- when called in the non-schema-aware version of the productSchemaException
- if the schema cannot be read
-
readMultipleSchemas
public void readMultipleSchemas(PipelineConfiguration pipe, String baseURI, Collection schemaLocations, String expected) throws SchemaException Read schemas from a list of schema locations. This method is intended for internal use.- Parameters:
pipe
- the pipeline configurationbaseURI
- the base URI against which the schema locations are to be resolvedschemaLocations
- the relative URIs specified as schema locationsexpected
- the namespace URI which is expected as the target namespace of the loaded schema- Throws:
SchemaException
- if an error occurs
-
readInlineSchema
public String readInlineSchema(NodeInfo root, String expected, ErrorListener errorListener) throws SchemaException Read an inline schema from a stylesheet. This method is intended for internal use.- Parameters:
root
- the xs:schema element in the stylesheetexpected
- the target namespace expected; null if there is no expectation.errorListener
- The destination for error messages. May be null, in which case the errorListener registered with this Configuration is used.- Returns:
- the actual target namespace of the schema
- Throws:
SchemaException
- if the schema cannot be processed
-
needEnterpriseEdition
protected void needEnterpriseEdition()Throw an error indicating that a request cannot be satisfied because it requires the schema-aware edition of Saxon -
addSchemaSource
Load a schema, which will be available for use by all subsequent operations using this Configuration. Any errors will be notified to the ErrorListener associated with this Configuration.- Parameters:
schemaSource
- the JAXP Source object identifying the schema document to be loaded- Throws:
SchemaException
- if the schema cannot be read or parsed or if it is invalidUnsupportedOperationException
- if the configuration is not schema-aware- Since:
- 8.4
-
addSchemaSource
public void addSchemaSource(Source schemaSource, ErrorListener errorListener) throws SchemaException Load a schema, which will be available for use by all subsequent operations using this EnterpriseConfiguration.- Parameters:
schemaSource
- the JAXP Source object identifying the schema document to be loadederrorListener
- the ErrorListener to be notified of any errors in the schema.- Throws:
SchemaException
- if the schema cannot be read or parsed or if it is invalid
-
addSchemaForBuiltInNamespace
Add a built-in schema for a given namespace. This is a no-op if the configuration is not schema-aware- Parameters:
namespace
- the namespace. Currently built-in schemas are available for the XML and FN namespaces
-
isSchemaAvailable
Determine whether the Configuration contains a cached schema for a given target namespace- Parameters:
targetNamespace
- the target namespace of the schema being sought (supply "" for the unnamed namespace)- Returns:
- true if the schema for this namespace is available, false if not.
-
clearSchemaCache
public void clearSchemaCache()Remove all schema components that have been loaded into this Configuration. This method must not be used if any processes (such as stylesheet or query compilations or executions) are currently active. In a multi-threaded environment, it is the user's responsibility to ensure that this method is not called unless it is safe to do so. -
getImportedNamespaces
Get the set of namespaces of imported schemas- Returns:
- a Set whose members are the namespaces of all schemas in the schema cache, as String objects
-
sealNamespace
Mark a schema namespace as being sealed. This is done when components from this namespace are first used for validating a source document or compiling a source document or query. Once a namespace has been sealed, it is not permitted to change the schema components in that namespace by redefining them, deriving new types by extension, or adding to their substitution groups.- Parameters:
namespace
- the namespace URI of the components to be sealed
-
getExtensionsOfType
Get the set of complex types that have been defined as extensions of a given type. Note that we do not seal the schema namespace, so this list is not necessarily final; we must assume that new extensions of built-in simple types can be added at any time- Parameters:
type
- the type whose extensions are required- Returns:
- an iterator over the types that are derived from the given type by extension
-
importComponents
Import a precompiled Schema Component Model from a given Source. The schema components derived from this schema document are added to the cache of schema components maintained by this SchemaManager- Parameters:
source
- the XML file containing the schema component model, as generated by a previous call onexportComponents(net.sf.saxon.event.Receiver)
- Throws:
XPathException
- if an error occurs
-
exportComponents
Export a precompiled Schema Component Model containing all the components (except built-in components) that have been loaded into this Processor.- Parameters:
out
- the destination to recieve the precompiled Schema Component Model in the form of an XML document- Throws:
XPathException
- if a failure occurs
-
getElementDeclaration
Get a global element declaration. This method is intended for internal use.- Parameters:
fingerprint
- the NamePool fingerprint of the name of the required element declaration- Returns:
- the element declaration whose name matches the given fingerprint, or null if no element declaration with this name has been registered.
-
getElementDeclaration
Get a global element declaration.- Parameters:
qName
- the name of the required element declaration- Returns:
- the element declaration whose name matches the given fingerprint, or null if no element declaration with this name has been registered.
-
getAttributeDeclaration
Get a global attribute declaration. This method is intended for internal use- Parameters:
fingerprint
- the namepool fingerprint of the required attribute declaration- Returns:
- the attribute declaration whose name matches the given fingerprint, or null if no element declaration with this name has been registered.
-
getSchemaType
Get the top-level schema type definition with a given fingerprint. This method is intended for internal use and for use by advanced applications. (The SchemaType object returned cannot yet be considered a stable API, and may be superseded when a JAXP API for schema information is defined.)- Parameters:
fingerprint
- the fingerprint of the schema type- Returns:
- the schema type , or null if there is none with this name.
-
isDeclaredNotation
Ask whether a given notation has been declared in the schema- Specified by:
isDeclaredNotation
in interfaceNotationSet
- Parameters:
uri
- the targetNamespace of the notationlocal
- the local part of the notation name- Returns:
- true if the notation has been declared, false if not
- Since:
- 9.3
-
getExternalObjectType
Get the external object type corresponding to a fingerprint if it is indeed an external object type, otherwise return null- Parameters:
fingerprint
- the name of the type- Returns:
- the external object type it the name is in the JAVA_TYPE namespace, otherwise null.
-
checkTypeDerivationIsOK
public void checkTypeDerivationIsOK(SchemaType derived, SchemaType base, int block) throws SchemaException Check that a type is validly derived from another type, following the rules for the Schema Component Constraint "Is Type Derivation OK (Simple)" (3.14.6) or "Is Type Derivation OK (Complex)" (3.4.6) as appropriate.- Parameters:
derived
- the derived typebase
- the base type; the algorithm tests whether derivation from this type is permittedblock
- the derivations that are blocked by the relevant element declaration- Throws:
SchemaException
- if the derivation is not allowed
-
getDocumentValidator
public Receiver getDocumentValidator(Receiver receiver, String systemId, int validationMode, int stripSpace, SchemaType schemaType, int topLevelElementName) Get a document-level validator to add to a Receiver pipeline. This method is intended for internal use.- Parameters:
receiver
- The receiver to which events should be sent after validationsystemId
- the base URI of the document being validatedvalidationMode
- for example Validation.STRICT or Validation.STRIP. The integer may also have the bit Validation.VALIDATE_OUTPUT set, indicating that the strean being validated is to be treated as a final output stream (which means multiple errors can be reported)stripSpace
- options for space strippingschemaType
- The type against which the outermost element of the document must be validated (null if there is no constraint)topLevelElementName
- the namepool name code of the required top-level element in the instance document, or -1 if there is no specific element required- Returns:
- A Receiver to which events can be sent for validation
-
getElementValidator
public SequenceReceiver getElementValidator(SequenceReceiver receiver, NodeName elemName, int locationId, SchemaType schemaType, int validation) throws XPathException Get a Receiver that can be used to validate an element, and that passes the validated element on to a target receiver. If validation is not supported, the returned receiver will be the target receiver. This method is intended for internal use.- Parameters:
receiver
- the target receiver tp receive the validated elementelemName
- the name of the element to be validated. This must correspond to the name of an element declaration in a loaded schemalocationId
- current location in the stylesheet or queryschemaType
- the schema type (typically a complex type) against which the element is to be validatedvalidation
- The validation mode, for example Validation.STRICT or Validation.LAX- Returns:
- The target receiver, indicating that with this configuration, no validation is performed.
- Throws:
XPathException
- if a validator for the element cannot be created
-
validateAttribute
public SimpleType validateAttribute(int nameCode, CharSequence value, int validation) throws ValidationException Validate an attribute value. This method is intended for internal use.- Parameters:
nameCode
- the name of the attributevalue
- the value of the attribute as a stringvalidation
- STRICT or LAX- Returns:
- the type annotation to apply to the attribute node
- Throws:
ValidationException
- if the value is invalid
-
getAnnotationStripper
Add to a pipeline a receiver that strips all type annotations. This has a null implementation in the Saxon-B product, because type annotations can never arise. This method is intended for internal use.- Parameters:
destination
- the Receiver that events will be written to after whitespace stripping- Returns:
- the Receiver to which events should be sent for stripping
-
makeParser
Create a new SAX XMLReader object using the class name provided.
The named class must exist and must implement the org.xml.sax.XMLReader or Parser interface.
This method returns an instance of the parser named. This method is intended for internal use.- Parameters:
className
- A string containing the name of the SAX parser class, for example "com.microstar.sax.LarkDriver"- Returns:
- an instance of the Parser class named, or null if it is not loadable or is not a Parser.
- Throws:
TransformerFactoryConfigurationError
- if a failure occurs configuring the parser of this class
-
newExpressionParser
public ExpressionParser newExpressionParser(String language, boolean updating, DecimalValue languageVersion) Make an expression Parser for a specified version of XPath or XQuery- Parameters:
language
- set to "XP" (XPath) or "XQ" (XQuery)updating
- indicates whether or not XQuery update syntax may be used. Note that XQuery Update is supported only in Saxon-EElanguageVersion
- the required version (e.g "1.0", "3.0")- Returns:
- the QueryParser
- Throws:
UnsupportedOperationException
- if a parser that supports update syntax is requested on Saxon-B
-
getLocale
Get a locale given a language code in XML format. This method is intended for internal use.- Parameters:
lang
- the language code- Returns:
- the Java locale
-
setDebugger
Set the debugger to be used. This method is provided for advanced users only, and is subject to change.- Parameters:
debugger
- the debugger to be used, or null if no debugger is to be used
-
getDebugger
Get the debugger in use. This will be null if no debugger has been registered. This method is provided for advanced users only, and is subject to change.- Returns:
- the debugger in use, or null if none is in use
-
makeSlotManager
Factory method to create a SlotManager. This method is provided for advanced users only, and is subject to change.- Returns:
- a SlotManager (which is a skeletal stack frame representing the mapping of variable names to slots on the stack frame)
-
makeStreamingTransformer
Create a streaming transformer- Parameters:
context
- the initial XPath contextmode
- the initial mode, which must be a streaming mode- Returns:
- a Receiver to which the streamed input document will be pushed
- Throws:
XPathException
- if a streaming transformer cannot be created (which is always the case in Saxon-HE and Saxon-PE)
-
obtainOptimizer
Factory method to get an Optimizer. This method is intended for internal use only.- Returns:
- the optimizer used in this configuration, which is created if necessary
-
makeClosure
public Value makeClosure(Expression expression, int ref, XPathContext context) throws XPathException Make a Closure, given the expected reference count- Parameters:
expression
- the expression to be evaluatedref
- the (nominal) number of times the value of the expression is requiredcontext
- the XPath dynamic evaluation context- Returns:
- the constructed Closure
- Throws:
XPathException
- if a failure occurs constructing the Closure
-
makeSequenceExtent
public ValueRepresentation makeSequenceExtent(Expression expression, int ref, XPathContext context) throws XPathException Make a SequenceExtent, given the expected reference count- Parameters:
expression
- the expression to be evaluatedref
- the (nominal) number of times the value of the expression is requiredcontext
- the XPath dynamic evaluation context- Returns:
- the constructed SequenceExtent
- Throws:
XPathException
- if evaluation of the expression fails
-
makeStyleNodeFactory
Factory method to get the StyleNodeFactory, used for constructing elements in a stylesheet document- Returns:
- the StyleNodeFactory used in this Configuration
-
setLazyConstructionMode
public void setLazyConstructionMode(boolean lazy) Set lazy construction mode on or off. In lazy construction mode, element constructors are not evaluated until the content of the tree is required. Lazy construction mode is currently experimental and is therefore off by default.- Parameters:
lazy
- true to switch lazy construction mode on, false to switch it off.
-
isLazyConstructionMode
public boolean isLazyConstructionMode()Determine whether lazy construction mode is on or off. In lazy construction mode, element constructors are not evaluated until the content of the tree is required. Lazy construction mode is currently experimental and is therefore off by default.- Returns:
- true if lazy construction mode is enabled
-
registerExternalObjectModel
Register an external object model with this Configuration.- Parameters:
model
- The external object model. This can either be one of the system-supplied external object models for JDOM, XOM, or DOM, or a user-supplied external object model. This method is intended for advanced users only, and is subject to change.
-
getExternalObjectModel
Get the external object model with a given URI, if registered- Parameters:
uri
- the identifying URI of the required external object model- Returns:
- the requested external object model if available, or null otherwise
-
getExternalObjectModel
Get the external object model that recognizes a particular class of node, if available- Parameters:
nodeClass
- the class of the Node object in the external object model- Returns:
- the requested external object model if available, or null otherwise
-
getExternalObjectModels
Get all the registered external object models. This method is intended for internal use only.- Returns:
- a list of external object models supported. The members of the list are of
type
ExternalObjectModel
-
unravel
Get a NodeInfo corresponding to a DOM or other external Node, either by wrapping or unwrapping the external Node. This method is intended for internal use.- Parameters:
source
- A Source representing the wrapped or unwrapped external Node. This will typically be a DOMSource, but it may be a similar Source recognized by some other registered external object model.- Returns:
- If the Source is a DOMSource and the underlying node is a wrapper around a Saxon NodeInfo, returns the wrapped Saxon NodeInfo. If the Source is a DOMSource and the undelying node is not such a wrapper, returns a new Saxon NodeInfo that wraps the DOM Node. If the Source is any other kind of source, it is offered to each registered external object model for similar treatment. The result is the NodeInfo object obtained by wrapping or unwrapping the supplied external node.
- Throws:
IllegalArgumentException
- if the source object is not of a recognized class. This method doesnot call the registeredto resolve the Source
.
-
setDOMLevel
public void setDOMLevel(int level) Set the level of DOM interface to be used- Parameters:
level
- the DOM level. Must be 2 or 3. By default Saxon assumes that DOM level 3 is available; this parameter can be set to the value 2 to indicate that Saxon should not use methods unless they are available in DOM level 2. From Saxon 9.2, this switch remains available, but the use of DOM level 2 is untested and unsupported.
-
getDOMLevel
public int getDOMLevel()Get the level of DOM interface to be used- Returns:
- the DOM level. Always 2 or 3.
-
newStaticQueryContext
Get a new StaticQueryContext (which is also the factory class for creating a query parser)- Returns:
- a new StaticQueryContext
-
newPendingUpdateList
Get a new Pending Update List- Returns:
- the new Pending Update List
- Throws:
UnsupportedOperationException
- if called when using Saxon-B
-
makePipelineConfiguration
Make a PipelineConfiguration from the properties of this Configuration- Returns:
- a new PipelineConfiguration
- Since:
- 8.4
-
getConfiguration
Get the configuration, given the context. This is provided as a static method to make it accessible as an extension function.- Parameters:
context
- the XPath dynamic context- Returns:
- the Saxon Configuration for a given XPath dynamic context
-
setSourceResolver
Supply a SourceResolver. This is used for handling unknown implementations of theSource
interface: a user-supplied SourceResolver can handle such Source objects and translate them to a kind of Source that Saxon understands.- Parameters:
resolver
- the source resolver.
-
getSourceResolver
Get the current SourceResolver. If none has been supplied, a system-defined SourceResolver is returned.- Returns:
- the current SourceResolver
-
resolveSource
Resolve a Source.- Specified by:
resolveSource
in interfaceSourceResolver
- Parameters:
source
- A source object, typically the source supplied as the first argument toTransformer.transform(javax.xml.transform.Source, javax.xml.transform.Result)
or similar methods.config
- The Configuration. This provides the SourceResolver with access to configuration information; it also allows the SourceResolver to invoke the resolveSource() method on the Configuration object as a fallback implementation.- Returns:
- a source object that Saxon knows how to process. This must be an instance of one
of the classes StreamSource, SAXSource, DOMSource,
AugmentedSource
,NodeInfo
, orPullSource
. Return null if the Source object is not recognized - Throws:
XPathException
- if the Source object is recognized but cannot be processed
-
buildDocument
Build a document tree, using options set on this Configuration and on the supplied source object. Options set on the source object override options set in the Configuration. The Source object must be one of the kinds of source recognized by Saxon, or a source that can be resolved using the registeredSourceResolver
.- Parameters:
source
- the Source to be used. This may be anAugmentedSource
, allowing options to be specified for the way in which this document will be built. If an AugmentedSource is supplied then options set in the AugmentedSource take precendence over options set in the Configuration.From Saxon 9.2, this method always creates a new tree, it never wraps or returns an existing tree.
- Returns:
- the document node of the constructed document
- Throws:
XPathException
- if any errors occur during document parsing or validation. Detailed errors occurring during schema validation will be written to the ErrorListener associated with the AugmentedSource, if supplied, or with the Configuration otherwise.- Since:
- 8.9. Modified in 9.0 to avoid copying a supplied document where this is not necessary. Modified in 9.2 so that this interface always constructs a new tree; it never wraps an existing document, even if an AugmentedSource that requests wrapping is supplied.
-
buildDocument
Build a document, using specified options for parsing and building. This method always constructs a new tree, it never wraps an existing document (regardless of anything in the parseOptions)- Parameters:
source
- the source of the document to be constructed. If this is an AugmentedSource, then any parser options contained in the AugmentedSource take precedence over options specified in the parseOptions argument.parseOptions
- options for parsing and constructing the document. Any options that are not explicitly set in parseOptions default first to the values supplied in the source argument if it is an AugmentedSource, and then to the values set in this Configuration. The supplied parseOptions object is not modified.- Returns:
- the document node of the constructed document
- Throws:
XPathException
- if parsing fails, or if the Source represents a node other than a document node- Since:
- 9.2
-
makeEmitter
Load a named output emitter or SAX2 ContentHandler and check it is OK.- Parameters:
clarkName
- the QName of the user-supplied ContentHandler (requested as a prefixed value of the method attribute in xsl:output, or anywhere that serialization parameters are allowed), encoded in Clark format as {uri}localprops
- the properties to be used in the case of a dynamically-loaded ContentHandler.- Returns:
- a Receiver (despite the name, it is not required to be an Emitter)
- Throws:
XPathException
- if a failure occurs creating the Emitter
-
makeUnconstructedElement
public NodeInfo makeUnconstructedElement(ElementCreator instr, XPathContext context) throws XPathException Make an "unconstructed" (that is, lazily-constructed) element node- Parameters:
instr
- the instruction that creates the elementcontext
- the dynamic evaluation context- Returns:
- the lazily constructed element node
- Throws:
XPathException
- if an error occurs, for example if called in Saxon-HE
-
makeUnconstructedDocument
public NodeInfo makeUnconstructedDocument(DocumentInstr instr, XPathContext context) throws XPathException Make an "unconstructed" (that is, lazily-constructed) document node- Parameters:
instr
- the instruction that creates the document nodecontext
- the dynamic evaluation context- Returns:
- the lazily constructed document node
- Throws:
XPathException
- in Saxon-HE
-
setConfigurationProperty
Set a property of the configuration. This method underpins the setAttribute() method of the TransformerFactory implementation, and is provided to enable setting of Configuration properties using URIs without instantiating a TransformerFactory: specifically, this may be useful when running XQuery, and it is also used by the Validator API- Parameters:
name
- the URI identifying the property to be set. See the classFeatureKeys
for constants representing the property names that can be set.value
- the value of the property. Note that boolean values may be supplied either as a Boolean, or as one of the strings "0", "1", "true", "false", "yes", "no", "on", or "off".- Throws:
IllegalArgumentException
- if the property name is not recognized or if the value is not a valid value for the named property
-
requireBoolean
Validate a property value where the required type is boolean- Parameters:
propertyName
- the name of the propertyvalue
- the supplied value of the property. This may be either a java.lang.Boolean, or a string taking one of the values on|off, true|false, yes|no, or 1|0 (suited to the conventions of different configuration APIs that end up calling this method)- Returns:
- the value as a boolean
- Throws:
IllegalArgumentException
- if the supplied value cannot be validated as a recognized boolean value
-
requireString
-
instantiateClassName
-
getConfigurationProperty
Get a property of the configuration- Parameters:
name
- the name of the required property. See the classFeatureKeys
for constants representing the property names that can be requested.- Returns:
- the value of the property. Note that boolean values are returned as a Boolean, even if the value was supplied as a string (for example "true" or "on").
- Throws:
IllegalArgumentException
- thrown if the property is not one that Saxon recognizes.
-
setDebugBytecode
public void setDebugBytecode(boolean debugBytecode) This option is set to indicate that bytecode generation should be run in debugging mode. This will be used only during Saxon product development; the setting should not be enabled by users (and may not work in the released product).- Parameters:
debugBytecode
- true to switch debugging on
-
isDebugBytecode
public boolean isDebugBytecode()This option is set to indicate that bytecode generation should be run in debugging mode. This will be used only during Saxon product development; the setting should not be enabled by users (and may not work in the released product).- Returns:
- true if debugging is switched on
-
setDisplayBytecode
public void setDisplayBytecode(boolean displayBytecode) This option is set to indicate that bytecode generation should be run in display mode. This will be used only during Saxon product development; the setting should not be enabled by users (and may not work in the released product).- Parameters:
displayBytecode
- true to switch debugging on
-
isDisplayBytecode
public boolean isDisplayBytecode()This option is set to indicate that bytecode generation should be run in display mode. This will be used only during Saxon product development; the setting should not be enabled by users (and may not work in the released product).- Returns:
- true if display bytecode is switched on
-
setGenerateByteCode
public void setGenerateByteCode(boolean compileToBytecode) Say whether bytecode should be generated. The default setting is true in Saxon Enterprise Edition and false in all other cases. Setting the option to true has no effect if Saxon-EE is not available. Setting the option to false in Saxon-EE is permitted if for some reason bytecode generation is to be suppressed (one possible reason is to improve compilation performance at the expense of evaluation performance).- Parameters:
compileToBytecode
- true to switch the option on
-
isGenerateByteCode
public boolean isGenerateByteCode(int hostLanguage) Ask whether bytecode should be generated. The default setting is true in Saxon Enterprise Edition and false in all other cases. Setting the option to true has no effect if Saxon-EE is not available (but if it is set to true, this method will return true). Setting the option to false in Saxon-EE is permitted if for some reason bytecode generation is to be suppressed (one possible reason is to improve compilation performance at the expense of evaluation performance).- Parameters:
hostLanguage
- one of XSLT or XQUERY- Returns:
- true if the option is switched on
-
finalize
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. This implementation closes the error output file if one has been allocated.
-