java.lang.Object javax.xml.validation.SchemaFactory
public abstract class SchemaFactory
创建 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 语义。
值 | 语言 |
---|---|
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 |
构造方法摘要 | |
---|---|
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 的实现并返回它。 |
static SchemaFactory |
newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader) 根据类名称获得一个新 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) 设置此 SchemaFactory 的特性,Schema 由此工厂创建,更进一步说,Validator 和 ValidatorHandler 由这些 Schema 创建。 |
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 |
构造方法详细信息 |
---|
protected SchemaFactory()
派生类的构造方法。
构造方法不执行任何动作。
派生类必须创建具有 null
ErrorHandler
和 null
LSResourceResolver
的 SchemaFactory
对象。
方法详细信息 |
---|
public static final SchemaFactory newInstance(String schemaLanguage)
查找支持指定模式语言的 SchemaFactory
的实现并返回它。
为了查找给定模式语言的 SchemaFactory
对象,此方法按照以下顺序查找以下位置,其中“类加载器”指上下文类加载器:
"javax.xml.validation.SchemaFactory:schemaLanguage"
存在(其中 schemaLanguage 是此方法的参数),那么可以将它的值作为类名称来读取。该方法试图通过使用类加载器来创建此类的新实例,如果创建成功,则返回它。 $java.home/lib/jaxp.properties
,并查找与作为系统属性的键关联的值。如果存在这样的值,则按上面的方式处理该值。 类加载器要求服务提供者的提供者配置文件与资源目录 META-INF/services 中的 javax.xml.validation.SchemaFactory
匹配。参见文件格式和解析规则的 JAR File Specification。每个可能的服务提供者均要实现以下方法:
isSchemaLanguageSupported(String schemaLanguage)
返回支持指定模式语言的类加载器顺序中的第一个服务提供者。 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)
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。
newInstance(String schemaLanguage)
public abstract boolean isSchemaLanguageSupported(String schemaLanguage)
此 SchemaFactory
支持指定的模式吗?
schemaLanguage
- 指定返回的
SchemaFactory
理解的模式语言。
schemaLanguage
必须指定
有效的模式语言。
SchemaFactory
支持
schemaLanguage
,则返回
true
,否则返回
false
。
NullPointerException
- 如果
schemaLanguage
为
null
。
IllegalArgumentException
- 如果
schemaLanguage.length() == 0
或
schemaLanguage
未指定
有效的模式语言。
public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException
功能名称是任何完全限定的 URI。SchemaFactory
有可能识别功能名称,但暂时不能返回其值。
实现者可随意选择(鼓励)创建自己的功能,方法是使用在它们自己的 URI 上构建的名称。
name
- 功能名称,它是非 null 的完全限定 URI。
SAXNotRecognizedException
- 如果不能分配或检索功能值。
SAXNotSupportedException
- 当
SchemaFactory
可以识别功能名称但不能确定它此时的值时。
NullPointerException
- 如果
name
为
null
。
setFeature(String, boolean)
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)
public void setProperty(String name, Object object) throws SAXNotRecognizedException, SAXNotSupportedException
属性名称是任何完全限定的 URI。SchemaFactory
有可能识别属性名称,但不能更改当前值。
SchemaFactory
无需识别设置任何特定的属性名称。
name
- 属性名称,它是非 null 的完全限定 URI。
object
- 所请求的属性值。
SAXNotRecognizedException
- 如果不能分配或检索属性值。
SAXNotSupportedException
- 当
SchemaFactory
可以识别属性名称,但不能设置请求的值时。
NullPointerException
- 如果
name
为
null
。
public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException
属性名称是任何完全限定的 URI。SchemaFactory
有可能识别属性名称,但暂时不能返回其值。
SchemaFactory
无需识别任何特定的属性名称。
实现者可随意选择(鼓励)创建自己的属性,方法是使用在它们自己的 URI 上构建的名称。
name
- 属性名称,它是非 null 的完全限定 URI。
SAXNotRecognizedException
- 如果不能分配或检索属性值。
SAXNotSupportedException
- 当 XMLReader 可以识别属性名称,但不能确定它此时的值时。
NullPointerException
- 如果
name
为
null
。
setProperty(String, Object)
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 implementsErrorHandler
{ public void fatalError(SAXParseException
e ) throwsSAXException
{ throw e; } public void error(SAXParseException
e ) throwsSAXException
{ throw e; } public void warning(SAXParseException
e ) throwsSAXException
{ // noop } }
当创建新 SchemaFactory
对象时,此字段在初始化时被设置为 null。不要 将此字段继承给从此 SchemaFactory
创建的 Schema
、Validator
或 ValidatorHandler
。
errorHandler
- 要设置的新错误处理程序。此参数可以为
null
。
public abstract ErrorHandler getErrorHandler()
SchemaFactory
的当前
ErrorHandler
。
setErrorHandler(ErrorHandler)
方法设置的最后一个对象,如果自从创建此
SchemaFactory
以来一直未调用该方法,则返回 null。
setErrorHandler(ErrorHandler)
public abstract void setResourceResolver(LSResourceResolver resourceResolver)
LSResourceResolver
以自定义解析模式时的资源解析。
在模式解析中,SchemaFactory
在需要查找外部资源时使用 LSResourceResolver
,虽然“查找外部资源”的准确含义取决于每个模式语言。例如,对于 W3C XML Schema,这包括文件 <include>
d 或 <import>
ed,以及从模式文件引用的 DTD 等。
甚至正在解析 Schema
期间,应用程序也可以调用此方法。
当 LSResourceResolver
为 null 时,实现的行为就好像设置了以下 LSResourceResolver
一样:
class DumbDOMResourceResolver implementsLSResourceResolver
{ publicLSInput
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。
public abstract LSResourceResolver getResourceResolver()
SchemaFactory
的当前
LSResourceResolver
。
setResourceResolver(LSResourceResolver)
方法设置的最后一个对象,如果自从创建此
SchemaFactory
以来一直未调用该方法,则返回 null。
setErrorHandler(ErrorHandler)
public Schema newSchema(Source schema) throws SAXException
解析作为模式的指定源并以模式形式返回它。
这是一个针对 newSchema(Source[] schemas)
的便捷方法。
schema
- 表示模式的源。
schema
得到的新
Schema
。
SAXException
- 如果解析期间发生 SAX 错误。
NullPointerException
- 如果
schema
为 null。
public Schema newSchema(File schema) throws SAXException
解析作为模式的指定 File
并以 Schema
的形式返回它。
这是一个针对 newSchema(Source schema)
的便捷方法。
schema
- 表示模式的 File。
schema
得到的新
Schema
。
SAXException
- 如果解析期间发生 SAX 错误。
NullPointerException
- 如果
schema
为 null。
public Schema newSchema(URL schema) throws SAXException
解析作为模式的指定 URL
并以 Schema
形式返回它。
这是一个针对 newSchema(Source schema)
的便捷方法。
schema
- 表示模式的
URL
。
schema
得到的新
Schema
。
SAXException
- 如果解析期间发生 SAX 错误。
NullPointerException
- 如果
schema
为 null。
public abstract Schema newSchema(Source[] schemas) throws SAXException
被调用者将读取所有 Source
并将它们组合到一个模式中。组合的精确语义取决于此 SchemaFactory
对象为其创建的模式语言。
当设置 ErrorHandler
时,被调用者将向处理程序报告源中发现的所有错误。如果处理程序执行异常,则它将中止模式组合,且将从此方法抛出相同的异常。同样,向处理程序报告错误后,允许被调用者通过抛出该错误来中止下一步处理。如果未设置错误处理程序,则被调用者将抛出在源中发现的第一个错误。
得到的模式包含来自指定源的组件。如果使用合适的 schemaLocation 值和名称空间值将所有这些源导入具有不同 targetNamespace 且没有其自己组件的单个模式文档中,如果以与源相同的顺序给定导入元素,则将得到相同结果。XML 模式建议的第 4.2.3 节描述了处理器关于这方面的选项。当处理器应与其 JAXP 模式源和 XML 模式导入的处理一致时,JAXP 兼容的解析器之间的行为可能不同,特别是解析器可能选择忽略所有给定名称空间的 <import>(第一个除外),而不管 schemaLocation 中所提供的信息。
如果解析后的模式集包含 XML 模式规范第 5.1 节指定的错误(或多个错误),则必须将错误报告给 ErrorHandler
。
对于 RELAX NG,如果 schemas.length!=1
,则此方法必须抛出 UnsupportedOperationException
。
schemas
- 要解析的输入。
SchemaFactory
必须识别
SAXSource
、
StreamSource
、
StAXSource
和
DOMSource
。输入模式必须是 XML 文档或 XML 元素,并且不得为 null。为了向后兼容,传递文档或元素以外的任何内容的所得结果都由实现决定。实现必须能识别并处理输入,否则将抛出 IllegalArgumentException。
Schema
对象。注意,当已报告错误后,不保证返回的
Schema
对象有意义。
SAXException
- 如果在处理指定输入期间发现错误。当设置
ErrorHandler
时,首先将错误报告到该处。参见
setErrorHandler(ErrorHandler)
。
NullPointerException
- 如果
schemas
参数本身为 null,或数组中的任何项为 null。
IllegalArgumentException
- 如果此方法不识别数组中的任何项。
UnsupportedOperationException
- 如果模式语言不支持此操作。
public abstract Schema newSchema() throws SAXException
Schema
对象。
返回的 Schema
对象的精确语义取决于此 SchemaFactory
为其创建的模式语言。
同样,允许实现使用特定于实现的属性/功能来更改此方法的语义。
实现者和开发人员应该特别注意此 SchemaFactory
上设置的特性是如何由此特殊 Schema
对象处理的。在某些情况下,例如,当 SchemaFactory
和类实际上加载来自不同实现的模式时,SchemaFactory
特性将无法自动继承。开发人员应该确保在两个地方都显式地设置了特性(如安全处理)。
对于 XML 模式,此方法创建 Schema
对象,该对象通过使用文档中指定的位置提示来执行验证。
返回的 Schema
对象假定如果文档指向模式位置提示中的相同 URL,则它们将总是解析为相同的模式文档。此假定允许实现重用解析后的模式文档结果,以便相对于相同模式的多个验证可以更快地运行。
注意,模式位置提示的使用引入了恶意的拒绝服务攻击。
RELAX NG 不支持此操作。
Schema
对象。
UnsupportedOperationException
- 如果被调用者不支持此操作。
SAXException
- 如果此操作受支持但由于某种原因而失败。