com.saxonica.ee.s9api

Class SchemaValidatorImpl

java.lang.Object

net.sf.saxon.s9api.SchemaValidator

com.saxonica.ee.s9api.SchemaValidatorImpl

All Implemented Interfaces:

Destination

public class SchemaValidatorImpl
extends SchemaValidator

A SchemaValidator is an object that is used for validating instance documents against a schema. The schema consists of the collection of schema components that are available within the schema cache maintained by the SchemaManager, together with any additional schema components located during the course of validation by means of an xsl:schemaLocation or xsi:noNamespaceSchemaLocation attribute within the instance document.

If validation fails, an exception is thrown. If validation succeeds, the validated document can optionally be written to a specified destination. This will be a copy of the original document, augmented with default values for absent elements and attributes, and carrying type annotations derived from the schema processing. Expansion of defaults can be suppressed by means of the method setExpandAttributeDefaults(boolean).

A SchemaValidator is serially resuable but not thread-safe. That is, it should normally be used in the thread where it is created, but it can be used more than once, to validate multiple input documents.

A SchemaValidator is a Destination, which allows it to receive the output of a query or transformation to be validated.

Saxon does not deliver the full PSVI as described in the XML schema specifications, only the subset of the PSVI properties featured in the XDM data model.

Constructor Summary

Constructors

Constructor and Description
SchemaValidatorImpl(Processor processor)

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close the destination, allowing resources to be released.
protected ValidationParams	convertParams(GlobalParameterSet suppliedParams, Collection<GlobalParam> declaredParams)
Destination	getDestination() Get the Destination that will receive the validated document.
QName	getDocumentElementName() Get the name of the required top-level element of the document to be validated.
protected SchemaType	getDocumentElementType() Get the schema type against which the document element is to be validated
QName	getDocumentElementTypeName() Get the name of the required type of the top-level element of the document to be validated.
ErrorListener	getErrorListener() Get the ErrorListener being used while validating instance documents
InvalidityHandler	getInvalidityHandler() Get the InvalidityHandler used when validating instance documents
XdmValue	getParameter(QName name) Get the value that has been set for a schema parameter (a parameter defined in the schema using the saxon:param extension)
Receiver	getReceiver(Configuration config) Return a Receiver.
InvalidityHandler	getReportingHandler()
boolean	isCollectStatistics() Ask whether validation statistics are to be collected
boolean	isExpandAttributeDefaults() Ask whether attribute defaults defined in a schema are to be expanded or not (by default, fixed and default attribute values are expanded, that is, they are inserted into the document during validation as if they were present in the instance being validated)
boolean	isLax() Ask whether validation is to be in lax mode.
boolean	isUseXsiSchemaLocation() Ask whether the schema processor is to take account of any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered while validating an instance document
void	reportValidationStatistics(Destination destination) Report the validation statistics from the most recent validation episode Does nothing if no validation statistics have been collected.
void	setCollectStatistics(boolean collect) Say whether validation statistics are to be collected.
void	setDestination(Destination destination) Set the Destination to receive the validated document.
void	setDocumentElementName(QName name) Set the name of the required top-level element of the document to be validated (that is, the name of the outermost element of the document).
void	setDocumentElementTypeName(QName name) Set the name of the required type of the top-level element of the document to be validated.
void	setErrorListener(ErrorListener listener) Set the ErrorListener to be used while validating instance documents.
void	setExpandAttributeDefaults(boolean expand) Set whether attribute defaults defined in a schema are to be expanded or not (by default, fixed and default attribute values are expanded, that is, they are inserted into the document during validation as if they were present in the instance being validated)
void	setInvalidityHandler(InvalidityHandler handler) Set the InvalidityHandler to be used when validating instance documents
void	setLax(boolean lax) The validation mode may be either strict or lax.
void	setParameter(QName name, XdmValue value) Set the value of a schema parameter (a parameter defined in the schema using the saxon:param extension)
void	setThreadCount(int tc)
void	setUseXsiSchemaLocation(boolean recognize) Say whether the schema processor is to take account of any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered while validating an instance document
void	setValidityReporting(Destination destination) Setup Validation Reporting feature which saves the validation errors in an XML file
void	validate(Source source) Validate an instance document supplied as a Source object
void	validateMultiple(Iterable<Source> sources) Validate multiple instance document supplied as a Iterable of instance Source objects

Methods inherited from class java.lang.Object

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

Constructor Detail

SchemaValidatorImpl

public SchemaValidatorImpl(Processor processor)

Method Detail

setLax

public void setLax(boolean lax)

The validation mode may be either strict or lax. The default is strict; this method may be called to indicate that lax validation is required. With strict validation, validation fails if no element declaration can be located for the outermost element. With lax validation, the absence of an element declaration results in the content being considered valid.

