Package com.saxonica.ee.s9api

## Class SchemaValidatorImpl

- java.lang.Object
- - net.sf.saxon.s9api.AbstractDestination
  - - 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 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
    --- | ---
    `SchemaValidatorImpl​(Processor processor)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Close the destination, allowing resources to be released.
    `protected ValidationParams` | `convertParams​(GlobalParameterSet suppliedParams, java.util.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.
    `javax.xml.transform.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​(PipelineConfiguration pipe, SerializationProperties params)` | A SchemaValidator is a Destination (for example, it can act as the destination of a query or transformation).
    `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​(javax.xml.transform.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​(javax.xml.transform.Source source)` | Validate an instance document supplied as a Source object
    `void` | `validateMultiple​(java.lang.Iterable<javax.xml.transform.Source> sources)` | Validate multiple instance documents supplied as a Iterable collection of Source objects

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

      `asSource`

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

    - #### 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​(javax.xml.transform.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 javax.xml.transform.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 the invalidity handler is not one that wraps an error listener.

    - #### 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` - if the destination cannot be configured for this purpose

    - #### 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
      Throws:
        `SaxonApiUncheckedException` - if the value is lazily evaluated and evaluation fails
      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​(java.lang.Iterable<javax.xml.transform.Source> sources)
                                throws SaxonApiException

      Validate multiple instance documents supplied as a Iterable collection of Source objects
      Specified by:
        `validateMultiple` in class `SchemaValidator`
      Parameters:
        `sources` - the Iterable collection 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​(javax.xml.transform.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,
                                                   java.util.Collection<GlobalParam> declaredParams)
                                            throws XPathException

      Throws:
        `XPathException`

    - #### getReceiver

          public Receiver getReceiver​(PipelineConfiguration pipe,
                                      SerializationProperties params)
                               throws SaxonApiException

      A SchemaValidator is a Destination (for example, it can act as the destination of a query or transformation). The getReceiver() method is used internally to provide the receiver to which events can be sent; the effect is that the SchemaValidator validates the document represented by this sequence of events
      Specified by:
        `getReceiver` in interface `Destination`
      Specified by:
        `getReceiver` in class `SchemaValidator`
      Parameters:
        `pipe` - the Saxon Configuration
        `params` -
      Returns:
        a Receiver to which events can be sent
      Throws:
        `SaxonApiException` - if a failure occurs

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