javax.xml.validation
类 SchemaFactory

java.lang.Object
  javax.xml.validation.SchemaFactory

public abstract class SchemaFactory
extends Object

创建 Schema 对象的工厂。验证 API 的入口点。

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

SchemaFactory 类不是线程安全的。换句话说，应用程序负责确保任意给定时刻至多只有一个线程使用 SchemaFactory 对象。鼓励实现将方法标记为 synchronized，以保护客户机不至于崩溃。

SchemaFactory 不是重入（re-entrant）方法。当正在调用某个 newSchema 方法时，应用程序不能试图以递归方式调用 newSchema 方法，甚至不能从相同线程调用该方法。

模式语言

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

要遵守此规范，实现只需支持 W3C XML 模式 1.0 即可。但是，如果实现选择支持其他模式语言，那么它必须遵守此规范中所描述的相关行为。

此处未列出的模式语言应引用它们自己的 URI 来表示它们本身。SchemaFactory 类能够在运行时定位其他模式语言的其他实现。

注意，因为 XML DTD 与解析过程有紧密联系，并对解析过程产生很大影响，因此不能将 DTD 验证定义为与解析无关的过程。出于此原因，此规范不定义 XML DTD 的语义。这并不限制实现者以他们了解的合适方式来实现它，但这里提醒用户，此接口上实现的任何 DTD 验证必然偏离 XML 1.0 中所定义的 XML DTD 语义。

从以下版本开始：

1.5

SchemaFactory

protected SchemaFactory()

派生类的构造方法。

构造方法不执行任何动作。

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

newInstance

public static final SchemaFactory newInstance(String schemaLanguage)

查找支持指定模式语言的 SchemaFactory 的实现并返回它。

为了查找给定模式语言的 SchemaFactory 对象，此方法按照以下顺序查找以下位置，其中“类加载器”指上下文类加载器：

1. 如果系统属性 "javax.xml.validation.SchemaFactory:schemaLanguage" 存在（其中 schemaLanguage 是此方法的参数），那么可以将它的值作为类名称来读取。该方法试图通过使用类加载器来创建此类的新实例，如果创建成功，则返回它。
2. 读取 $java.home/lib/jaxp.properties，并查找与作为系统属性的键关联的值。如果存在这样的值，则按上面的方式处理该值。

3. 类加载器要求服务提供者的提供者配置文件与资源目录 META-INF/services 中的 javax.xml.validation.SchemaFactory 匹配。参见文件格式和解析规则的 JAR File Specification。每个可能的服务提供者均要实现以下方法：

           isSchemaLanguageSupported(String schemaLanguage)
        

   返回支持指定模式语言的类加载器顺序中的第一个服务提供者。
4. 以特定于实现的方式来定位平台默认的 SchemaFactory。必须存在 W3C XML 模式的平台默认 SchemaFactory。

如果这些都失败，则将抛出 IllegalArgumentException。

疑难解答提示：

有关如何精确解析属性文件的信息，请参阅 Properties.load(java.io.InputStream)。尤其要指出的是，冒号 ':'在属性文件中需要转义，因此要确保模式语言 URI 在其中进行正确转义。例如：

 http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
 

参数：

schemaLanguage - 指定返回的 SchemaFactory 理解的模式语言。有关可能的值，请参阅 可用模式语言列表。

返回：

新的 SchemaFactory 实例

抛出：

IllegalArgumentException - 如果没有可用的模式语言实现。

NullPointerException - 如果 schemaLanguage 参数为 null。

另请参见：

newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

newInstance

public static SchemaFactory newInstance(String schemaLanguage,
                                        String factoryClassName,
                                        ClassLoader classLoader)

根据类名称获得一个新 SchemaFactory 实例。如果指定的工厂类支持指定的模式语言，则返回 SchemaFactory。当类路径中有多个提供者时此功能很有用。它给了应用程序更多的控制权，因为它能指定应该加载哪个提供者。

疑难解答提示

设置 jaxp.debug 系统属性将导致此方法将许多调试消息打印到 System.err，以说明它执行的操作以及在何处查找这些操作。

如有问题，请尝试：

 java -Djaxp.debug=1 YourProgram ....
 

参数：

schemaLanguage - 指定返回的 SchemaFactory 理解的模式语言。有关可能的值，请参阅 the list of available schema languages。

factoryClassName - 完全限定工厂类名称，提供 javax.xml.validation.SchemaFactory 的实现。

classLoader - 用来加载工厂类的 ClassLoader。如果为 null，则使用当前 Thread 的上下文 classLoader 来加载工厂类。

返回：

新的 SchemaFactory 实例

抛出：

IllegalArgumentException - 如果 factoryClassName 为 null、工厂类不能被加载或实例化、工厂类不支持 schemLanguage 参数中指定的模式语言。

NullPointerException - 如果 schemaLanguage 参数为 null。

从以下版本开始：

1.6

另请参见：

newInstance(String schemaLanguage)

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 - 功能名称，它是非 null 的完全限定 URI。

返回：

功能的当前值（true 或 false）。

抛出：