Specified by:

setLax in class SchemaValidator

Parameters:

lax - true if validation is to be lax, false if it is to be strict

isLax

public boolean isLax()

Ask whether validation is to be in lax mode.

Specified by:

isLax in class SchemaValidator

Returns:

true if validation is to be in lax mode, false if it is to be in strict mode.

setErrorListener

public void setErrorListener(ErrorListener listener)

Set the ErrorListener to be used while validating instance documents.

Specified by:

setErrorListener in class SchemaValidator

Parameters:

listener - The error listener to be used. This is notified of all errors detected during the validation episode.

getErrorListener

public ErrorListener getErrorListener()

Get the ErrorListener being used while validating instance documents

Specified by:

getErrorListener in class SchemaValidator

Returns:

listener The error listener in use. This is notified of all errors detected during the validation episode. Returns null if no user-supplied ErrorListener has been set.

setValidityReporting

public void setValidityReporting(Destination destination)
                          throws SaxonApiException

Setup Validation Reporting feature which saves the validation errors in an XML file

Specified by:

setValidityReporting in class SchemaValidator

Parameters:

destination - where XML will be sent

Throws:

SaxonApiException

getReportingHandler

public InvalidityHandler getReportingHandler()

Specified by:

getReportingHandler in class SchemaValidator

getInvalidityHandler

public InvalidityHandler getInvalidityHandler()

Get the InvalidityHandler used when validating instance documents

Specified by:

getInvalidityHandler in class SchemaValidator

Returns:

the InvalidityHandler being used

setInvalidityHandler

public void setInvalidityHandler(InvalidityHandler handler)

Set the InvalidityHandler to be used when validating instance documents

Specified by:

setInvalidityHandler in class SchemaValidator

Parameters:

handler - the InvalidityHandler to be used

setCollectStatistics

public void setCollectStatistics(boolean collect)

Say whether validation statistics are to be collected. Calling this method has the side-effect of deleting any statistics previously collected.

Specified by:

setCollectStatistics in class SchemaValidator

Parameters:

collect - true if validation statistics are to be collected (default is false)

Since:

9.6

isCollectStatistics

public boolean isCollectStatistics()

Ask whether validation statistics are to be collected

Specified by:

isCollectStatistics in class SchemaValidator

Returns:

true if validation statistics are to be collected (default is false)

Since:

9.6

reportValidationStatistics

public void reportValidationStatistics(Destination destination)
                                throws SaxonApiException

Report the validation statistics from the most recent validation episode Does nothing if no validation statistics have been collected.

Specified by:

reportValidationStatistics in class SchemaValidator

Parameters:

destination - the destination to which the statistics will be written. The XML format of the destination is not guaranteed to be stable across Saxon releases.

Throws:

SaxonApiException - if any error occurs writing the statistics

Since:

Saxon 9.6

setUseXsiSchemaLocation

public void setUseXsiSchemaLocation(boolean recognize)

Say whether the schema processor is to take account of any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered while validating an instance document

Specified by:

setUseXsiSchemaLocation in class SchemaValidator

Parameters:

recognize - true if these two attributes are to be recognized; false if they are to be ignored. Default is true.

isUseXsiSchemaLocation

public boolean isUseXsiSchemaLocation()

Ask whether the schema processor is to take account of any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered while validating an instance document

Specified by:

isUseXsiSchemaLocation in class SchemaValidator

Returns:

true if these two attributes are to be recognized; false if they are to be ignored. Default is true.

setDestination

public void setDestination(Destination destination)

Set the Destination to receive the validated document. If no destination is supplied, the validated document is discarded.

Specified by:

setDestination in class SchemaValidator

Parameters:

destination - the destination to receive the validated document

getDestination

public Destination getDestination()

Get the Destination that will receive the validated document. Return null if no destination has been set.

Specified by:

getDestination in class SchemaValidator

Returns:

the destination to receive the validated document, or null if none has been supplied

setDocumentElementName

public void setDocumentElementName(QName name)

Set the name of the required top-level element of the document to be validated (that is, the name of the outermost element of the document). If no value is supplied, there is no constraint on the required element name

Specified by:

setDocumentElementName in class SchemaValidator

Parameters:

name - the name of the document element, as a QName; or null to remove a previously-specified value.

getDocumentElementName

public QName getDocumentElementName()

Get the name of the required top-level element of the document to be validated.

Specified by:

getDocumentElementName in class SchemaValidator

Returns:

the name of the required document element, or null if no value has been set.

setDocumentElementTypeName

public void setDocumentElementTypeName(QName name)
                                throws SaxonApiException

Set the name of the required type of the top-level element of the document to be validated. If no value is supplied, there is no constraint on the required type

Specified by:

setDocumentElementTypeName in class SchemaValidator

Parameters:

