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 Schema 1.0 即可。但是，如果实现选择支持其他模式语言，则它必须遵守此规范中所描述的相关行为。

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

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

值	语言
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

构造方法摘要

protected

SchemaFactory() 派生类的构造方法。

方法摘要

abstract ErrorHandler	getErrorHandler() 获取设置为此 SchemaFactory 的当前 ErrorHandler。
boolean	getFeature(String name) 查找功能标志的值。
Object	getProperty(String name) 查找属性值。
abstract LSResourceResolver	getResourceResolver() 获取设置为此 SchemaFactory 的当前 LSResourceResolver。
abstract boolean	isSchemaLanguageSupported(String schemaLanguage) 此 SchemaFactory 支持指定的模式吗？
static SchemaFactory	newInstance(String schemaLanguage) 查找支持指定模式语言的 SchemaFactory 的实现并返回它。
abstract Schema	newSchema() 创建特殊的 Schema 对象。
Schema	newSchema(File schema) 解析作为模式的指定 File 并以 Schema 的形式返回它。
Schema	newSchema(Source schema) 解析作为模式的指定源并以模式形式返回它。
abstract Schema	newSchema(Source[] schemas) 解析作为模式的指定源（或多个源），并以模式形式返回它。
Schema	newSchema(URL schema) 解析作为模式的指定 URL 并以 Schema 形式返回它。
abstract void	setErrorHandler(ErrorHandler errorHandler) 设置 ErrorHandler 以接收在 newSchema 方法调用期间遇到的错误。
void	setFeature(String name, boolean value) 设置功能标志的值。
void	setProperty(String name, Object object) 设置属性值。
abstract void	setResourceResolver(LSResourceResolver resourceResolver) 设置 LSResourceResolver 以自定义解析模式时的资源解析。

从类 java.lang.Object 继承的方法

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

构造方法详细信息

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 Schema 的平台默认 SchemaFactory。

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

疑难解答提示：

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

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

参数：

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

返回：

新的 SchemaFactory 实例

抛出：

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

NullPointerException - 如果 schemLanguage 参数为 null。

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 - 如果名称参数为 null。

另请参见：

setFeature(String, boolean)

setFeature

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

设置功能标志的值。

功能可用于控制 SchemaFactory 解析模式的方法，虽然 SchemaFactory 无需识别任何特定的功能名称。

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

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

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

参数：

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

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

抛出：

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

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

NullPointerException - 如果名称参数为 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 - 如果名称参数为 null。

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

查找属性值。

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

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

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

参数：

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

返回：

属性的当前值。

抛出：

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

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

NullPointerException - 如果名称参数为 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 Schema 1.0

得到的模式包含来自指定源的组件。如果使用合适的 schemaLocation 值和名称空间值将所有这些源导入具有不同 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 和 DOMSource。

返回：

总返回非 null 的有效 Schema 对象。注意，当已报告错误后，不保证返回的 Schema 对象有意义。

抛出：

SAXException - 如果在处理指定输入期间发现错误。当设置 ErrorHandler 时，首先将错误报告到该处。参见 setErrorHandler(ErrorHandler)。

NullPointerException - 如果 schemas 参数本身为 null，或数组中的任何项为 null。

IllegalArgumentException - 如果此方法不识别数组中的任何项。

UnsupportedOperationException - 如果模式语言不支持此操作。

newSchema

public abstract Schema newSchema()
                          throws SAXException

创建特殊的 Schema 对象。

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

同样，允许实现使用特定于实现的属性/功能来更改此方法的语义。

W3C XML Schema 1.0

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

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

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

RELAX NG

RELAX NG 不支持此操作。

返回：

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

抛出：

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

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