Package net.sf.saxon.s9api

## Class SchemaValidator

- java.lang.Object
- - net.sf.saxon.s9api.AbstractDestination
  - - net.sf.saxon.s9api.SchemaValidator

- All Implemented Interfaces:
    `Destination`
  Direct Known Subclasses:
    `SchemaValidatorImpl`

      public abstract class SchemaValidator
      extends AbstractDestination

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

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.s9api.AbstractDestination

      `helper`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SchemaValidator()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | 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.
    `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.
    `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).

    - ### Methods inherited from class net.sf.saxon.s9api.AbstractDestination

      `closeAndNotify, getDestinationBaseURI, onClose, setDestinationBaseURI`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SchemaValidator

          public SchemaValidator()

  - ### Method Detail

    - #### setLax

          public abstract 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.
      Parameters:
        `lax` - true if validation is to be lax, false if it is to be strict

    - #### isLax

          public abstract boolean isLax()

      Ask whether validation is to be in lax mode.
      Returns:
        true if validation is to be in lax mode, false if it is to be in strict mode.

    - #### setErrorListener

          public abstract void setErrorListener​(javax.xml.transform.ErrorListener listener)

      Deprecated.
      since 10.0. Use `setInvalidityHandler(InvalidityHandler)`
      Set the ErrorListener to be used while validating instance documents. The setErrorReporter, setInvalidityHandler, and setValidityReporting are mutually exclusive - setting any one of them will cancel the others. Please note that setErrorReporter has the drawback of creating an exception for every validation error, which is expensive.
      Parameters:
        `listener` - The error listener to be used. This is notified of all errors detected during the validation episode.

    - #### getErrorListener

          public abstract javax.xml.transform.ErrorListener getErrorListener()

      Deprecated.
      since 10.0. Use `getInvalidityHandler()`
      Get the ErrorListener being used while validating instance documents
      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.

    - #### setInvalidityHandler

          public abstract void setInvalidityHandler​(InvalidityHandler handler)

      Set the 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.
      Parameters:
        `handler` - the InvalidityHandler to be used.

    - #### getInvalidityHandler

          public abstract InvalidityHandler getInvalidityHandler()

      Get the InvalidityHandler used when validating instance documents
      Returns:
        the InvalidityHandler being used

    - #### setCollectStatistics

          public abstract 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.
      Parameters:
        `collect` - true if validation statistics are to be collected (default is false)
      Since:
        9.6

    - #### isCollectStatistics

          public abstract boolean isCollectStatistics()

      Ask whether validation statistics are to be collected
      Returns:
        true if validation statistics are to be collected (default is false)
      Since:
        9.6

    - #### reportValidationStatistics

          public abstract 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.
      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

    - #### setValidityReporting

          public abstract void setValidityReporting​(Destination destination)
                                             throws SaxonApiException

      This method can be called before running a validation to define a destination to which validation reports should be written. The validation report is in XML format, and the 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 or ErrorListener 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(net.sf.saxon.s9api.Destination)` 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. The `setErrorListener(javax.xml.transform.ErrorListener)`, `setInvalidityHandler(net.sf.saxon.lib.InvalidityHandler)`, and `setValidityReporting(net.sf.saxon.s9api.Destination)` are mutually exclusive - setting any one of them will cancel the others.
      Parameters:
        `destination` - where XML will be sent
      Throws:
        `SaxonApiException` - if the destination is unsuitable

    - #### setUseXsiSchemaLocation

          public 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
      Parameters:
        `recognize` - true if these two attributes are to be recognized; false if they are to be ignored. Default is true.

    - #### isUseXsiSchemaLocation

          public 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
      Returns:
        true if these two attributes are to be recognized; false if they are to be ignored. Default is true.

    - #### setDestination

          public abstract void setDestination​(Destination destination)

      Set the Destination to receive the validated document. If no destination is supplied, the validated document is discarded.
      Parameters:
        `destination` - the destination to receive the validated document

    - #### getDestination

          public abstract Destination getDestination()

      Get the Destination that will receive the validated document. Return null if no destination has been set.
      Returns:
        the destination to receive the validated document, or null if none has been supplied

    - #### setDocumentElementName

          public 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). If no value is supplied, there is no constraint on the required element name
      Parameters:
        `name` - the name of the document element, as a QName; or null to remove a previously-specified value.

    - #### getDocumentElementName

          public abstract QName getDocumentElementName()

      Get the name of the required top-level element of the document to be validated.
      Returns:
        the name of the required document element, or null if no value has been set.

    - #### setDocumentElementTypeName

          public abstract 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
      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 abstract QName getDocumentElementTypeName()

      Get the name of the required type of the top-level element of the document to be validated.
      Returns:
        the name of the required type of the document element, or null if no value has been set.

    - #### getDocumentElementType

          protected abstract SchemaType getDocumentElementType()

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

    - #### setExpandAttributeDefaults

          public 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)
      Parameters:
        `expand` - true if defaults are to be expanded, false if not

    - #### isExpandAttributeDefaults

          public 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)
      Returns:
        true if defaults are to be expanded, false if not

    - #### setParameter

          public 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)
      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 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)
      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

    - #### validate

          public abstract void validate​(javax.xml.transform.Source source)
                                 throws SaxonApiException

      Validate an instance document supplied as a Source object
      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.

    - #### validateMultiple

          public abstract void validateMultiple​(java.lang.Iterable<javax.xml.transform.Source> sources)
                                         throws SaxonApiException

      This method can be called to validate multiple source documents simultaneously (in parallel threads). The method returns when all the threads are complete. The number of threads used is set to the number of processors available on the machine. When this method is used, any destination set using the setDestination() 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 setValidityReport; 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 FeatureKeys.ALLOW_MULTITHREADING is set to false, the source documents are validated synchronously in a single thread.
      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.

    - #### asSource

          public javax.xml.transform.Source asSource​(javax.xml.transform.Source input)

      Construct a Source object that applies validation to an underlying input Source. This method does not cause validation to take place immediately: the validation happens only when the returned `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.
      Parameters:
        `input` - the input Source to be validated
      Returns:
        a Source object that reads the supplied input source and returns events corresponding to the result of validating the input source. The Source object will be recognized by all Saxon methods that expect a `Source` as input, but not (in general) by other products.
      Since:
        9.9

    - #### getReceiver

          public abstract Receiver getReceiver​(PipelineConfiguration pipe,
                                               SerializationProperties params)
                                        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 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.

      Parameters:
        `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.

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

      Throws:
        `SaxonApiException` - if the Receiver cannot be created

    - #### close

          public abstract void close()
                              throws SaxonApiException

      Close the destination, allowing resources to be released. Saxon calls this method when it has finished writing to the destination.
      Throws:
        `SaxonApiException` - if any failure occurs