模块 java.xml

包 javax.xml.validation

类 SchemaFactory

java.lang.Object

javax.xml.validation.SchemaFactory

public abstract class SchemaFactory extends Object 
      

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

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

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

SchemaFactory 不可重入。在调用 newSchema 方法之一时，应用程序可能不会尝试递归调用 newSchema 方法，即使是从同一线程。

Schema 语言

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

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

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

请注意，由于 XML DTD 与解析过程紧密相关并且对解析过程有重大影响，因此不可能将 DTD 验证定义为独立于解析的过程。出于这个原因，本规范没有定义 XML DTD 的语义。这并不禁止实施者以他们认为合适的方式实施它，但是 users are warned that any DTD validation implemented on this interface necessarily deviate from the XML DTD semantics as defined in the XML 1.0 。

支持的模式语言的 URI

value	语言
XMLConstants.W3C_XML_SCHEMA_NS_URI （“http://www.w3.org/2001/XMLSchema”）	W3C XML 架构 1.0
XMLConstants.RELAXNG_NS_URI （“http://relaxng.org/ns/structure/1.0”）	RELAX NG 1.0

自从：

1.5

构造方法总结

构造方法

修饰符	构造方法	描述
protected	SchemaFactory()	派生类的构造方法。

方法总结

修饰符和类型	方法	描述
abstract ErrorHandler	getErrorHandler()	将当前的 ErrorHandler 设置为此 SchemaFactory 。
boolean	getFeature(String name)	查找功能标志的值。
Object	getProperty(String name)	查找属性的值。
abstract LSResourceResolver	getResourceResolver()	将当前的 LSResourceResolver 设置为此 SchemaFactory 。
abstract boolean	isSchemaLanguageSupported(String schemaLanguage)	这个 SchemaFactory 支持指定的架构吗？
static SchemaFactory	newDefaultInstance()	创建 SchemaFactory 内置系统默认实现的新实例。
static SchemaFactory	newInstance(String schemaLanguage)	获取支持指定模式语言的 SchemaFactory 的新实例。
static SchemaFactory	newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)	从类名中获取 SchemaFactory 的新实例。
abstract Schema	newSchema()	创建一个特殊的 Schema 对象。
Schema	newSchema(File schema)	将指定的 File 解析为模式并将其作为 Schema 返回。
Schema	newSchema(URL schema)	将指定的 URL 解析为架构并将其作为 Schema 返回。
Schema	newSchema(Source schema)	将指定的源解析为模式并将其作为模式返回。
abstract Schema	newSchema(Source[] schemas)	将指定的源解析为模式并将其作为模式返回。
abstract void	setErrorHandler(ErrorHandler errorHandler)	设置 ErrorHandler 以接收在 newSchema 方法调用期间遇到的错误。
void	setFeature(String name, boolean value)	为这个工厂创建的 SchemaFactory、Schema 以及由这些 Schema 创建的 Validator 和 ValidatorHandler 设置一个特性。
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 对象。

方法详情

newDefaultInstance

public static SchemaFactory  newDefaultInstance()
            

创建 SchemaFactory 内置系统默认实现的新实例。

实现要求：

SchemaFactory 内置系统默认实现只需要支持 W3C XML 架构 1.0 ，但可能支持额外的 图式语言 。

返回：

SchemaFactory 内置系统默认实现的新实例。

自从：

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 参数为空。

SchemaFactoryConfigurationError - 如果遇到配置错误。

参见：

• 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 将理解的模式语言。有关可能的值，请参阅 可用模式语言列表。

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

classLoader - ClassLoader 用于加载工厂类。如果使用nullcurrentThread的context classLoader加载工厂类。

返回：

SchemaFactory 的新实例

抛出：

IllegalArgumentException - 如果 factoryClassName 是 null ，或者无法加载、实例化工厂类或不支持 schemLanguage 参数中指定的模式语言。

NullPointerException - 如果 schemaLanguage 参数为空。

自从：

1.6

参见：

• newInstance(String schemaLanguage)

isSchemaLanguageSupported

public abstract boolean isSchemaLanguageSupported(String  schemaLanguage)
            

这个 SchemaFactory 支持指定的架构吗？

参数：

schemaLanguage - 指定返回的 SchemaFactory 将理解的模式语言。 schemaLanguage 必须指定 valid 模式语言。

返回：

true 如果 SchemaFactory 支持 schemaLanguage ，否则 false 。

抛出：

NullPointerException - 如果 schemaLanguage 是 null。

IllegalArgumentException - 如果 schemaLanguage.length() == 0 或 schemaLanguage 未指定 valid 模式语言。

getFeature

public boolean getFeature(String  name) throws SAXNotRecognizedException , SAXNotSupportedException 
            

查找功能标志的值。

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

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

参数：

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

返回：

特征的当前值（真或假）。

抛出：

SAXNotRecognizedException - 如果无法分配或检索特征值。

SAXNotSupportedException - 当 SchemaFactory 识别特征名称但此时无法确定其值时。

NullPointerException - 如果 name 是 null。

参见：

• setFeature(String, boolean)

setFeature

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

为这个工厂创建的 SchemaFactory、Schema 以及由这些 Schema 创建的 Validator 和 ValidatorHandler 设置一个特性。