SAXNotRecognizedException - 如果不能分配或检索功能值。

SAXNotSupportedException - 当 SchemaFactory 可以识别功能名称但不能确定它此时的值时。

NullPointerException - 如果 name 为 null。

另请参见：

setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

设置此 SchemaFactory 的特性，Schema 由此工厂创建，更进一步说，Validator 和 ValidatorHandler 由这些 Schema 创建。

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

功能名称是任何完全限定的 URI。SchemaFactory 有可能公开功能值，但不能更改当前值。

所有实现必须支持 XMLConstants.FEATURE_SECURE_PROCESSING 功能。当功能为以下情况时：

• true：该实现将限制 XML 处理遵守实现限制。示例包括实体扩展限制和将使用大量资源的 XML 模式构造。如果由于安全原因 XML 处理受到限制，则将通过调用注册的 ErrorHandler.fatalError(SAXParseException exception) 来报告此情况。参见 setErrorHandler(ErrorHandler errorHandler)。
• false：实现将根据 XML 规范来处理 XML，而不管可能的实现限制。

参数：

name - 功能名称，它是非 null 的完全限定 URI。

value - 所请求的功能值（true 或 false）。

抛出：

SAXNotRecognizedException - 如果不能分配或检索功能值。

SAXNotSupportedException - 当 SchemaFactory 可以识别功能名称，但不能设置请求的值时。

NullPointerException - 如果 name 为 null。

另请参见：

getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

设置属性值。

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

SchemaFactory 无需识别设置任何特定的属性名称。

参数：

name - 属性名称，它是非 null 的完全限定 URI。

object - 所请求的属性值。

抛出：

SAXNotRecognizedException - 如果不能分配或检索属性值。

SAXNotSupportedException - 当 SchemaFactory 可以识别属性名称，但不能设置请求的值时。

NullPointerException - 如果 name 为 null。

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

查找属性值。

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

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

实现者可随意选择（鼓励）创建自己的属性，方法是使用在它们自己的 URI 上构建的名称。

参数：

name - 属性名称，它是非 null 的完全限定 URI。

返回：

属性的当前值。

抛出：

SAXNotRecognizedException - 如果不能分配或检索属性值。

SAXNotSupportedException - 当 XMLReader 可以识别属性名称，但不能确定它此时的值时。

NullPointerException - 如果 name 为 null。

另请参见：

setProperty(String, Object)

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 {
         // noop
     }
 }
 

当创建新 SchemaFactory 对象时，此字段在初始化时被设置为 null。不要 将此字段继承给从此 SchemaFactory 创建的 Schema、Validator 或 ValidatorHandler。

参数：

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

getErrorHandler

public abstract ErrorHandler getErrorHandler()

获取设置为此 SchemaFactory 的当前 ErrorHandler。

返回：

此方法返回通过 setErrorHandler(ErrorHandler) 方法设置的最后一个对象，如果自从创建此 SchemaFactory 以来一直未调用该方法，则返回 null。

另请参见：

setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)

设置 LSResourceResolver 以自定义解析模式时的资源解析。

在模式解析中，SchemaFactory 在需要查找外部资源时使用 LSResourceResolver，虽然“查找外部资源”的准确含义取决于每个模式语言。例如，对于 W3C XML Schema，这包括文件 <include>d 或 <import>ed，以及从模式文件引用的 DTD 等。

甚至正在解析 Schema 期间，应用程序也可以调用此方法。

当 LSResourceResolver 为 null 时，实现的行为就好像设置了以下 LSResourceResolver 一样：

 class DumbDOMResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {
         
         return null; // always return 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。

另请参见：

setErrorHandler(ErrorHandler)

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 - 表示模式的 File。

返回：

从解析 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 模式 1.0

得到的模式包含来自指定源的组件。如果使用合适的 schemaLocation 值和名称空间值将所有这些源导入具有不同 targetNamespace 且没有其自己组件的单个模式文档中，如果以与源相同的顺序给定导入元素，则将得到相同结果。XML 模式建议的第 4.2.3 节描述了处理器关于这方面的选项。当处理器应与其 JAXP 模式源和 XML 模式导入的处理一致时，JAXP 兼容的解析器之间的行为可能不同，特别是解析器可能选择忽略所有给定名称空间的 <import>（第一个除外），而不管 schemaLocation 中所提供的信息。

如果解析后的模式集包含 XML 模式规范第 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 模式 1.0

对于 XML 模式，此方法创建 Schema 对象，该对象通过使用文档中指定的位置提示来执行验证。

返回的 Schema 对象假定如果文档指向模式位置提示中的相同 URL，则它们将总是解析为相同的模式文档。此假定允许实现重用解析后的模式文档结果，以便相对于相同模式的多个验证可以更快地运行。

注意，模式位置提示的使用引入了恶意的拒绝服务攻击。

RELAX NG

RELAX NG 不支持此操作。

返回：

总返回非 null 的有效 Schema 对象。

抛出：

UnsupportedOperationException - 如果被调用者不支持此操作。

SAXException - 如果此操作受支持但由于某种原因而失败。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。