Module java.xml
Package javax.xml.validation

Class SchemaFactory

java.lang.Object
javax.xml.validation.SchemaFactory
public abstract class SchemaFactory extends Object
工厂，用于创建Schema对象。验证API的入口点。

SchemaFactory是一个模式编译器。它读取模式的外部表示并为验证做准备。

SchemaFactory类不是线程安全的。换句话说，应用程序有责任确保在任何给定时刻最多只有一个线程在使用SchemaFactory对象。鼓励实现将方法标记为synchronized以保护自己免受错误客户端的影响。

SchemaFactory不可重入。在调用newSchema方法时，应用程序不得尝试从同一线程递归调用newSchema方法。

模式语言

此规范使用命名空间URI来指定模式语言。以下表格显示了此规范定义的值。

为了符合规范，实现只需要支持W3C XML Schema 1.0。但是，如果选择支持此处列出的其他模式语言，则必须符合本规范中描述的相关行为。

未在此处列出的模式语言预计会引入自己的URI来表示自己。在运行时，SchemaFactory类能够定位其他模式语言的其他实现。

请注意，因为XML DTD与解析过程紧密相关，并且对解析过程有重大影响，所以不可能将DTD验证定义为与解析过程无关的过程。因此，本规范不定义XML DTD的语义。这并不禁止实现者根据自己的看法实现它，但警告用户，此接口上实现的任何DTD验证必然偏离XML 1.0中定义的XML DTD语义。

