Package com.saxonica.ee.jaxp

## Class SchemaFactoryImpl

- java.lang.Object
- - javax.xml.validation.SchemaFactory
  - - com.saxonica.ee.jaxp.SchemaFactoryImpl

- All Implemented Interfaces:
    `Configuration.ApiProvider`

      public class SchemaFactoryImpl
      extends javax.xml.validation.SchemaFactory
      implements Configuration.ApiProvider

  This is the Saxon implementation of the JAXP 1.3 SchemaFactory interface.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SchemaFactoryImpl.ErrorReporterWrappingErrorHandler` | A JAXP ErrorListener that wraps a SAX ErrorHandler

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static boolean` | `ENABLED` | A mutable static variable (horrible but useful) allowing the use of this SchemaFactory to be disabled.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SchemaFactoryImpl()` | Default constructor.
    `SchemaFactoryImpl​(EnterpriseConfiguration config)` | Constructor supplying an EnterpriseConfiguration

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `EnterpriseConfiguration` | `getConfiguration()` | Get the underlying Saxon Configuration object
    `org.xml.sax.ErrorHandler` | `getErrorHandler()` | Get the error handler in use
    `boolean` | `getFeature​(java.lang.String name)` | Look up the value of a feature flag.
    `java.lang.Object` | `getProperty​(java.lang.String name)` | Look up the value of a property.
    `org.w3c.dom.ls.LSResourceResolver` | `getResourceResolver()` | Get the resolver used for dereferencing URIs encountered during schema processing and validation.
    `boolean` | `isSchemaLanguageSupported​(java.lang.String language)` | Tests whether a particular schema language is supported.
    `javax.xml.validation.Schema` | `newSchema()` | Returns the `Schema` object containing all the schema components that have been loaded using the `newSchema(javax.xml.transform.Source[])` method.
    `javax.xml.validation.Schema` | `newSchema​(javax.xml.transform.Source[] sources)` | Parses the specified source(s) as a schema and returns it as a schema.
    `static void` | `setConfigurationFactory​(java.util.function.Supplier<EnterpriseConfiguration> factory)` | Static customization method to register a factory method for instantiating the `EnterpriseConfiguration`.
    `void` | `setErrorHandler​(org.xml.sax.ErrorHandler errorHandler)` | Set an error handler to which all schema processing errors will be notified.
    `void` | `setFeature​(java.lang.String name, boolean value)` | Set a feature for this `SchemaFactory`.
    `void` | `setProperty​(java.lang.String name, java.lang.Object object)` | Set the value of a property.
    `void` | `setResourceResolver​(org.w3c.dom.ls.LSResourceResolver lsResourceResolver)` | Set a resolver to be used for dereferencing URIs encountered during schema processing and validation.

    - ### Methods inherited from class javax.xml.validation.SchemaFactory

      `newDefaultInstance, newInstance, newInstance, newSchema, newSchema, newSchema`

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

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

- - ### Field Detail

    - #### ENABLED

          public static boolean ENABLED

      A mutable static variable (horrible but useful) allowing the use of this SchemaFactory to be disabled. If the value of this variable is set to false, then when the JAXP classpath search calls `isSchemaLanguageSupported(String)`, the response will be false, meaning that Saxon does not get used as the Schema validation provider even though it is present on the classpath.

  - ### Constructor Detail

    - #### SchemaFactoryImpl

          public SchemaFactoryImpl()

      Default constructor. This is designed to be invoked via the JAXP SchemaFactory.newInstance() mechanism, but it can also be invoked directly if the application will always be using the Saxon implementation. Instantiating a SchemaFactory directly in this way is likely to be a lot faster than the JAXP mechanism, because it avoid the expensive search of all JARs on the classpath.

      This constructor creates an EnterpriseConfiguration: to do so it calls the registered ConfigurationProvider. The ConfigurationProvider can be customized using the (static) method `setConfigurationFactory(Supplier)`.

      The constructor does not at this stage check that a license key is installed.

    - #### SchemaFactoryImpl

          public SchemaFactoryImpl​(EnterpriseConfiguration config)

      Constructor supplying an EnterpriseConfiguration
      Parameters:
        `config` - The EnterpriseConfiguration. The method verifies that this is usable by checking that a license key is available.

  - ### Method Detail

    - #### setConfigurationFactory

          public static void setConfigurationFactory​(java.util.function.Supplier<EnterpriseConfiguration> factory)

      Static customization method to register a factory method for instantiating the `EnterpriseConfiguration`. This callback can be used to initialize a configuration (for example, by reading it from a configuration file, or by setting configuration options and/or a license key)
      Parameters:
        `factory` - the class that will be called to instantiate or initialize the configuration, assuming the class is instantiated implicitly as a consequence of the JAXP search mechanism. (Despite the name, the callback is not required to create a new `EnterpriseConfiguration`. It can equally well return an existing one.)

    - #### isSchemaLanguageSupported

          public boolean isSchemaLanguageSupported​(java.lang.String language)

      Tests whether a particular schema language is supported.
      Specified by:
        `isSchemaLanguageSupported` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `language` - URI identifying the language (see JAXP specifications for details).
      Returns:
        true if the requested language is XML Schema (XMLConstants.W3C_XML_SCHEMA_NS_URI), (or the language versions `XSD10_LANGUAGE_IDENTIFIER` or `XSD11_LANGUAGE_IDENTIFIER`; otherwise false.

        Always returns false if the static variable {#ENABLED} is set to false.

        Always returns false if no Saxon Enterprise license can be found.

    - #### setErrorHandler

          public void setErrorHandler​(org.xml.sax.ErrorHandler errorHandler)

      Set an error handler to which all schema processing errors will be notified. May be null, in which case all schema processing errors are fatal. The error handler is NOT inherited by instances of Validator or ValidatorHandler created using this factory.
      Specified by:
        `setErrorHandler` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `errorHandler` - The requested error handler. Note: unlike releases prior to Saxon 9.6, this does not change the error listener used by the Configuration.

    - #### getErrorHandler

          public org.xml.sax.ErrorHandler getErrorHandler()

      Get the error handler in use
      Specified by:
        `getErrorHandler` in class `javax.xml.validation.SchemaFactory`
      Returns:
        the error handler previously registered using `setErrorHandler(org.xml.sax.ErrorHandler)` if available; otherwise null.

    - #### setResourceResolver

          public void setResourceResolver​(org.w3c.dom.ls.LSResourceResolver lsResourceResolver)

      Set a resolver to be used for dereferencing URIs encountered during schema processing and validation.
      Specified by:
        `setResourceResolver` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `lsResourceResolver` - The resolver to be used. This is wrapped in a URIResolver and registered with the Configuration, overwriting any URIResolver or SchemaURIResolver that was previously registered with the Configuration. Equally, any subsequent call on setURIResolver() or setSchemaURIResolver() on the Configuration object will replace the resolver registered using this method.

    - #### getResourceResolver

          public org.w3c.dom.ls.LSResourceResolver getResourceResolver()

      Get the resolver used for dereferencing URIs encountered during schema processing and validation.
      Specified by:
        `getResourceResolver` in class `javax.xml.validation.SchemaFactory`
      Returns:
        the resolver in use. If no resolver has been registered, or if the resolver registered with the Configuration is not a wrapped LSResourceResolver, return null.

    - #### newSchema

          public javax.xml.validation.Schema newSchema​(javax.xml.transform.Source[] sources)
                                                throws org.xml.sax.SAXException

      Parses the specified source(s) as a schema and returns it as a schema.

      The callee will read all the `Source`s and combine them into a single schema. The exact semantics of the combination depends on the schema language that this `SchemaFactory` object is created for.

      When an `ErrorHandler` is set, the callee will report all the errors found in sources to the handler. If the handler throws an exception, it will abort the schema compilation and the same exception will be thrown from this method. Also, after an error is reported to a handler, the callee is allowed to abort the further processing by throwing it. If an error handler is not set, the callee will throw the first error it finds in the sources.

      ## W3C XML Schema 1.0

      The resulting schema contains components from the specified sources. The same result would be achieved if all these sources were imported, using appropriate values for schemaLocation and namespace, into a single schema document with a different targetNamespace and no components of its own, if the import elements were given in the same order as the sources. Section 4.2.3 of the XML Schema recommendation describes the options processors have in this regard. While a processor should be consistent in its treatment of JAXP schema sources and XML Schema imports, the behaviour between JAXP-compliant parsers may vary; in particular, parsers may choose to ignore all but the first <import> for a given namespace, regardless of information provided in schemaLocation.

      If the parsed set of schemas includes error(s) as specified in the section 5.1 of the XML Schema spec, then the error must be reported to the `ErrorHandler`.

      ## RELAX NG

      The Saxon implementation does not support RELAX NG.

      Specified by:
        `newSchema` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `sources` - inputs to be parsed as schema documents. The Saxon implementation recognizes not only the standard `SAXSource`, `StreamSource`, and `DOMSource`, but also any implementation of `NodeInfo`
      Returns:
        Always return a non-null valid `Schema` object. Note that when an error has been reported, there is no guarantee that the returned `Schema` object is meaningful.
      Throws:
        `org.xml.sax.SAXException` - If an error is found during processing the specified inputs. When an `ErrorHandler` is set, errors are reported to there first. See `setErrorHandler(ErrorHandler)`. In the Saxon implementation, if a SAXException is thrown, it will always wrap an instance of `SchemaException`
        `java.lang.NullPointerException` - If the `schemas` parameter itself is null or any item in the array is null.
        `java.lang.IllegalArgumentException` - If any item in the array is not recognized by this method.

    - #### newSchema

          public javax.xml.validation.Schema newSchema()

      Returns the `Schema` object containing all the schema components that have been loaded using the `newSchema(javax.xml.transform.Source[])` method. If no schema components have been loaded, the schema can still be used to validate source documents provided that they specify the location of the required schema components using the xsi:schemaLocation attribute.

      The returned `Schema` object assumes that if documents refer to the same URL in the schema location hints, they will always resolve to the same schema document. This assumption allows implementations to reuse parsed results of schema documents so that multiple validations against the same schema will run faster.

      Note that the use of schema location hints introduces a vulnerability to denial-of-service attacks.

      Specified by:
        `newSchema` in class `javax.xml.validation.SchemaFactory`
      Returns:
        Always return a non-null valid `Schema` object.

    - #### getProperty

          public java.lang.Object getProperty​(java.lang.String name)
                                       throws org.xml.sax.SAXNotSupportedException

      Look up the value of a property.

      The property name is any fully-qualified URI. It is possible for a `SchemaFactory` to recognize a property name but temporarily be unable to return its value.

      `SchemaFactory`s are not required to recognize any specific property names.

      In the Saxon implementation, the property names that are recognized are the same as the attribute names recognised by a `TransformerFactory`. These are listed as constant fields in the class `FeatureKeys`

      Overrides:
        `getProperty` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `name` - The property name, which is a non-null fully-qualified URI.
      Returns:
        The current value of the property.
      Throws:
        `org.xml.sax.SAXNotSupportedException` - When the XMLReader recognizes the property name but cannot determine its value at this time.
        `java.lang.NullPointerException` - if the name parameter is null.
      See Also:
        `setProperty(String, Object)`

    - #### setProperty

          public void setProperty​(java.lang.String name,
                                  java.lang.Object object)
                           throws org.xml.sax.SAXNotRecognizedException,
                                  org.xml.sax.SAXNotSupportedException

      Set the value of a property.

      The property name is any fully-qualified URI. It is possible for a `SchemaFactory` to recognize a property name but to be unable to change the current value.

      In the Saxon implementation, the property names that are recognized are the same as the attribute names recognised by a `TransformerFactory`. These are listed as constant fields in the class `FeatureKeys`

      Overrides:
        `setProperty` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `name` - The property name, which is a non-null fully-qualified URI.
        `object` - The requested value for the property.
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - If the property value can't be assigned or retrieved.
        `org.xml.sax.SAXNotSupportedException` - When the `SchemaFactory` recognizes the property name but cannot set the requested value.
        `java.lang.NullPointerException` - if the name parameter is null.

    - #### getFeature

          public boolean getFeature​(java.lang.String name)
                             throws org.xml.sax.SAXNotRecognizedException,
                                    org.xml.sax.SAXNotSupportedException

      Look up the value of a feature flag.

      Saxon recognizes the feature name XMLConstants.FEATURE_SECURE_PROCESSING, and if this is requested, it returns the value of the Configuration property named as the concatenation of FeatureKeys.XML_PARSER_FEATURE + XMLConstants.FEATURE_SECURE_PROCESSING.

      In all other cases Saxon delegates to the superclass, which will generally result in a `SAXNotRecognizedException`.

      Overrides:
        `getFeature` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `name` - The feature name, which is a non-null fully-qualified URI.
      Returns:
        The current value of the feature (true or false).
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - If the feature value can't be assigned or retrieved.
        `org.xml.sax.SAXNotSupportedException` - When the `SchemaFactory` recognizes the feature name but cannot determine its value at this time.
        `java.lang.NullPointerException` - If `name` is `null`.
      See Also:
        `setFeature(String, boolean)`

    - #### setFeature

          public void setFeature​(java.lang.String name,
                                 boolean value)
                          throws org.xml.sax.SAXNotRecognizedException,
                                 org.xml.sax.SAXNotSupportedException

      Set a feature for this `SchemaFactory`.

      The call is delegated to the superclass except when the feature is `XMLConstants.FEATURE_SECURE_PROCESSING` feature. With this feature, the effect is to set the corresponding parser feature in the Configuration. (It thus affects all operations under the control of that Configuration, not only schema processing). Setting a parser feature in the Configuration affects all parsers created by that Configuration, but it does not affect the settings of a user-supplied parser, for example an XMLReader supplied within a SAXSource object.

      Note: in general, the way to set configuration options for Saxon is via the Configuration object, which can be obtained using the `getConfiguration()` method.

      Overrides:
        `setFeature` in class `javax.xml.validation.SchemaFactory`
      Parameters:
        `name` - The feature name, which is a non-null fully-qualified URI.
        `value` - The requested value of the feature (true or false).
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - If the feature value can't be assigned or retrieved.
        `org.xml.sax.SAXNotSupportedException` - When the `SchemaFactory` recognizes the feature name but cannot set the requested value.
        `java.lang.NullPointerException` - If `name` is `null`.
      See Also:
        `getFeature(String)`

    - #### getConfiguration

          public EnterpriseConfiguration getConfiguration()

      Get the underlying Saxon Configuration object
      Returns:
        the underlying Saxon Configuration object, which will always be an EnterpriseConfiguration