Module java.xml

Package javax.xml.validation

Class ValidatorHandler

java.lang.Object

javax.xml.validation.ValidatorHandler

所有已实现的接口:

ContentHandler

       public abstract class ValidatorHandler extends Object implements ContentHandler
      

在SAX流上工作的流验证器。

ValidatorHandler对象不是线程安全的，也不是可重入的。换句话说，应用程序有责任确保一个ValidatorHandler对象在任何给定时间内不会从多个线程中使用。

ValidatorHandler检查SAX事件是否遵循与关联的Schema中描述的一组约束，并且还可以修改SAX事件（例如通过添加默认值等）。

ValidatorHandler扩展自ContentHandler，但它以以下方式完善了底层的ContentHandler：

1. startElement/endElement事件必须接收非空的String作为uri、localName和qname，即使SAX允许其中一些为空。同样，用户指定的ContentHandler将为所有三个参数接收非空字符串。
2. 应用程序必须确保正确调用ValidatorHandler的ContentHandler.startPrefixMapping(String,String)和ContentHandler.endPrefixMapping(String)。同样，用户指定的ContentHandler将接收startPrefixMapping/endPrefixMapping事件。如果ValidatorHandler引入了额外的命名空间绑定，用户指定的ContentHandler将接收额外的startPrefixMapping/endPrefixMapping事件。
3. 用于ContentHandler.startElement(String,String,String,Attributes)方法的Attributes可能包含或不包含xmlns*属性。

ValidatorHandler在每次调用startDocument方法时会自动重置。

已识别的属性和特性

此规范定义了所有ValidatorHandler实现必须识别的以下特性。

http://xml.org/sax/features/namespace-prefixes

此特性控制ValidatorHandler如何引入原始SAX事件流中不存在的命名空间绑定。当此特性设置为true时，必须确保用户的ContentHandler将在Attributes对象中看到相应的xmlns*属性，该属性将在ContentHandler.startElement(String,String,String,Attributes)回调中添加。否则，xmlns*属性不得添加到传递给用户指定的ContentHandler的Attributes中。

（请注意，无论此开关如何，命名空间绑定始终通过用户指定的ContentHandler的ContentHandler.startPrefixMapping(String,String)和ContentHandler.endPrefixMapping(String)方法向应用程序通知。）

请注意，此特性默认设置为false。

自版本:

1.5

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ValidatorHandler()	派生类的构造函数。

Method Summary

Modifier and Type	Method	Description
abstract ContentHandler	getContentHandler()	获取接收增强验证结果的ContentHandler。
abstract ErrorHandler	getErrorHandler()	获取当前设置为此ValidatorHandler的ErrorHandler。
boolean	getFeature(String name)	查找特性标志的值。
Object	getProperty(String name)	查找属性的值。
abstract LSResourceResolver	getResourceResolver()	获取当前设置为此ValidatorHandler的LSResourceResolver。
abstract TypeInfoProvider	getTypeInfoProvider()	获取此ValidatorHandler的TypeInfoProvider实现。
abstract void	setContentHandler(ContentHandler receiver)	设置接收增强验证结果的ContentHandler。
abstract void	setErrorHandler(ErrorHandler errorHandler)	设置用于接收验证期间遇到的错误的ErrorHandler。
void	setFeature(String name, boolean value)	为此ValidatorHandler设置一个特性。
void	setProperty(String name, Object object)	设置属性的值。
abstract void	setResourceResolver(LSResourceResolver resourceResolver)	设置为此ValidatorHandler的LSResourceResolver以自定义资源解析。

Methods declared in class java.lang.Object

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

Methods declared in interface org.xml.sax.ContentHandler

characters, declaration, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping

Constructor Details

ValidatorHandler

             protected ValidatorHandler()
            

派生类的构造函数。

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

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

Method Details

setContentHandler

             public abstract void setContentHandler(ContentHandler receiver)
            

设置接收增强验证结果的ContentHandler。

当指定ContentHandler时，ValidatorHandler将作为过滤器工作，并基本上将传入的事件复制到指定的ContentHandler中。

在这样做时，ValidatorHandler可能会修改事件，例如通过添加默认属性。

ValidatorHandler可能会缓冲事件到一定程度，但为了允许解析器使用ValidatorHandler，必须满足以下要求。

1. 当在ValidatorHandler上调用ContentHandler.startElement(String, String, String, Attributes)、ContentHandler.endElement(String, String, String)、ContentHandler.startDocument()或ContentHandler.endDocument()时，必须在回调返回之前为相同事件调用用户指定的ContentHandler上的相同方法。
2. ValidatorHandler不得引入输入中不存在的新元素。
3. ValidatorHandler不得删除输入中存在的属性。

当指定的ContentHandler上的回调方法抛出异常时，必须从ValidatorHandler中抛出相同的异常对象。不应通知ErrorHandler此类异常。

此方法甚至可以在验证过程中间调用。

参数:

receiver - 一个ContentHandler或一个null值。

getContentHandler

             public abstract ContentHandler getContentHandler()
            

获取接收增强验证结果的ContentHandler。

返回：

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

另请参阅：

• setContentHandler(ContentHandler)

setErrorHandler

             public abstract void setErrorHandler(ErrorHandler errorHandler)
            

设置用于接收验证过程中遇到的错误的ErrorHandler。

错误处理程序可用于自定义验证过程中的错误处理过程。当设置了一个ErrorHandler时，在验证过程中发现的错误将首先发送到ErrorHandler。

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

如果从ErrorHandler中抛出任何Throwable，则相同的Throwable对象将被抛向调用堆栈的根部。

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

当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 {
         // 空操作
     }
 }
 

创建新的ValidatorHandler对象时，最初此字段设置为null。

参数：

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

getErrorHandler

             public abstract ErrorHandler getErrorHandler()
            

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

返回：

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

另请参阅：

• setErrorHandler(ErrorHandler)

setResourceResolver

             public abstract void setResourceResolver(LSResourceResolver resourceResolver)
            

设置用于在验证过程中自定义资源解析的LSResourceResolver。

ValidatorHandler在需要在验证期间定位外部资源时使用LSResourceResolver，尽管“定位外部资源”的确切含义取决于每种模式语言。

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

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

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

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

创建新的ValidatorHandler对象时，最初此字段设置为null。

参数：

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

getResourceResolver

             public abstract LSResourceResolver getResourceResolver()
            

获取设置为此ValidatorHandler的当前LSResourceResolver。

返回：

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

另请参阅：

• setErrorHandler(ErrorHandler)

getTypeInfoProvider

             public abstract TypeInfoProvider getTypeInfoProvider()
            

获取此ValidatorHandler的TypeInfoProvider实现。

获取的TypeInfoProvider可在解析期间查询，以访问验证器确定的类型信息。

某些模式语言不定义类型的概念，对于这些语言，可能不支持此方法。但是，为了符合此规范，W3C XML Schema 1.0的实现必须支持此操作。

返回：

如果验证器/模式语言不支持TypeInfo的概念，则返回null。否则返回非null有效的TypeInfoProvider。

getFeature

             public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException
            

查找功能标志的值。

功能名称是任何完全限定的URI。一个ValidatorHandler可能识别一个功能名称，但暂时无法返回其值。某些功能值可能仅在特定上下文中可用，例如在验证之前、期间或之后。

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

参数：

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

返回：

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

抛出：

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

SAXNotSupportedException - 当ValidatorHandler识别功能名称但目前无法确定其值时。

NullPointerException - 当name为null时。

另请参阅：

• setFeature(String, boolean)

setFeature

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

为这个ValidatorHandler设置一个特性。

特性可用于控制ValidatorHandler解析模式的方式。特性名称是任何完全限定的URI。一个SchemaFactory可能会公开一个特性值，但无法更改当前值。一些特性值可能是不可变的，或者只能在特定上下文中（例如验证之前、期间或之后）可变。

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

• true：实现将限制XML处理以符合实现限制。示例包括实体扩展限制和可能消耗大量资源的XML模式构造。如果出于安全原因限制XML处理，将通过调用注册的ErrorHandler.fatalError(SAXParseException exception)来报告。请参见setErrorHandler(ErrorHandler errorHandler)。
• false：实现将根据XML规范处理XML，而不考虑可能的实现限制。

参数:

name - 特性名称，必须是非空的完全限定URI。

value - 特性的请求值（true或false）。

抛出:

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

SAXNotSupportedException - 当ValidatorHandler识别特性名称但无法设置请求的值时。

NullPointerException - 当name为null时。

参见:

• getFeature(String)

setProperty

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

设置属性的值。

属性名称是任何完全限定的URI。一个ValidatorHandler可能会识别属性名称，但无法更改当前值。一些属性值可能是不可变的，或者只能在特定上下文中（例如验证之前、期间或之后）可变。

ValidatorHandler不需要识别设置任何特定属性名称。

参数:

name - 属性名称，必须是非空的完全限定URI。

object - 属性的请求值。

抛出:

SAXNotRecognizedException - 如果无法分配或检索属性值。

SAXNotSupportedException - 当ValidatorHandler识别属性名称但无法设置请求的值时。

NullPointerException - 当name为null时。

getProperty

             public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException
            

查找属性的值。

属性名称是任何完全限定的URI。一个ValidatorHandler可能会识别属性名称，但暂时无法返回其值。一些属性值可能仅在特定上下文中（例如验证之前、期间或之后）可用。

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

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

参数:

name - 属性名称，必须是非空的完全限定URI。

返回:

属性的当前值。

抛出:

SAXNotRecognizedException - 如果无法分配或检索属性值。

SAXNotSupportedException - 当XMLReader识别属性名称但目前无法确定其值时。

NullPointerException - 当name为null时。

参见:

• setProperty(String, Object)