支持的模式语言的URI
值 语言
XMLConstants.W3C_XML_SCHEMA_NS_URI ("http://www.w3.org/2001/XMLSchema") W3C XML Schema 1.0
XMLConstants.RELAXNG_NS_URI ("http://relaxng.org/ns/structure/1.0") RELAX NG 1.0
自1.5版本起：
1.5

  • Constructor Details

    • SchemaFactory

      protected SchemaFactory()
      派生类的构造函数。

      构造函数不执行任何操作。

      派生类必须创建具有null SchemaFactory对象和null ErrorHandler的对象。

  • Method Details

    • newDefaultInstance

      public static SchemaFactory newDefaultInstance()
      创建内置系统默认实现的SchemaFactory的新实例。
      实现要求：
      SchemaFactory内置系统默认实现只需要支持W3C XML Schema 1.0，但可以支持其他模式语言。
      返回：
      SchemaFactory内置系统默认实现的新实例。
      自9版本起：
      9

    • newInstance

      public static SchemaFactory newInstance(String schemaLanguage)
      获取支持指定模式语言的SchemaFactory的新实例。此方法使用JAXP查找机制来确定和加载支持指定模式语言的SchemaFactory实现。

      故障排除提示：

      查看Properties.load(java.io.InputStream)以了解属性文件的解析方式。特别是，在属性文件中冒号':'需要转义，因此确保模式语言URI在其中正确转义。例如：

       http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
      参数：
      schemaLanguage - 指定返回的SchemaFactory将理解的模式语言。请参阅可用模式语言列表以获取可能的值。
      返回：
      SchemaFactory的新实例
      抛出：
      IllegalArgumentException - 如果没有模式语言的实现可用。
      NullPointerException - 如果schemaLanguage参数为null。
      SchemaFactoryConfigurationError - 如果遇到配置错误。
      另请参阅：

    • newInstance

      public static SchemaFactory newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
      从类名获取SchemaFactory的新实例。如果指定的工厂类名支持指定的模式语言，则返回SchemaFactory。当类路径中存在多个提供程序时，此函数很有用。它为应用程序提供更多控制，因为可以指定应加载哪个提供程序。

      故障排除提示

      设置jaxp.debug系统属性将导致此方法向System.err打印大量关于其操作和查找位置的调试消息。

      如果遇到问题，请尝试：

       java -Djaxp.debug=1 YourProgram ....
      参数：
      schemaLanguage - 指定返回的SchemaFactory将理解的模式语言。请参阅可用模式语言列表以获取可能的值。
      factoryClassName - 提供javax.xml.validation.SchemaFactory实现的完全限定工厂类名。
      classLoader - 用于加载工厂类的ClassLoader。如果为null，则使用当前Thread的上下文类加载器来加载工厂类。
      返回：
      SchemaFactory的新实例
      抛出：
      IllegalArgumentException - 如果factoryClassName为null，或者无法加载、实例化工厂类，或者工厂类不支持schemLanguage参数中指定的模式语言。
      NullPointerException - 如果schemaLanguage参数为null。
      自1.6版本起：
      1.6
      另请参阅：

    • isSchemaLanguageSupported

      public abstract boolean isSchemaLanguageSupported(String schemaLanguage)
      此SchemaFactory是否支持指定的模式？
      参数:
      schemaLanguage - 指定返回的SchemaFactory将理解的模式语言。 schemaLanguage必须指定一个有效的模式语言。
      返回:
      如果SchemaFactory支持schemaLanguage，则返回true，否则返回false。
      抛出:
      NullPointerException - 如果schemaLanguage为null。
      IllegalArgumentException - 如果schemaLanguage.length() == 0或schemaLanguage未指定有效的模式语言。

    • getFeature

      public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException
      查找特性标志的值。

      特性名称是任何完全限定的URI。 SchemaFactory可能会识别特性名称，但暂时无法返回其值。

      实现者可以自由（并且鼓励）发明自己的特性，使用建立在其自己URI上的名称。

      参数:
      name - 特性名称，非空完全限定的URI。
      返回:
      特性的当前值（true或false）。
      抛出:
      SAXNotRecognizedException - 如果无法分配或检索特性值。
      SAXNotSupportedException - 当SchemaFactory识别特性名称但目前无法确定其值时。
      NullPointerException - 如果name为null。
      参见:

    • setFeature

      public void setFeature(String name, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException
      为此SchemaFactory设置特性，由此工厂创建的Schema，以及由此延伸的Validator和由这些Schema创建的ValidatorHandler。

      实现者和开发人员应特别注意如何处理由newSchema()返回的特殊Schema对象。 在某些情况下，例如，当SchemaFactory和实际加载模式的类来自不同的实现时，可能无法自动继承SchemaFactory特性。 开发人员应确保在两个地方明确设置特性，例如安全处理。

      特性名称是任何完全限定的URI。 SchemaFactory可能会公开特性值，但无法更改当前值。

      所有实现都必须支持XMLConstants.FEATURE_SECURE_PROCESSING特性。 当特性为：

      参数:
      name - 属性名称，非空完全限定的URI。
      value - 属性的请求值（true或false）。
      抛出:
      SAXNotRecognizedException - 如果无法分配或检索属性值。
      SAXNotSupportedException - 当SchemaFactory识别属性名称但无法设置请求的值时。
      NullPointerException - 如果name为null。
      参见:

    • setProperty

      public void setProperty(String name, Object object) throws SAXNotRecognizedException, SAXNotSupportedException
      设置属性的值。

      属性名称是任何完全限定的URI。 SchemaFactory可能会识别属性名称，但无法更改当前值。

      所有实现实现JAXP 1.5或更新版本都必须支持XMLConstants.ACCESS_EXTERNAL_DTD和XMLConstants.ACCESS_EXTERNAL_SCHEMA属性。

      参数:
      name - 属性名称，非空完全限定的URI。
      object - 属性的请求值。
      抛出:
      SAXNotRecognizedException - 如果无法分配或检索属性值。
      SAXNotSupportedException - 当SchemaFactory识别属性名称但无法设置请求的值时。
      NullPointerException - 如果name为null。

    • getProperty

      public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException
      查找属性的值。

      属性名称是任何完全限定的URI。 SchemaFactory可能会识别属性名称，但暂时无法返回其值。

      SchemaFactory不需要识别任何特定的属性名称。

      实现者可以自由（并且鼓励）发明自己的属性，使用建立在其自己URI上的名称。

      参数:
      name - 属性名称，必须是非空的完全限定URI。
      返回:
      属性的当前值。
      抛出:
      SAXNotRecognizedException - 如果无法分配或检索属性值。
      SAXNotSupportedException - 当XMLReader识别属性名称但此时无法确定其值时。
      NullPointerException - 如果name为null。
      参见:

    • setErrorHandler

      public abstract void setErrorHandler(ErrorHandler errorHandler)
      设置ErrorHandler以接收在调用newSchema方法时遇到的错误。

      错误处理程序可用于自定义模式解析过程中的错误处理。当设置了ErrorHandler时，在解析模式期间发现的错误将首先发送到ErrorHandler。

      错误处理程序可以通过从处理程序中抛出SAXException来立即中止模式的解析。或者例如，它可以将错误打印到屏幕并尝试通过从ErrorHandler中正常返回来继续处理。

      如果从ErrorHandler中抛出任何Throwable（或其派生类的实例），则调用newSchema方法的调用者将抛出相同的Throwable对象。

      SchemaFactory不允许在未先向ErrorHandler报告的情况下抛出SAXException。

      应用程序甚至可以在解析Schema时调用此方法。

      当ErrorHandler为null时，实现将表现为已设置以下ErrorHandler：

       class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // 空操作
     }
 }

      创建新的SchemaFactory对象时，最初此字段设置为null。此字段将不会被继承到从此SchemaFactory创建的Schema、Validator或ValidatorHandler。

      参数:
      errorHandler - 要设置的新错误处理程序。此参数可以为null。

    • getErrorHandler

      public abstract ErrorHandler getErrorHandler()
      获取设置为此SchemaFactory的当前ErrorHandler。
      返回:
      此方法返回通过setErrorHandler(ErrorHandler)方法最后设置的对象，如果自创建此SchemaFactory以来从未调用过该方法，则返回null。
      参见:

    • setResourceResolver

      public abstract void setResourceResolver(LSResourceResolver resourceResolver)
      设置LSResourceResolver以自定义解析模式时的资源解析。

      SchemaFactory在解析模式时需要定位外部资源时会使用LSResourceResolver，尽管"定位外部资源"的确切含义取决于每种模式语言。例如，对于W3C XML Schema，这包括从模式文件中<include>或<import>的文件，以及从DTD引用的文件等。

      应用程序甚至可以在解析Schema时调用此方法。

      当LSResourceResolver为null时，实现将表现为已设置以下LSResourceResolver：

       class DumbDOMResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {

         return null; // 总是返回null
     }
 }

      如果LSResourceResolver抛出RuntimeException（或其派生类的实例），则SchemaFactory将中止解析，并且调用newSchema方法的调用者将收到相同的RuntimeException。

      创建新的SchemaFactory对象时，最初此字段设置为null。此字段将不会被继承到从此SchemaFactory创建的Schema、Validator或ValidatorHandler。

      参数:
      resourceResolver - 要设置的新资源解析器。此参数可以为null。

    • getResourceResolver

      public abstract LSResourceResolver getResourceResolver()
      获取设置为此SchemaFactory的当前LSResourceResolver。
      返回:
      此方法返回通过setResourceResolver(LSResourceResolver)方法最后设置的对象，如果自创建此SchemaFactory以来从未调用过该方法，则返回null。
      参见:

    • newSchema

      public Schema newSchema(Source schema) throws SAXException
      解析指定的源作为模式并将其作为模式返回。

      这是newSchema(Source[] schemas)的便利方法。

      参数:
      schema - 表示模式的源。
      返回:
      从解析schema得到的新Schema。
      抛出:
      SAXException - 如果在解析过程中发生SAX错误。
      NullPointerException - 如果schema为null。

    • newSchema

      public Schema newSchema(File schema) throws SAXException
      解析指定的File作为模式并将其作为Schema返回。

      这是newSchema(Source schema)的便利方法。

      参数:
      schema - 表示模式的文件。
      返回:
      从解析schema得到的新Schema。
      抛出:
      SAXException - 如果在解析过程中发生SAX错误。
      NullPointerException - 如果schema为null。

    • newSchema

      public Schema newSchema(URL schema) throws SAXException
      解析指定的URL作为模式，并将其作为Schema返回。

      这是一个方便的方法，用于newSchema(Source schema)。

      参数：
      schema - 表示模式的URL。
      返回：
      通过解析schema创建的新Schema。
      抛出：
      SAXException - 如果在解析过程中发生SAX错误。
      NullPointerException - 如果schema为null。

    • newSchema

      public abstract Schema newSchema(Source[] schemas) throws SAXException
      解析指定的源作为模式，并将其作为模式返回。

      调用方将读取所有Source并将它们组合成单个模式。组合的确切语义取决于创建此SchemaFactory对象的模式语言。

      当设置了一个ErrorHandler时，调用方将向处理程序报告在源中找到的所有错误。如果处理程序抛出异常，它将中止模式编译，并从此方法中抛出相同的异常。此外，在向处理程序报告错误后，调用方允许通过抛出它来中止进一步处理。如果未设置错误处理程序，调用方将抛出在源中找到的第一个错误。

      W3C XML Schema 1.0

      生成的模式包含来自指定源的组件。如果所有这些源都被导入，使用适当的schemaLocation和namespace值导入到一个不同targetNamespace且没有自己组件的单个模式文档中，且如果导入元素按照源的顺序给出，则将实现相同的结果。XML Schema推荐中的第4.2.3节描述了处理器在这方面的选项。虽然处理器应该在处理JAXP模式源和XML Schema导入时保持一致，但JAXP兼容解析器之间的行为可能会有所不同；特别是，解析器可能选择忽略给定命名空间的除第一个<import>之外的所有内容，而不管schemaLocation中提供的信息。

      如果解析的模式集包含在XML Schema规范的第5.1节中指定的错误，则必须向ErrorHandler报告错误。

      RELAX NG

      对于RELAX NG，如果schemas.length!=1，此方法必须抛出UnsupportedOperationException。

      参数：
      schemas - 要解析的输入。SchemaFactory需要识别SAXSource、StreamSource、StAXSource和DOMSource。输入模式必须是XML文档或XML元素，不能为null。为了向后兼容，传递除文档或元素之外的任何内容的结果取决于实现。实现必须识别和处理输入，否则将抛出IllegalArgumentException。
      返回：
      始终返回一个非null的有效Schema对象。请注意，一旦报告了错误，就不能保证返回的Schema对象是有意义的。
      抛出：
      SAXException - 如果在处理指定输入时发现错误。当设置了一个ErrorHandler时，错误将首先报告给那里。请参阅setErrorHandler(ErrorHandler)。
      NullPointerException - 如果schemas参数本身为null或数组中的任何项为null。
      IllegalArgumentException - 如果数组中的任何项未被此方法识别。
      UnsupportedOperationException - 如果模式语言不支持此操作。

    • newSchema

      public abstract Schema newSchema() throws SAXException
      创建一个特殊的Schema对象。

      返回的Schema对象的确切语义取决于创建此SchemaFactory的模式语言。

      此外，实现允许使用特定于实现的属性/特性来改变此方法的语义。

      实现者和开发人员应特别注意设置在此SchemaFactory上的特性如何被此特殊的Schema处理。在某些情况下，例如，当SchemaFactory和实际加载模式的类来自不同的实现时，可能无法自动继承SchemaFactory特性。开发人员应确保在两个地方明确设置特性，例如安全处理。

      W3C XML Schema 1.0

      对于XML Schema，此方法创建一个通过文档中指定的位置提示执行验证的Schema对象。

      返回的Schema对象假定如果文档引用模式位置提示中的相同URL，则它们将始终解析为相同的模式文档。这种假设允许实现重用模式文档的解析结果，以便多次针对同一模式的验证运行更快。

      请注意，使用模式位置提示会引入拒绝服务攻击的漏洞。

      RELAX NG

      RELAX NG不支持此操作。

      返回：
      始终返回非null有效的Schema对象。
      抛出：
      UnsupportedOperationException - 如果调用方不支持此操作。
      SAXException - 如果支持此操作但由于某种原因失败。