name - the name of the type of the document element, as a QName; or null to remove a previously-specified value. This must be the name of a type in the schema (typically but not necessarily a complex type).

Throws:

SaxonApiException - if there is no known type with this name

getDocumentElementTypeName

public QName getDocumentElementTypeName()

Get the name of the required type of the top-level element of the document to be validated.

Specified by:

getDocumentElementTypeName in class SchemaValidator

Returns:

the name of the required type of the document element, or null if no value has been set.

getDocumentElementType

protected SchemaType getDocumentElementType()

Get the schema type against which the document element is to be validated

Specified by:

getDocumentElementType in class SchemaValidator

Returns:

the schema type

setExpandAttributeDefaults

public void setExpandAttributeDefaults(boolean expand)

Set whether attribute defaults defined in a schema are to be expanded or not (by default, fixed and default attribute values are expanded, that is, they are inserted into the document during validation as if they were present in the instance being validated)

Specified by:

setExpandAttributeDefaults in class SchemaValidator

Parameters:

expand - true if defaults are to be expanded, false if not

isExpandAttributeDefaults

public boolean isExpandAttributeDefaults()

Ask whether attribute defaults defined in a schema are to be expanded or not (by default, fixed and default attribute values are expanded, that is, they are inserted into the document during validation as if they were present in the instance being validated)

Specified by:

isExpandAttributeDefaults in class SchemaValidator

Returns:

true if defaults are to be expanded, false if not

setParameter

public void setParameter(QName name,
                XdmValue value)

Set the value of a schema parameter (a parameter defined in the schema using the saxon:param extension)

Specified by:

setParameter in class SchemaValidator

Parameters:

name - the name of the schema parameter, as a QName

value - the value of the schema parameter, or null to clear a previously set value

Since:

9.5

getParameter

public XdmValue getParameter(QName name)

Get the value that has been set for a schema parameter (a parameter defined in the schema using the saxon:param extension)

Specified by:

getParameter in class SchemaValidator

Parameters:

name - the parameter whose name is required

Returns:

the value that has been set for the parameter, or null if no value has been set

Since:

9.5

setThreadCount

public void setThreadCount(int tc)

validateMultiple

public void validateMultiple(Iterable<Source> sources)
                      throws SaxonApiException

Validate multiple instance document supplied as a Iterable of instance Source objects

Specified by:

validateMultiple in class SchemaValidator

Parameters:

sources - the Iterable of instance documents to be validated. The call getSystemId() applied to the source objects must return the base URI used for dereferencing any xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes

Throws:

SaxonApiException - if the source document is found to be invalid, or if error conditions occur that prevented validation from taking place (such as failure to read or parse the input document). The wrapped exception acting as the cause of the SaxonApiException can be used to distinguish these failure conditions.

validate

public void validate(Source source)
              throws SaxonApiException

Validate an instance document supplied as a Source object

Specified by:

validate in class SchemaValidator

Parameters:

source - the instance document to be validated. The call getSystemId() applied to this source object must return the base URI used for dereferencing any xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes

Throws:

SaxonApiException - if the source document is found to be invalid, or if error conditions occur that prevented validation from taking place (such as failure to read or parse the input document). The wrapped exception acting as the cause of the SaxonApiException can be used to distinguish these failure conditions.

convertParams

protected ValidationParams convertParams(GlobalParameterSet suppliedParams,
                             Collection<GlobalParam> declaredParams)
                                  throws XPathException

Throws:

XPathException

getReceiver

public Receiver getReceiver(Configuration config)
                     throws SaxonApiException

Description copied from interface: Destination

Return a Receiver. Saxon calls this method to obtain a Receiver, to which it then sends a sequence of events representing the content of an XML document. The method is intended primarily for internal use, and may give poor diagnostics if used incorrectly.

Specified by:

getReceiver in interface Destination

Specified by:

getReceiver in class SchemaValidator

Parameters:

config - The Saxon configuration. This is supplied so that the destination can use information from the configuration (for example, a reference to the name pool) to construct or configure the returned Receiver.

Returns:

the Receiver to which events are to be sent. It is the caller's responsibility to initialize this Receiver with a PipelineConfiguration before calling its open() method. The caller is also responsible for ensuring that the sequence of events sent to the Receiver represents a well-formed document: in particular the event stream must include namespace events corresponding exactly to the namespace declarations that are required. If the calling code cannot guarantee this, it should insert a NamespaceReducer into the pipeline in front of the returned Receiver.

Throws:

SaxonApiException - if the Receiver cannot be created

close

public void close()
           throws SaxonApiException

Close the destination, allowing resources to be released. Saxon calls this method when it has finished writing to the destination.

Specified by:

close in interface Destination

Specified by:

close in class SchemaValidator

Throws:

SaxonApiException - if any failure occurs