com.saxonica.validate
Class SchemaAwareConfiguration

java.lang.Object
  net.sf.saxon.Configuration
      com.saxonica.validate.SchemaAwareConfiguration

All Implemented Interfaces:

Serializable, SourceResolver

public final class SchemaAwareConfiguration
extends Configuration

A subclass of Configuration that defines a schema-aware processor. This contains helper methods invoked both at compile time and at run-time to perform operations that are allowed only in a schema-aware processor; the superclass Configuration contains the dummy versions of these methods used in a non-schema-aware processor. The interface is designed so that the calling classes contain no references to classes that are available only in the schema-aware product.

Applications should avoid using this class directly, and should instead access all the necessary functionality through its superclass, Configuration.

See Also:

Serialized Form

Nested Class Summary

static class

SchemaAwareConfiguration.SurrogateSchema A SurrogateSchema is a dummy schema object that is stored in the schema cache while the schema for a given namespace is being processed.

Field Summary

Fields inherited from class net.sf.saxon.Configuration

DO_NOT_RECOVER, JAVA_APPLICATION, RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, XML_SCHEMA, XML10, XML11, XPATH, XQUERY, XSLT

Constructor Summary

SchemaAwareConfiguration()
Create a SchemaAwareConfiguration

Method Summary

void	addSchema(PreparedSchema pschema) Add a schema to the cache
void	addSchemaSource(Source schemaSource, ErrorListener errorListener) Load a schema, which will be available for use by all subsequent operations using this SchemaAwareConfiguration.
void	addSurrogateSchema(String namespace) Put a temporary schema marker in the cache, to indicate that a schema for a given namespace is being processed.
DocumentInfo	buildDocument(Source source) Build a document tree, using options set on this Configuration and on the supplied source object.
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.
void	displayLicenseMessage() Display a message about the license status.
Receiver	getAnnotationStripper(Receiver destination) Add to a pipeline a receiver that strips all type annotations.
SchemaDeclaration	getAttributeDeclaration(int fingerprint) Get a global attribute declaration
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
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 to which errors are reported
Set	getImportedNamespaces() Get the set of namespaces of imported schemas
int[]	getOccurrenceLimits() Get the occurrence limits previously set using setOccurrenceLimits (or the default)
Optimizer	getOptimizer() Factory method to get an Optimizer
String	getProductTitle() Get a message used to identify this product when a transformation is run using the -t option
PreparedSchema	getSchema(String namespace) Get a schema from the cache.
SchemaType	getSchemaType(int fingerprint) Get the top-level schema type 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 the standard schema URI resolver.
PreparedSchema	getSuperSchema() Get the SuperSchema, containing references to all names defined in all known schemas
VendorFunctionLibrary	getVendorFunctionLibrary() Get the FunctionLibrary used to bind calls on Saxon-defined extension functions
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
boolean	isSealedNamespace(String namespace) Test whether a schema namespace is sealed.
ProxyReceiver	makeDocumentProjector(PathMap.PathMapRoot map) Create a document projector for a given path map.
Receiver	makeEmitter(String clarkName, Controller controller) Get a configuration-defined output method.
SchemaCompiler	newSchemaCompiler() Make a SchemaCompiler which can be used to compile schema documents.
String	readInlineSchema(NodeInfo root, String expected, ErrorListener errorListener) Read an inline schema from a stylesheet
void	readMultipleSchemas(PipelineConfiguration pipe, String baseURI, List 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
void	removeSchema(String namespace) Remove the schema for a given namespace.
Source	resolveSource(Source source, Configuration config) Implement the SourceResolver interface
void	sealNamespace(String namespace) Mark a schema namespace as being sealed.
void	setOccurrenceLimits(int minimum, int maximum) Set the occurrence limits to be used when compiling a finite state automaton.
void	setParameterizedURIResolver() Set the URIResolver to a URI resolver that allows query parameters after the URI, and in the case of Saxon-SA, that inteprets the file extension .ptree
void	supplyLicenseKey(BufferedReader reader) This method allows the contents of a license key to be supplied programmatically.
int	validateAttribute(int nameCode, CharSequence value, int validation) Validate an attribute value (XSLT only)

Methods inherited from class net.sf.saxon.Configuration

addSchemaSource, areAllNodesUntyped, findExternalObjectModel, getClass, getClassLoader, getCollationURIResolver, getCollectionURIResolver, getConfiguration, getConfigurationProperty, getConversionContext, getDebugger, getDocumentNumberAllocator, getDOMLevel, getExtensionBinder, getExtensionFunctionFactory, getExternalObjectModels, getGlobalDocumentPool, getHostLanguage, getInstance, getLocale, getMessageEmitterClass, getModuleURIResolver, getNameChecker, getNamePool, getOutputURIResolver, getPlatform, getRecoveryPolicy, getSchemaValidationMode, getSerializerFactory, getSourceParser, getSourceParserClass, getSourceResolver, getStandardModuleURIResolver, getStripsWhiteSpace, getStyleParser, getStyleParserClass, getSystemURIResolver, getTraceListener, getTreeModel, getTypeHierarchy, getURIResolver, getXMLVersion, isAllowExternalFunctions, isCompatible, isCompileWithTracing, isExpandAttributeDefaults, isLazyConstructionMode, isLineNumbering, isMultiThreading, isOptimizerTracing, isRetainDTDAttributeTypes, isStripsAllWhiteSpace, isTiming, isTraceExternalFunctions, isValidation, isValidationWarnings, isVersionWarning, isXIncludeAware, loadSchema, makeCollator, makeConfiguration, makeParser, makePipelineConfiguration, makeSchemaAwareConfiguration, makeSlotManager, makeTraceListener, makeURIResolver, registerExternalObjectModel, reportFatalError, reuseSourceParser, reuseStyleParser, setAllNodesUntyped, setAllowExternalFunctions, setClassLoader, setCollationURIResolver, setCollectionURIResolver, setCompileWithTracing, setConfigurationProperty, setDebugger, setDocumentNumberAllocator, setDOMLevel, setErrorListener, setExpandAttributeDefaults, setExtensionBinder, setExtensionFunctionFactory, setHostLanguage, setLazyConstructionMode, setLineNumbering, setMessageEmitterClass, setModuleURIResolver, setModuleURIResolver, setMultiThreading, setNamePool, setOptimizerTracing, setOutputURIResolver, setRecoveryPolicy, setRetainDTDAttributeTypes, setSchemaURIResolver, setSchemaValidationMode, setSerializerFactory, setSourceParserClass, setSourceResolver, setStripsAllWhiteSpace, setStripsWhiteSpace, setStyleParserClass, setTiming, setTraceExternalFunctions, setTraceListener, setTreeModel, setURIResolver, setValidation, setValidationWarnings, setVersionWarning, setXIncludeAware, setXMLVersion, unravel

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SchemaAwareConfiguration

public SchemaAwareConfiguration()

Create a SchemaAwareConfiguration

Method Detail

copy

public Configuration copy()

Copy an existing Configuration to create a new Configuration. This is a shallow copy. The new Configuration will share all the option settings of the old; it will also share the same NamePool, and the same DocumentNumberAllocator. If this configuration is schema-aware then the new one will also be schema-aware, and will share the same Schema manager and so on. (So any schema component loaded into one configuration will affect both).

Note that creating a new SchemaAwareConfiguration using this method can be significantly cheaper than creating one from scratch, because it avoids the need to verify the Saxon-SA license key if this has already been done.

Overrides:

copy in class Configuration

Returns:

a shallow copy of this Configuration

supplyLicenseKey

public void supplyLicenseKey(BufferedReader reader)

This method allows the contents of a license key to be supplied programmatically. This must be a license file as issued to authorized OEM distributors of Saxon-SA.

Parameters:

reader - A reader that will be used to read the contents of the license file (for example, a StringReader)

Throws:

IllegalArgumentException - if the key supplied is not a valid OEM license key

getProductTitle

public String getProductTitle()

Get a message used to identify this product when a transformation is run using the -t option

Overrides:

getProductTitle in class Configuration

Returns:

A string containing both the product name and the product version

isSchemaAware

public final boolean isSchemaAware(int language)

Determine if the configuration is schema-aware

Overrides:

isSchemaAware in class Configuration

Parameters:

language - the processing language for which schema-aware processing is required

Returns:

true if the configuration is schema-aware

displayLicenseMessage

public void displayLicenseMessage()

Display a message about the license status. Used from command-line tools only.

Overrides:

displayLicenseMessage in class Configuration

setParameterizedURIResolver

public void setParameterizedURIResolver()

Set the URIResolver to a URI resolver that allows query parameters after the URI, and in the case of Saxon-SA, that inteprets the file extension .ptree

Overrides:

setParameterizedURIResolver in class Configuration

getErrorListener

public ErrorListener getErrorListener()

Get the ErrorListener to which errors are reported

Overrides:

getErrorListener in class Configuration

Returns:

either the user-supplied error listener, or a system-provided error listener

newSchemaCompiler

public SchemaCompiler newSchemaCompiler()

Make a SchemaCompiler which can be used to compile schema documents. The initial settings of the SchemaCompiler are a snapshot of the settings in the SchemaAwareConfiguration. Other methods in SchemaAwareConfiguration provided for the purpose of compiling schemas are retained for compatibility reasons.

Returns:

a new SchemaCompiler object

Since:

8.9

setOccurrenceLimits

public void setOccurrenceLimits(int minimum,
                                int maximum)

Set the occurrence limits to be used when compiling a finite state automaton.

Parameters:

minimum - The highest value of minOccurs that will be strictly enforced. If the actual value of minOccurs in a schema is higher than this value, it will be treated as if this value had been specified. The default is 100.

maximum - The highest value of maxOccurs that will be strictly enforced. If the actual value of maxOccurs in a schema is higher than this value, it will be treated as if "unbounded" had been specified. The default is 250.

getOccurrenceLimits

public int[] getOccurrenceLimits()

Get the occurrence limits previously set using setOccurrenceLimits (or the default)

Returns:

an array of two integers, the minimum occurrence limit and the maximum occurrence limit

getSchemaURIResolver

public SchemaURIResolver getSchemaURIResolver()

Get the user-defined SchemaURIResolver for resolving URIs used in "import schema" declarations; if none has been explicitly set, returns the standard schema URI resolver.

Overrides:

getSchemaURIResolver in class Configuration

Returns:

the user-defined SchemaURIResolver for resolving URIs

readSchema

public String readSchema(PipelineConfiguration pipe,
                         String baseURI,
                         String schemaLocation,
                         String expected)
                  throws SchemaException

Read a schema from a given schema location

Overrides:

readSchema in class Configuration

Parameters:

pipe - the PipelineConfiguration

baseURI - the base URI for resolving relative URIs

schemaLocation - the location "hint" where to find the schema document. Must not be null.

expected - the target namespace expected; null if there is no expectation

Returns:

the actual target namespace of the schema

Throws:

SchemaException

readMultipleSchemas

public void readMultipleSchemas(PipelineConfiguration pipe,
                                String baseURI,
                                List schemaLocations,
                                String expected)
                         throws SchemaException

Read schemas from a list of schema locations

Overrides:

readMultipleSchemas in class Configuration

Parameters:

pipe - the pipeline configuration

baseURI - the base URI for resolving relative URIs

schemaLocations - the list of location "hints" where to find the schema document. Must not be null.

expected - the target namespace expected in each of the schema documents; null if there is no expectation

Throws:

SchemaException

readInlineSchema

public String readInlineSchema(NodeInfo root,
                               String expected,
                               ErrorListener errorListener)
                        throws SchemaException

Read an inline schema from a stylesheet

Overrides:

readInlineSchema in class Configuration

Parameters:

root - the xs:schema element in the stylesheet

expected - the target namespace expected; "" 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

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 SchemaAwareConfiguration.

Overrides:

addSchemaSource in class Configuration

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. If null, the configuration's errorListener is used

Throws:

SchemaException - if the schema cannot be read or parsed or if it is invalid

addSchema

public void addSchema(PreparedSchema pschema)
               throws SchemaException

Add a schema to the cache

Parameters:

pschema - The schema

Throws:

SchemaException

addSurrogateSchema

public void addSurrogateSchema(String namespace)

Put a temporary schema marker in the cache, to indicate that a schema for a given namespace is being processed. Used to detect circularities

Parameters:

namespace - the target namespace of the schema

getSchema

public PreparedSchema getSchema(String namespace)

Get a schema from the cache. Return null if not found.

Parameters:

namespace - the target namespace of the required schema

Returns:

a PreparedSchema containing the schema components for the specified namespace, or null if it is not present

isSchemaAvailable

public boolean isSchemaAvailable(String targetNamespace)

Determine whether the Configuration contains a cached schema for a given target namespace

Overrides:

isSchemaAvailable in class Configuration

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.

removeSchema

public void removeSchema(String namespace)

Remove the schema for a given namespace. This is done if it is found to be invalid

Parameters:

namespace - the namespace of the schema to be removed

getImportedNamespaces

public Set getImportedNamespaces()

Get the set of namespaces of imported schemas

Overrides:

getImportedNamespaces in class Configuration

Returns:

a Set whose members are the namespaces of all schemas in the schema cache, as String objects

getSuperSchema

public PreparedSchema getSuperSchema()

Get the SuperSchema, containing references to all names defined in all known schemas

Returns:

the PreparedSchema containing the schema components for all loaded target namespaces

sealNamespace

public void sealNamespace(String namespace)

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.

Overrides:

sealNamespace in class Configuration

Parameters:

namespace - the namespace URI of the components to be sealed

isSealedNamespace

public boolean isSealedNamespace(String namespace)

Test whether a schema namespace is sealed. 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 tested

Returns:

true if this namespace has been sealed, otherwise false

getElementDeclaration

public SchemaDeclaration getElementDeclaration(int fingerprint)

Get a global element declaration

Overrides:

getElementDeclaration in class Configuration

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.

getAttributeDeclaration

public SchemaDeclaration getAttributeDeclaration(int fingerprint)

Get a global attribute declaration

Overrides:

getAttributeDeclaration in class Configuration

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

public SchemaType getSchemaType(int fingerprint)

Get the top-level schema type with a given fingerprint.

Overrides:

getSchemaType in class Configuration

Parameters:

fingerprint - the fingerprint of the schema type

Returns:

the schema type , or null if there is none with this name.

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.

Overrides:

checkTypeDerivationIsOK in class Configuration

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

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

Overrides:

getDocumentValidator in class Configuration

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 stream being validated is to be treated as a final output stream (which means multiple errors can be reported)

stripSpace - if set to Whitespace.IGNORABLE, causes whitespace in element-only content to be stripped after validation. Default is taken from the Configuration settings.

schemaType - The type against which the outermost element of the document must be validated (null if there is no constraint)

topLevelElementName - the fingerprint of the required name for the top-level element being validated

Returns:

A Receiver to which events can be sent for validation

getElementValidator

public SequenceReceiver getElementValidator(SequenceReceiver receiver,
                                            int nameCode,
                                            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.

Overrides:

getElementValidator in class Configuration

Parameters:

receiver - the target receiver to receive the validated element

nameCode - the nameCode of the element to be validated. This should be set to -1 if validation against a specific type is required (in which case schemaType must not be null). Otherwise, the namecode must correspond to the name of an element declaration in a loaded schema

locationId - identifies the location of the element within its source document (or, if preferred, the location of the instruction requesting validation)

schemaType - the schema type (typically a complex type) against which the element is to be validated. Supply null if there are no constraints, that is, if validation is to start from the element declaration.

validation - The validation mode, for example Validation.STRICT or Validation.LAX

Returns:

The newly created receiver, which performs the validation and passes the validated elements on to the target receiver.

Throws:

XPathException

validateAttribute

public int validateAttribute(int nameCode,
                             CharSequence value,
                             int validation)
                      throws ValidationException

Validate an attribute value (XSLT only)

Overrides:

validateAttribute in class Configuration

Parameters:

nameCode - the name of the attribute

value - the value of the attribute as a string

validation - STRICT or LAX

Returns:

an int, containing the type annotation to apply to the attribute node

Throws:

ValidationException - if the value is invalid

getAnnotationStripper

public Receiver getAnnotationStripper(Receiver destination)

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.

Overrides:

getAnnotationStripper in class Configuration

Parameters:

destination - the Receiver that events will be written to after whitespace stripping

Returns:

the Receiver to which events should be sent for stripping

getVendorFunctionLibrary

public VendorFunctionLibrary getVendorFunctionLibrary()

Get the FunctionLibrary used to bind calls on Saxon-defined extension functions

Overrides:

getVendorFunctionLibrary in class Configuration

Returns:

the FunctionLibrary used for extension functions in the Saxon library.

buildDocument

public DocumentInfo buildDocument(Source source)
                           throws XPathException

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 registered SourceResolver.

Overrides:

buildDocument in class Configuration

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.

A new tree will be built, using either the Tiny Tree or the Linked Tree implementation, except under the following circumstances:

• The supplied object is a DocumentInfo. In this case a new tree will be built only if validation or whitespace stripping has been requested in the Configuration; otherwise the DocumentInfo will be returned unchanged.
• The supplied object is an AugmentedSource wrapping a DocumentInfo. In this case a new tree will be built if wrap=no has been specified, if validation has been requested, or if whitespace stripping has been requested, either in the AugmentedSource or in the Configuration.
• The supplied object is a DOMSource. In this case a new tree will be built if validation or whitespace stripping has been requested in the Configuration, or if the DOM Node is not a Document Node; in other cases the Document node of the DOMSource will be wrapped in a Saxon DocumentWrapper, except in the case where the DOM Document node is a DocumentOverNodeInfo, in which case the DocumentInfo that it wraps is returned.
• The supplied object is an AugmentedSource wrapping a DOMSource. In this case a new tree will be built if wrap=no has been specified, if validation has been requested, or if whitespace stripping has been requested, either in the AugmentedSource or in the Configuration.

The choice between a tiny tree and a linked tree is determined first be the properties of the AugmentedSource if that's what is supplied; otherwise by the properties of this Configuration.

Returns:

the document node of the constructed or wrapped 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.

makeDocumentProjector

public ProxyReceiver makeDocumentProjector(PathMap.PathMapRoot map)

Create a document projector for a given path map.

Overrides:

makeDocumentProjector in class Configuration

Parameters:

map - the path map used to control document projection

Returns:

a push filter that implements document projection

getOptimizer

public Optimizer getOptimizer()

Factory method to get an Optimizer

Overrides:

getOptimizer in class Configuration

Returns:

the optimizer used in this configuration

resolveSource

public Source resolveSource(Source source,
                            Configuration config)
                     throws XPathException

Implement the SourceResolver interface

Specified by:

resolveSource in interface SourceResolver

Overrides:

resolveSource in class Configuration

Parameters:

source - A source object, typically the source supplied as the first argument to 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

makeEmitter

public Receiver makeEmitter(String clarkName,
                            Controller controller)
                     throws XPathException

Get a configuration-defined output method.

Overrides:

makeEmitter in class Configuration

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 that implements the method, or null if the method URI is not recognized

Throws:

XPathException