实施者和开发者应特别注意 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 - 功能名称，它是一个非空的完全限定 URI。

value - 特征的请求值（真或假）。

抛出：

SAXNotRecognizedException - 如果无法分配或检索特征值。

SAXNotSupportedException - 当 SchemaFactory 识别功能名称但无法设置请求的值时。

NullPointerException - 如果 name 是 null。

参见：

• getFeature(String)

setProperty

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

设置属性的值。

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

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

• 访问架构文件中的外部 DTD 仅限于 XMLConstants.ACCESS_EXTERNAL_DTD 属性指定的协议。如果由于该属性的限制，在创建新 Schema 期间访问被拒绝，SAXException 将被 newSchema(Source) 或 newSchema(File) 或 newSchema(URL) 或 newSchema(Source[]) 方法抛出。

  对 xml 源文件中的外部 DTD 的访问仅限于 XMLConstants.ACCESS_EXTERNAL_DTD 属性指定的协议。如果由于此属性的限制而在验证期间拒绝访问，SAXException 将被 Validator.validate(Source) 或 Validator.validate(Source, Result) 方法抛出。

  对 schemaLocation 属性设置的外部引用的访问仅限于 XMLConstants.ACCESS_EXTERNAL_SCHEMA 属性指定的协议。如果由于此属性的限制而在验证期间拒绝访问，SAXException 将被 Validator.validate(Source) 或 Validator.validate(Source, Result) 方法抛出。

  对 Import 和 Include 元素设置的外部引用的访问仅限于 XMLConstants.ACCESS_EXTERNAL_SCHEMA 属性指定的协议。如果由于该属性的限制，在创建新 Schema 期间访问被拒绝，SAXException 将被 newSchema(Source) 或 newSchema(File) 或 newSchema(URL) 或 newSchema(Source[]) 方法抛出。

参数：

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。

参见：

• 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 对象时，最初此字段设置为空。该字段将 NOT 继承到由此 SchemaFactory 创建的 Schema s、Validator s 或 ValidatorHandler s。

参数：

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

getErrorHandler

public abstract ErrorHandler  getErrorHandler()
            

将当前的 ErrorHandler 设置为此 SchemaFactory 。

返回：

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

参见：

• setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver  resourceResolver)
            

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

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

即使在解析 Schema 期间，应用程序也可以调用此方法。

当 LSResourceResolver 为空时，实现的行为就像设置了以下 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 对象时，最初此字段设置为空。该字段将 NOT 继承到由此 SchemaFactory 创建的 Schema s、Validator s 或 ValidatorHandler s。

参数：

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

getResourceResolver

public abstract LSResourceResolver  getResourceResolver()
            

将当前的 LSResourceResolver 设置为此 SchemaFactory 。

返回：

此方法返回上次通过 setResourceResolver(LSResourceResolver) 方法设置的对象，如果自此 SchemaFactory 创建以来从未调用过该方法，则返回 null。

参见：

• setErrorHandler(ErrorHandler)

newSchema

public Schema  newSchema(Source  schema) throws SAXException 
            

将指定的源解析为模式并将其作为模式返回。

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

参数：

schema - 表示模式的源。

返回：

解析 schema 的新 Schema。

抛出：

SAXException - 如果在解析期间发生 SAX 错误。

NullPointerException - 如果 schema 为空。

newSchema

public Schema  newSchema(File  schema) throws SAXException 
            

将指定的 File 解析为模式并将其作为 Schema 返回。

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

参数：

schema - 表示架构的文件。

返回：

解析 schema 的新 Schema。

抛出：

SAXException - 如果在解析期间发生 SAX 错误。

NullPointerException - 如果 schema 为空。

newSchema

public Schema  newSchema(URL  schema) throws SAXException 
            

将指定的 URL 解析为架构并将其作为 Schema 返回。

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

参数：

schema - URL 代表模式。

返回：

解析 schema 的新 Schema。

抛出：

SAXException - 如果在解析期间发生 SAX 错误。

NullPointerException - 如果 schema 为空。

newSchema

public abstract Schema  newSchema(Source [] schemas) throws SAXException 
            

将指定的源解析为模式并将其作为模式返回。

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

设置 ErrorHandler 后，被调用方将向处理程序报告源中发现的所有错误。如果处理程序抛出异常，它将中止架构编译，并从此方法抛出相同的异常。此外，在向处理程序报告错误后，被调用方可以通过抛出它来中止进一步的处理。如果未设置错误处理程序，被调用方将抛出它在源中找到的第一个错误。

W3C XML 架构 1.0

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

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

RELAX NG

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

参数：

schemas - 要解析的输入。 SchemaFactory 需要识别 SAXSource 、StreamSource 、StAXSource 和 DOMSource 。输入架构必须是 XML 文档或 XML 元素，并且不能为空。为了向后兼容，传递除文档或元素之外的任何内容的结果都是依赖于实现的。实现必须要么识别并处理输入，要么抛出 IllegalArgumentException。

返回：

总是返回一个非空的有效 Schema 对象。请注意，当报告错误时，无法保证返回的 Schema 对象有意义。

抛出：

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

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

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 不支持此操作。

返回：

始终返回非空有效 Schema 对象。

抛出：

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

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