public abstract class SchemaValidator extends AbstractDestination
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 reusable 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.
helper
Constructor and Description |
---|
SchemaValidator() |
Modifier and Type | Method and Description |
---|---|
javax.xml.transform.Source |
asSource(javax.xml.transform.Source input)
Construct a Source object that applies validation to an underlying input Source.
|
abstract void |
close()
Close the destination, allowing resources to be released.
|
abstract Destination |
getDestination()
Get the Destination that will receive the validated document.
|
abstract QName |
getDocumentElementName()
Get the name of the required top-level element of the document to be validated.
|
protected abstract SchemaType |
getDocumentElementType()
Get the schema type against which the document element is to be validated
|
abstract QName |
getDocumentElementTypeName()
Get the name of the required type of the top-level element of the document to be validated.
|
abstract javax.xml.transform.ErrorListener |
getErrorListener()
Deprecated.
since 10.0. Use
getInvalidityHandler() |
abstract InvalidityHandler |
getInvalidityHandler()
Get the
InvalidityHandler used when validating instance documents |
abstract 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) |
abstract Receiver |
getReceiver(PipelineConfiguration pipe,
SerializationProperties params)
Return a
Receiver . |
abstract boolean |
isCollectStatistics()
Ask whether validation statistics are to be collected
|
abstract 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)
|
abstract boolean |
isLax()
Ask whether validation is to be in lax mode.
|
abstract 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
|
abstract void |
reportValidationStatistics(Destination destination)
Report the validation statistics from the most recent validation episode
Does nothing if no validation statistics have been collected.
|
abstract void |
setCollectStatistics(boolean collect)
Say whether validation statistics are to be collected.
|
abstract void |
setDestination(Destination destination)
Set the Destination to receive the validated document.
|
abstract 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).
|
abstract void |
setDocumentElementTypeName(QName name)
Set the name of the required type of the top-level element of the document to be validated.
|
abstract void |
setErrorListener(javax.xml.transform.ErrorListener listener)
Deprecated.
since 10.0. Use
setInvalidityHandler(InvalidityHandler) |
abstract 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)
|
abstract void |
setInvalidityHandler(InvalidityHandler handler)
Set the
InvalidityHandler to be used when validating instance documents. |
abstract void |
setLax(boolean lax)
The validation mode may be either strict or lax.
|
abstract void |
setParameter(QName name,
XdmValue value)
Set the value of a schema parameter (a parameter defined in the schema using
the
saxon:param extension) |
abstract 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
|
abstract void |
setValidityReporting(Destination destination)
This method can be called before running a validation to define a destination to which validation
reports should be written.
|
abstract void |
validate(javax.xml.transform.Source source)
Validate an instance document supplied as a Source object
|
abstract void |
validateMultiple(java.lang.Iterable<javax.xml.transform.Source> sources)
This method can be called to validate multiple source documents simultaneously (in parallel threads).
|
closeAndNotify, getDestinationBaseURI, onClose, setDestinationBaseURI
public abstract void setLax(boolean lax)
lax
- true if validation is to be lax, false if it is to be strictpublic abstract boolean isLax()
@Deprecated public abstract void setErrorListener(javax.xml.transform.ErrorListener listener)
setInvalidityHandler(InvalidityHandler)
listener
- The error listener to be used. This is notified of all errors detected during the
validation episode.@Deprecated public abstract javax.xml.transform.ErrorListener getErrorListener()
getInvalidityHandler()
public abstract void setInvalidityHandler(InvalidityHandler handler)
InvalidityHandler
to be used when validating instance documents.
The setErrorReporter, setInvalidityHandler, and setValidityReporting
are mutually exclusive - setting any one of them will cancel the others.handler
- the InvalidityHandler to be used.public abstract InvalidityHandler getInvalidityHandler()
InvalidityHandler
used when validating instance documentspublic abstract void setCollectStatistics(boolean collect)
collect
- true if validation statistics are to be collected (default is false)public abstract boolean isCollectStatistics()
public abstract void reportValidationStatistics(Destination destination) throws SaxonApiException
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.SaxonApiException
- if any error occurs writing the statisticspublic abstract void setValidityReporting(Destination destination) throws SaxonApiException
Destination
may therefore
be (for example) a Serializer
, an XdmDestination
, or an XsltTransformer
.
(An XsltTransformer
might be used to render the report as HTML, for example). The format
of the validation report is defined in a schema which is available in the saxon-resources download file.
Calling this method has the effect of setting an InvalidityHandler
internally, which cancels any
user-defined InvalidityHandler
that has been set.
This option applies only to the next call of validate(javax.xml.transform.Source)
or validateMultiple(java.lang.Iterable<javax.xml.transform.Source>)
.
After such a call, the registered InvalidityHandler
is reset to its initial default state (which causes
validation errors to be output to System.err
), and setValidityReporting
must be called again
if reports are required for subsequent validations.
If multiple documents are validated using the validateMultiple(java.lang.Iterable<javax.xml.transform.Source>)
method, the reports for each
validation will be combined into a single report. Using this mechanism when validating multiple documents
simultaneously is recommended, because with other mechanisms, validation failures for different source
documents will be interleaved, and it becomes an application responsibility to organize which failures
relate to which source document.
destination
- where XML will be sentSaxonApiException
- if the destination is unsuitablepublic abstract void setUseXsiSchemaLocation(boolean recognize)
recognize
- true if these two attributes are to be recognized; false if they are to
be ignored. Default is true.public abstract boolean isUseXsiSchemaLocation()
public abstract void setDestination(Destination destination)
destination
- the destination to receive the validated documentpublic abstract Destination getDestination()
public abstract void setDocumentElementName(QName name)
name
- the name of the document element, as a QName; or null to remove a previously-specified
value.public abstract QName getDocumentElementName()
public abstract void setDocumentElementTypeName(QName name) throws SaxonApiException
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).SaxonApiException
- if there is no known type with this namepublic abstract QName getDocumentElementTypeName()
protected abstract SchemaType getDocumentElementType()
public abstract void setExpandAttributeDefaults(boolean expand)
expand
- true if defaults are to be expanded, false if notpublic abstract boolean isExpandAttributeDefaults()
public abstract void setParameter(QName name, XdmValue value)
saxon:param
extension)name
- the name of the schema parameter, as a QNamevalue
- the value of the schema parameter, or null to clear a previously set valuepublic abstract XdmValue getParameter(QName name)
saxon:param
extension)name
- the parameter whose name is requiredpublic abstract void validate(javax.xml.transform.Source source) throws SaxonApiException
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 attributesSaxonApiException
- 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.public abstract void validateMultiple(java.lang.Iterable<javax.xml.transform.Source> sources) throws SaxonApiException
When this method is used, any destination set using the setDestination(net.sf.saxon.s9api.Destination)
method is ignored. The
post-validation documents (with type annotations and expanded default values, for example) are not
made available.
It is recommended to use this method in conjunction with setValidityReporting(net.sf.saxon.s9api.Destination)
; the resulting report will
detail the outcome of validation for each supplied Source
, each in a separate section.
It is important that the systemId property of each Source object should be set; otherwise, it will not be possible in the resulting report to associate validation failures with individual source documents.
Note that the method does not throw an exception if any of the documents are found to be invalid, or if any of the documents cannot be validated (for example, because they are not well-formed XML, or because they cannot be retrieved from a web server). All such errors are reported in the validation report, or are notified to the registered ErrorListener or InvalidityHandler. By default, messages detailing the failures are simply written to System.err output.
If the Configuration option Feature.ALLOW_MULTITHREADING
is set to false, the source documents are
validated synchronously in a single thread.
The method returns when all the source documents have been validated.
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 attributesSaxonApiException
- if error conditions occur that prevented validation from taking place (such
as failure to read or parse an input document). No exception occurs if validation of all source documents
ran to completion, whether or not they were found to be valid.public javax.xml.transform.Source asSource(javax.xml.transform.Source input)
Source
is consumed. The Destination
associated with this SchemaValidator is ignored; indeed, it is overwritten. After
calling this method, the SchemaValidator
should not be used again for any
other purpose.input
- the input Source to be validatedSource
as input,
but not (in general) by other products.public abstract Receiver getReceiver(PipelineConfiguration pipe, SerializationProperties params) throws SaxonApiException
Destination
Receiver
. Saxon calls this method to obtain a Receiver, to which it then sends
a sequence of events representing an XDM value. The method is intended
primarily for internal use, and may give poor diagnostics if used incorrectly.
This method is normally only called once. However, in the case where a stylesheet includes
a call of xsl:result-document
with no href
attribute (or with an
href
attribute that resolves to the base output URI of the transformation), the
method may be called a second time (with a potentially different set of serialization parameters,
and perhaps a different validation request) to return a second Outputter
, which will typically
write to the same destination. The XSLT rules ensure that it is not possible to write principal and
secondary output to the same destination, so only one of these Receivers will actually be used.
pipe
- The pipeline 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.params
- Serialization parameters known to the caller of the method; typically,
output properties defined in a stylesheet or query. These will mainly
be of interest if the destination is performing serialization, but some
properties (such as item-separator
) are also used in other
situations. These properties are typically subordinate to any properties
defined on the (serializer) destination itself: for example if indent=yes
was explicitly specified on a Serializer
, this takes precedence
over indent=no
defined in a query or stylesheet.
The SerializationProperties
object may also contain a factory object for
generating a validator to add to the output pipeline. The Destination
object
is responsible for instantiating this validator and inserting it into the pipeline.
In most cases this is done by invoking the helper method
SerializationProperties.makeSequenceNormalizer(Receiver)
. Validation can be skipped
in the case of non-XML destinations.
It is the caller's responsibility to
initialize this Receiver with a PipelineConfiguration
before calling
its open()
method.
The Receiver
is expected to handle a regular event sequence as defined in
RegularSequenceChecker
. It is the caller's responsibility to
ensure that the sequence of calls to the Receiver
satisfies these rules, and it
is the responsibility of the implementation to accept any sequence conforming these rules;
the implementation is not expected to check that the sequence is valid, but it can do so
if it wishes by inserting a RegularSequenceChecker
into the pipeline.
The sequence of events passed to the Receiver
represents the raw results of
the query or transformation. If the Destination
is to perform sequence normalization,
this is typically done by returning a SequenceNormalizer
as the
result of this method.
The returned Receiver
is responsible for ensuring that when its Outputter.close()
method is called, this results in all registered onClose
actions being invoked.
An implementation returning a SequenceNormalizer
can achieve this by registering
the actions with the SequenceNormalizer.onClose(java.util.List<net.sf.saxon.s9api.Action>)
method.
Only a single call on this method will be made during the lifetime of the Destination
object, with the exception of the case noted above where a secondary result document is written
to the same destination as the principal transformation result.
SaxonApiException
- if the Receiver cannot be createdpublic abstract void close() throws SaxonApiException
SaxonApiException
- if any failure occursCopyright (c) 2004-2022 Saxonica Limited. All rights reserved.