net.sf.saxon
public class Configuration extends Object implements Serializable, SourceResolver
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
Nested Class Summary | |
---|---|
static class | Configuration.LicenseFeature |
Field Summary | |
---|---|
static Class<Configuration> | configurationClass |
static int | DO_NOT_RECOVER
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 int | JAVA_APPLICATION
Constant indicating that the host language is Java: that is, this is a free-standing
Java application with no XSLT or XQuery content |
protected int | optimizationLevel |
protected Optimizer | optimizer |
static int | RECOVER_SILENTLY
Constant indicating that the processor should take the recovery action
when a recoverable error occurs, with no warning message. |
static int | RECOVER_WITH_WARNINGS
Constant indicating that the processor should produce a warning
when a recoverable error occurs, and should then take the recovery
action and continue. |
protected StyleNodeFactory | styleNodeFactory |
protected VendorFunctionLibrary | vendorFunctionLibrary |
protected int | xsdVersion |
static int | XML10
Constant indicating the XML Version 1.0 |
static int | XML11
Constant indicating the XML Version 1.1 |
static int | XML_SCHEMA
Constant indicating that the "host language" is XML Schema |
static int | XPATH
Constant indicating that the host language is XPATH itself - that is, a free-standing XPath environment |
static int | XQUERY
Constant indicating that the host language is XQuery |
static int | XSD10
Language versions for XML Schema |
static int | XSD11 |
static int | XSLT
Constant indicating that the host language is XSLT |
Constructor Summary | |
---|---|
Configuration()
Create a non-schema-aware configuration object with default settings for all options.
|
Method Summary | |
---|---|
void | addExtensionBinders(FunctionLibraryList list)
Add the registered extension binders to a function library.
|
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.
|
DocumentInfo | buildDocument(Source source)
Build a document tree, using options set on this Configuration and on the supplied source
object. |
DocumentInfo | buildDocument(Source source, ParseOptions parseOptions)
Build a document, using specified options for parsing and building. |
void | 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.
|
Configuration | copy()
Copy an existing Configuration to create a new Configuration.
|
protected void | copyTo(Configuration c) |
void | displayLicenseMessage()
Display a message about the license status |
void | exportComponents(Receiver out)
Export a precompiled Schema Component Model containing all the components (except built-in components)
that have been loaded into this Processor.
|
Receiver | getAnnotationStripper(Receiver destination)
Add to a pipeline a receiver that strips all type annotations. |
SchemaDeclaration | getAttributeDeclaration(int fingerprint)
Get a global attribute declaration.
|
CharacterSetFactory | getCharacterSetFactory()
Get the CharacterSetFactory. |
Class | getClass(String className, boolean tracing, ClassLoader classLoader)
Load a class using the class name provided.
|
CollationMap | getCollationMap()
Get the collation map, which can be used to register named collations (and a default collation)
at the Configuration level. |
CollationURIResolver | getCollationURIResolver()
Get the collation URI resolver associated with this configuration. |
CollectionURIResolver | getCollectionURIResolver()
Get the collection URI resolver associated with this configuration. |
static Configuration | getConfiguration(XPathContext context)
Get the configuration, given the context. |
Object | getConfigurationProperty(String name)
Get a property of the configuration
|
XPathContext | getConversionContext()
Get an XPathContext object with sufficient capability to perform comparisons and conversions
|
Debugger | getDebugger()
Get the debugger in use. |
String | getDefaultCollection()
Get the URI of the default collection. |
String | getDefaultCountry()
Get the default country to be used for number and date formatting when no country is specified.
|
String | getDefaultLanguage()
Get the default language. |
Properties | getDefaultSerializationProperties()
Get the default serialization properties |
StaticQueryContext | getDefaultStaticQueryContext()
Get the default options for XQuery compilation |
CompilerInfo | getDefaultXsltCompilerInfo()
Get the default options for XSLT compilation |
DocumentNumberAllocator | getDocumentNumberAllocator()
Get the document number allocator.
|
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.
|
int | getDOMLevel()
Get the level of DOM interface to be used
|
DynamicLoader | getDynamicLoader()
Get the DynamicLoader used by this Configuration. |
String | getEditionCode()
Get the edition code identifying this configuration: "HE", "PE" or "EE" |
SchemaDeclaration | getElementDeclaration(int fingerprint)
Get a global element declaration.
|
SequenceReceiver | getElementValidator(SequenceReceiver receiver, int nameCode, 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. |
ErrorListener | getErrorListener()
Get the ErrorListener used in this configuration. |
Iterator | getExtensionsOfType(SchemaType type)
Get the set of complex types that have been defined as extensions of a given type.
|
ExternalObjectModel | getExternalObjectModel(String uri)
Get the external object model with a given URI, if registered |
ExternalObjectModel | getExternalObjectModel(Class nodeClass)
Get the external object model that recognizes a particular class of node, if available |
List<ExternalObjectModel> | getExternalObjectModels()
Get 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 null |
DocumentPool | getGlobalDocumentPool()
Get the global document pool. |
int | getHostLanguage()
Get the host language used in this configuration. |
Set | getImportedNamespaces()
Get the set of namespaces of imported schemas
|
Object | getInstance(String className, ClassLoader classLoader)
Instantiate a class using the class name provided.
|
IntegratedFunctionLibrary | getIntegratedFunctionLibrary()
Get the IntegratedFunction library containing integrated extension functions |
static Locale | getLocale(String lang)
Get a locale given a language code in XML format.
|
LocalizerFactory | getLocalizerFactory()
Get the localizer factory in use |
String | 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.
|
ModuleURIResolver | 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.
|
NameChecker | getNameChecker()
Get a class that can be used to check names against the selected XML version
|
NamePool | getNamePool()
Get the target namepool to be used for stylesheets/queries and for source documents.
|
Optimizer | getOptimizer()
Factory method to get an Optimizer.
|
OutputURIResolver | getOutputURIResolver()
Get the OutputURIResolver that will be used to resolve URIs used in the
href attribute of the xsl:result-document instruction.
|
ParseOptions | getParseOptions()
Get the parsing and document building options defined in this configuration |
static Platform | getPlatform()
Get the Platform to be used for platform-dependent methods
|
Object | getProcessor()
Get the Processor object that created this Configuration in the relevant API.
|
String | getProductTitle()
Get a message used to identify this product when a transformation is run using the -t option
|
int | getRecoveryPolicy()
Determine how recoverable run-time errors are to be handled. |
SchemaType | getSchemaType(int fingerprint)
Get the top-level schema type definition with a given fingerprint.
|
SchemaURIResolver | getSchemaURIResolver()
Get the user-defined SchemaURIResolver for resolving URIs used in "import schema"
declarations; if none has been explicitly set, returns null.
|
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
|
SerializerFactory | getSerializerFactory()
Get the SerializerFactory. |
XMLReader | getSourceParser()
Get a parser for source documents. |
String | 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).
|
SourceResolver | getSourceResolver()
Get the current SourceResolver. |
ModuleURIResolver | getStandardModuleURIResolver()
Get the standard system-defined ModuleURIResolver for resolving URIs used in "import module"
declarations in the XQuery prolog.
|
int | getStripsWhiteSpace()
Set which kinds of whitespace-only text node should be stripped.
|
StyleNodeFactory | getStyleNodeFactory()
Factory method to get the StyleNodeFactory, used for constructing elements
in a stylesheet document |
XMLReader | getStyleParser()
Get the parser for stylesheet documents. |
String | getStyleParserClass()
Get the name of the class that will be instantiated to create an XML parser
for parsing stylesheet modules.
|
StandardURIResolver | getSystemURIResolver()
Get the system-defined URI Resolver. |
TraceListener | getTraceListener()
Get the TraceListener used for run-time tracing of instruction execution.
|
String | getTraceListenerClass()
Get the name of the trace listener class to be used for run-time tracing of instruction
execution. |
int | getTreeModel()
Get the Tree Model used by this Configuration. |
TypeHierarchy | getTypeHierarchy()
Get the TypeHierarchy: a cache holding type information
|
URIResolver | getURIResolver()
Get the URIResolver used in this configuration
|
VendorFunctionLibrary | getVendorFunctionLibrary()
Get the FunctionLibrary used to bind calls on Saxon-defined extension functions.
|
int | getXMLVersion()
Get the XML version to be used by default for validating characters and names
|
int | getXsdVersion()
Get the version of XML Schema to be used |
void | 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 | isAllowExternalFunctions()
Determine whether calls to external Java functions are permitted.
|
boolean | isCompatible(Configuration other)
Determine whether two Configurations are compatible. |
boolean | isCompileWithTracing()
Determine whether compile-time generation of trace code was requested
|
boolean | isExpandAttributeDefaults()
Determine whether elements and attributes that have a fixed or default value are to be expanded.
|
boolean | isLazyConstructionMode()
Determine whether lazy construction mode is on or off. |
boolean | isLicensed()
Determine if the functionality available in this configuration is licensed. |
boolean | isLicensedFeature(int feature)
Determine if a particular feature is licensed. |
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.
|
boolean | isMultiThreading()
Determine whether multithreading optimizations are allowed
|
boolean | isOptimizerTracing()
Test whether optimizer tracing is on or off
|
boolean | isRetainDTDAttributeTypes()
Ask whether attribute types obtained from a DTD are to be used to set type annotations
on the resulting nodes |
boolean | isSchemaAvailable(String targetNamespace)
Determine whether the Configuration contains a cached schema for a given target namespace
|
boolean | isSchemaAware(int language)
Determine if the configuration is schema-aware, for the given host language
|
boolean | isStripsAllWhiteSpace()
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 | isTraceExternalFunctions()
Determine whether calls on external functions are to be traced for diagnostic
purposes.
|
boolean | isValidation()
Determine whether the XML parser for source documents will be asked to perform
validation of source documents
|
boolean | isValidationWarnings()
Determine whether schema validation failures on result documents are to be treated
as fatal errors or as warnings.
|
boolean | isVersionWarning()
Determine whether a warning is to be output when running against a stylesheet labelled
as version="1.0". |
boolean | isXIncludeAware()
Test whether or not source documents (including stylesheets and schemas) are to have
XInclude processing applied to them, or not
|
void | loadSchema(String absoluteURI)
Simple interface to load a schema document
|
StringCollator | makeCollator(String className)
Load a named collator class and check it is OK.
|
static Configuration | makeConfiguration(ClassLoader classLoader, String className)
Factory method to create a Configuration. |
ProxyReceiver | makeDocumentProjector(PathMap.PathMapRoot map)
Create a document projector for a given path map. |
Receiver | makeEmitter(String clarkName, Controller controller)
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.
|
Numberer | makeNumberer(String language, String country)
Load a Numberer class for a given language and check it is OK.
|
XMLReader | makeParser(String className)
Create a new SAX XMLReader object using the class name provided. |
PipelineConfiguration | makePipelineConfiguration()
Make a PipelineConfiguration from the properties of this Configuration
|
static Configuration | makeSchemaAwareConfiguration(ClassLoader loader, String className)
Make an enterprise configuration |
SlotManager | makeSlotManager()
Factory method to create a SlotManager.
|
Receiver | makeStreamingTransformer(XPathContext context, Mode mode)
Create a streaming transformer |
TraceListener | makeTraceListener()
Get or create the TraceListener used for run-time tracing of instruction execution.
|
TraceListener | makeTraceListener(String className)
Create an instance of a TraceListener with a specified class name
|
NodeInfo | makeUnconstructedDocument(DocumentInstr instr, XPathContext context)
Make an "unconstructed" (that is, lazily-constructed) document node |
NodeInfo | makeUnconstructedElement(ElementCreator instr, XPathContext context)
Make an "unconstructed" (that is, lazily-constructed) element node |
URIResolver | makeURIResolver(String className)
Create an instance of a URIResolver with a specified class name.
|
static Configuration | 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. |
PendingUpdateList | newPendingUpdateList()
Get a new Pending Update List
|
StaticQueryContext | newStaticQueryContext()
Get a new StaticQueryContext (which is also the factory class for creating a query parser) |
UserFunction | newUserFunction(boolean memoFunction)
Make a UserFunction object.
|
static Configuration | readConfiguration(Source source)
Factory method to construct a Configuration object by reading a configuration file.
|
String | 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.
|
String | readSchema(PipelineConfiguration pipe, String baseURI, String schemaLocation, String expected)
Read a schema from a given schema location
This method is intended for internal use.
|
void | registerExtensionFunction(ExtensionFunctionDefinition function)
Register an extension function that is to be made available in all queries, stylesheets, and
XPath expressions compiled under thie Configuration. |
void | registerExternalObjectModel(ExternalObjectModel model)
Register an external object model with this Configuration.
|
void | reportFatalError(XPathException err)
Report a fatal error
|
Source | resolveSource(Source source, Configuration config)
Resolve a Source. |
void | reuseSourceParser(XMLReader parser)
Return a source parser to the pool, for reuse
|
void | reuseStyleParser(XMLReader parser)
Return a stylesheet (or schema) parser to the pool, for reuse
|
void | 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 | setCollectionURIResolver(CollectionURIResolver resolver)
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 | setDebugger(Debugger debugger)
Set the debugger to be used.
|
void | setDefaultCollection(String uri)
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 | setDefaultSerializationProperties(Properties props)
Set the default serialization properties |
void | setDocumentNumberAllocator(DocumentNumberAllocator allocator)
Set the document number allocator.
|
void | setDOMLevel(int level)
Set the level of DOM interface to be used
|
void | 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 | 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 used |
void | 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(ModuleURIResolver resolver)
Set a user-defined ModuleURIResolver for resolving URIs used in "import module"
declarations in an XQuery prolog.
|
void | setModuleURIResolver(String className)
Create and register an instance of a ModuleURIResolver with a specified class name.
|
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 off
|
void | 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 | 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 |
void | 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)
Say whether attribute types obtained from a DTD are to be used to set type annotations
on the resulting nodes.
|
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 | 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 documents
|
void | 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 running against a stylesheet labelled
as version="1.0". |
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.
|
NodeInfo | unravel(Source source)
Get a NodeInfo corresponding to a DOM or other external Node,
either by wrapping or unwrapping the external Node.
|
boolean | useTypedValueCache()
Ask whether the typed value cache should be used for the TinyTree |
int | validateAttribute(int nameCode, CharSequence value, int validation)
Validate an attribute value.
|
Since: 8.4
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 invalid UnsupportedOperationException if the configuration is not schema-aware
Since: 8.4
Parameters: schemaSource the JAXP Source object identifying the schema document to be loaded errorListener 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
Parameters: source the Source to be used. This may be an AugmentedSource, 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.
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
Parameters: derived the derived type base the base type; the algorithm tests whether derivation from this type is permitted block the derivations that are blocked by the relevant element declaration
Throws: SchemaException if the derivation is not allowed
This method may replace a ProfessionalConfiguration by an EnterpriseConfiguration according to what is found in the installed license.
Note that creating a new EnterpriseConfiguration using this method can be significantly cheaper than creating one from scratch, because it avoids the need to verify the Saxon-EE license key if this has already been done.
Returns: a shallow copy of this Configuration
Parameters: out the destination to recieve the precompiled Schema Component Model in the form of an XML document
Parameters: destination the Receiver that events will be written to after whitespace stripping
Returns: the Receiver to which events should be sent for stripping
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.
Returns: the CharacterSetFactory in use.
Since: 9.2
DynamicLoader
, which may be overridden by a user-defined DynamicLoader
.
Parameters: className A string containing the name of the class, for example "com.microstar.sax.LarkDriver" tracing true if diagnostic tracing is required 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.
Returns: the registered CollationURIResolver
Since: 8.5
Returns: the registered CollationURIResolver
Since: 8.5
Parameters: context the XPath dynamic context
Returns: the Saxon Configuration for a given XPath dynamic context
Parameters: name the name of the required property. See the class FeatureKeys for constants representing the property names that can be requested.
Returns: the value of the property
Throws: IllegalArgumentException thrown if the property is not one that Saxon recognizes.
Returns: a dynamic context for performing conversions
Returns: the debugger in use, or null if none is in use
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
Returns: the default country to be used, as an ISO code for example "US" or "GB"
Since: 9.2
Returns: the default language
Since: 9.2
Returns: the default properties
Returns: the default options for XSLT compilation. The CompilerInfo object will reflect any options set using other methods available for this Configuration object
Returns: the current DocumentNumberAllocator
Since: 9.0
Parameters: receiver The receiver to which events should be sent after validation systemId the base URI of the document being validated validationMode 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 stripping schemaType 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
Returns: the DOM level. Always 2 or 3.
Returns: the DynamicLoader in use - either a user-supplied DynamicLoader, or the standard one supplied by the system.
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.
Parameters: receiver the target receiver tp receive the validated element nameCode the nameCode of the element to be validated. This must correspond to the name of an element declaration in a loaded schema locationId current location in the stylesheet or query schemaType the schema type (typically a complex type) against which the element is to be validated validation The validation mode, for example Validation.STRICT or Validation.LAX
Returns: The target receiver, indicating that with this configuration, no validation is performed.
Returns: the ErrorListener.
Since: 8.4
Parameters: type the type whose extensions are required
Parameters: uri the identifying URI of the required external object model
Returns: the requested external object model if available, or null otherwise
Parameters: nodeClass the class of the Node object in the external object model
Returns: the requested external object model if available, or null otherwise
Returns: a list of external object models supported. The members of the list are of type ExternalObjectModel
Parameters: fingerprint the name of the type
Returns: the external object type it the name is in the JAVA_TYPE namespace, otherwise null.
Returns: the global document pool
Since: 9.1
Returns: Configuration.XSLT or Configuration.XQUERY
Returns: a Set whose members are the namespaces of all schemas in the schema cache, as String objects
DynamicLoader
, which may be overridden by a user-defined DynamicLoader
.
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.
Returns: the IntegratedFunctionLibrary
Since: 9.2
Parameters: lang the language code
Returns: the Java locale
Returns: the LocalizerFactory, if any. If none has been set, returns null.
Since: 9.2
Returns: the full class name of the message emitter class.
Since: 8.4
Returns: the resolver for Module URIs
Returns: a class that can be used for name checking
Since: 8.6
Returns: the target name pool. If no NamePool has been specified explicitly, the default NamePool is returned.
Since: 8.4
Returns: the optimizer used in this configuration
Returns: the OutputURIResolver. If none has been supplied explicitly, the default OutputURIResolver is returned.
Since: 8.4
Returns: the parsing and document building options. Note that any changes to this 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
Returns: the platform to be used
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 method, or null
if this method has not been called. In practice this property is used to hold one of the
following:
net.sf.saxon.s9api.Processor
Saxon.Api.Processor
TransformerFactory
XPathFactory
SchemaFactory
XQDataSource
Since: 9.2
Returns: A string containing both the product name and the product version
Since: 8.4
Returns: the current recovery policy. The options are RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER.
Since: 8.4
Parameters: fingerprint the fingerprint of the schema type
Returns: the schema type , or null if there is none with this name.
Returns: the user-defined SchemaURIResolver for resolving URIs
Returns: the schema validation mode previously set using setSchemaValidationMode(), or the default mode STRIP otherwise.
Returns: the SerializerFactory in use
Since: 8.8
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 Configuration setting.
Returns: the fully qualified name of the XML parser class
Returns: the current SourceResolver
Returns: the standard system-defined ModuleURIResolver for resolving URIs
Returns: kind the kind of whitespace-only text node that should be stripped when building a source tree. One of NONE (none), ALL (all), or IGNORABLE (element-content whitespace as defined in a DTD or schema)
Returns: the StyleNodeFactory used in this Configuration
Returns: an XML parser (a SAX2 parser) that can be used for stylesheets and schema documents
Returns: the fully qualified name of the XML parser class
Returns: the system-defined URI resolver
Returns: the TraceListener that was set using getTraceListener if set. Otherwise, returns null.
Since: 8.4. Modified in 9.1.
Returns: the name of the trace listener class, or null if no trace listener class has been nominated.
Since: 9.1
Builder.TINY_TREE
.
Returns: the selected Tree Model
Since: 8.4 (Condensed tinytree added in 9.2)
Returns: the type hierarchy cache
Returns: the URIResolver. If no URIResolver has been set explicitly, the default URIResolver is used.
Since: 8.4
Returns: the FunctionLibrary used for extension functions in the Saxon library.
Returns: one of the constants XML10 or XML11
Since: 8.6
Parameters: source the XML file containing the schema component model, as generated by a previous call on Configuration
Returns: true if such calls are permitted.
Since: 8.4
Parameters: other the other Configuration to be compared with this one
Returns: true if the two configurations are compatible
Returns: true if compile-time generation of code was requested
Since: 8.8
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
Returns: true if lazy construction mode is enabled
Returns: true for Saxon-HE, since all Saxon-HE functionality is always available
Since: 9.2
Parameters: feature the feature in question, identified by a constant in class LicenseFeature
Returns: true if line numbers are maintained in source documents
Since: 8.4
Returns: true if multithreading optimizations are allowed
Returns: true if optimizer tracing is switched on
Returns: true if DTD types are to be taken into account
Since: 8.4
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.
Deprecated: since 9.2: use isLicensedFeature() instead
Determine if the configuration is schema-aware, for the given host languageParameters: language the required host language: XSLT, XQUERY, or XML_SCHEMA
Returns: true if the configuration is schema-aware
Since: 8.4
Returns: true if all whitespace-only text nodes are stripped.
Since: 8.4
Returns: true if these messages are to be output.
Returns: true if tracing is enabled for calls to external Java functions
Returns: true if DTD validation is requested.
Since: 8.4
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
Returns: true if these messages are to be output.
Since: 8.4
Returns: true if XInclude elements are to be expanded, false if not
Since: 8.9
Parameters: absoluteURI the absolute URI of the location of the schema document
Parameters: className the name of the collator class
Returns: a StringCollator to implement a collation
Deprecated: since 9.2: use newConfiguration() instead
Factory method to create a Configuration. The resulting configuration will be an enterprise Configuration if Saxon-EE is installed and if a license is available; otherwise it will be a basic configuration. Note that the license might not permit all processing options.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 schema aware configuration class. Defaults to "com.saxonica.EnterpriseConfiguration" 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, but there is nothing that requires it to be schema-aware.
Returns: an EnterpriseConfiguration object if Saxon-EE can be loaded and a valid license is installed; otherwise, a non-schema-aware configuration object
Since: 9.0
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
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}local controller the Controller. Allows a local class loader to be used.
Returns: a Receiver (despite the name, it is not required to be an Emitter)
On the .NET platform, this method should not be called unless it is known that the assembly saxon9sa.dll has already been loaded. This can be achieved by an appropriate call on Assembly.Load(): for an example, see the C# Configuration.cs class in the Saxon.Api namespace.
This method fails if Saxon-EE cannot be loaded, but it does not fail if there is no license available. In that case it returns a schema-aware configuration object, but any attempt to use schema-aware processing will fail.
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 EnterpriseConfiguration
Throws: RuntimeException if the Saxon-EE product cannot be loaded
Since: 9.2 (renamed from makeSchemaAwareConfiguration)
Parameters: language the language for which a Numberer is required. May be null, indicating default language country 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.
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.
Returns: a new PipelineConfiguration
Since: 8.4
Deprecated: since 9.2. Use Configuration instead.
Make an enterprise configurationParameters: loader the class loader (or null) className the name of the configuration class (or null)
Returns: a SlotManager (which is a skeletal stack frame representing the mapping of variable names to slots on the stack frame)
Parameters: context the initial XPath context mode the initial mode, which must be a streaming mode
Returns: a Receiver to which the streamed input document will be pushed
Returns: If a TraceListener has been set using setTraceListener, returns that TraceListener. Otherwise, if a TraceListener class has been set using setTraceListenerClass, 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.
Parameters: className The fully qualified class name of the TraceListener to be constructed
Returns: the newly constructed TraceListener
Throws: net.sf.saxon.trans.XPathException if the requested class does not implement the net.sf.saxon.trace.TraceListener interface
Parameters: instr the instruction that creates the document node context the dynamic evaluation context
Returns: the lazily constructed document node
Parameters: instr the instruction that creates the element context the dynamic evaluation context
Returns: the lazily constructed element node
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
Returns: a Configuration object of the class appropriate to the Saxon edition in use.
Since: 9.2
Returns: the new Pending Update List
Throws: UnsupportedOperationException if called when using Saxon-B
Returns: a new StaticQueryContext
Parameters: memoFunction true if the function is to be a memo function, This option is ignored in Saxon-HE.
Parameters: source Source object containing the configuration file
Returns: the resulting Configuration
Parameters: root the xs:schema element in the stylesheet expected 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
Parameters: pipe the pipeline configuration baseURI the base URI against which the schema locations are to be resolved schemaLocations the relative URIs specified as schema locations expected the namespace URI which is expected as the target namespace of the loaded schema
Parameters: pipe the PipelineConfiguration baseURI the base URI of the instruction requesting the reading of the schema schemaLocation the location of the schema to be read expected The expected targetNamespace of the schema being read.
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 product
Parameters: function the class that implements the extension function. This must be a class that extends ExtensionFunctionCall, and it must have a public zero-argument constructor
Throws: XPathException if the class cannot be instantiated or does not extend ExtensionFunctionCall
Since: 9.2
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.
Parameters: err the exception to be reported
Parameters: source A source object, typically the source supplied as the first argument to javax.xml.transform.Transformer#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, or PullSource. Return null if the Source object is not recognized
Throws: XPathException if the Source object is recognized but cannot be processed
Parameters: parser The parser: the caller must not supply a parser that was obtained by any mechanism other than calling the getSourceParser() method.
Parameters: parser The parser: the caller must not supply a parser that was obtained by any mechanism other than calling the getStyleParser() method.
Parameters: namespace the namespace URI of the components to be sealed
Setting the value to false disallows all of the following:
xsl:result-document
instructionNote 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-supplied URIResolver
Parameters: allowExternalFunctions true if external function calls are to be permitted.
Since: 8.4
Parameters: resolver the collation URI resolver to be used. This replaces any collation URI resolver previously registered.
Since: 8.5
Parameters: resolver the collection URI resolver to be used. This replaces any collection URI resolver previously registered.
Since: 8.5
Parameters: trace true if compile-time generation of trace code is required
Since: 8.8
Parameters: name the URI identifying the property to be set. See the class FeatureKeys for constants representing the property names that can be set. value the value of the property
Throws: IllegalArgumentException if the property name is not recognized or if the value is not a valid value for the named property
Parameters: debugger the debugger to be used.
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
Since: 9.2
Parameters: country the default country to be used, as an ISO code for example "US" or "GB"
Since: 9.2
Parameters: language the default language to be used, as an ISO code for example "en" or "fr-CA"
Since: 9.2
Parameters: props the default properties
This 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
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.
Parameters: dynamicLoader the DynamicLoader to be used by this Configuration
Parameters: listener the ErrorListener to be used
Since: 8.4
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
Parameters: hostLanguage Configuration.XSLT or Configuration.XQUERY
Parameters: lazy true to switch lazy construction mode on, false to switch it off.
Parameters: lineNumbering true if line numbers are maintained in source documents
Since: 8.4
Parameters: factory the LocalizerFactory
Since: 9.2
Parameters: messageReceiverClassName the full class name of the message receiver. This must implement net.sf.saxon.event.Receiver.
Since: 8.4
Parameters: resolver the URI resolver for XQuery modules
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
Parameters: multithreading true if multithreading optimizations area allowed
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
Parameters: trace set to true to switch optimizer tracing on, false to switch it off
Parameters: outputURIResolver the OutputURIResolver to be used.
Since: 8.4
Parameters: processor This can be any object, but it is actually used to hold one of the
following:
net.sf.saxon.s9api.Processor
Saxon.Api.Processor
TransformerFactory
XPathFactory
SchemaFactory
XQDataSource
Since: 9.2
Parameters: recoveryPolicy the recovery policy to be used. The options are RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER.
Since: 8.4
Deprecated: since 9.2 This feature was dropped from the final XDM specification and will be dropped in a future Saxon release. 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
Since: 8.4
Parameters: resolver the URI resolver used for import schema declarations
Parameters: validationMode the validation (or construction) mode to be used for source documents. One of STRIP, PRESERVE, STRICT, LAX
Since: 8.4
Parameters: factory a custom SerializerFactory
Since: 8.8
Parameters: sourceParserClass the fully qualified name of the XML parser class. This must implement the SAX2 XMLReader interface.
Parameters: resolver the source resolver.
Parameters: stripsAllWhiteSpace if all whitespace-only text nodes are to be stripped.
Since: 8.4
Parameters: kind the kind of whitespace-only text node that should be stripped when building a source tree. One of NONE (none), ALL (all), or IGNORABLE (element-content whitespace as defined in a DTD or schema)
Parameters: parser the fully qualified name of the XML parser class
Parameters: timing true if these messages are to be output.
Parameters: traceExternalFunctions true if tracing is to be enabled for calls to external Java functions
Note: this method should not be used if the Configuration is multithreading. In that situation, use Configuration to force stylesheets and queries to be compiled with trace code enabled, and use addTraceListener to supply a TraceListener at run time.
Parameters: traceListener The TraceListener to be used.
Since: 8.4
Parameters: className the name of the trace listener class
Throws: IllegalArgumentException if the class cannot be instantiated or does not implement TraceListener
Since: 9.1
Builder.TINY_TREE
.
Parameters: treeModel the integer constant representing the selected Tree Model
Since: 8.4 (Condensed tinytree added in 9.2)
Parameters: resolver The URIResolver to be used.
Since: 8.4
Parameters: validation true if DTD validation is to be requested.
Since: 8.4
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
Parameters: warn true if these messages are to be output.
Since: 8.4
Parameters: state true if XInclude elements are to be expanded, false if not
Since: 8.9
Parameters: version one of the constants XML10 or XML11
Since: 8.6
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 does
to resolve the Source
.
Returns: true (the default) if the cache should be used, false otherwise
Parameters: nameCode the name of the attribute value the value of the attribute as a string validation STRICT or LAX
Returns: the type annotation to apply to the attribute node
Throws: ValidationException if the value is invalid