Module java.xml

Package javax.xml.validation

Class Validator

java.lang.Object

javax.xml.validation.Validator

       public abstract class Validator extends Object
      

用于根据Schema检查XML文档的处理器。

验证器对象不是线程安全的，也不是可重入的。换句话说，应用程序有责任确保一个Validator对象在任何给定时间内不会被多个线程使用，并且在调用validate方法时，应用程序不得递归调用validate方法。

自版本:

1.5

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
abstract ErrorHandler	getErrorHandler()	获取设置为此Validator的当前ErrorHandler。
boolean	getFeature(String name)	查找特性标志的值。
Object	getProperty(String name)	查找属性的值。
abstract LSResourceResolver	getResourceResolver()	获取设置为此Validator的当前LSResourceResolver。
abstract void	reset()	将此Validator重置为其原始配置。
abstract void	setErrorHandler(ErrorHandler errorHandler)	设置用于在调用validate方法时接收遇到的错误的ErrorHandler。
void	setFeature(String name, boolean value)	设置特性标志的值。
void	setProperty(String name, Object object)	设置属性的值。
abstract void	setResourceResolver(LSResourceResolver resourceResolver)	设置为在验证过程中自定义资源解析的LSResourceResolver。
void	validate(Source source)	验证指定的输入。
abstract void	validate(Source source, Result result)	验证指定的输入并将增强的验证结果发送到指定的输出。

Methods declared in class java.lang.Object

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

Constructor Details

Validator

             protected Validator()
            

派生类的构造函数。

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

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

Method Details

reset

             public abstract void reset()
            

将此Validator重置为其原始配置。

Validator被重置为使用Schema.newValidator()创建时的相同状态。reset()旨在允许重用现有的Validator，从而节省与创建新Validator相关的资源。

重置后的Validator不能保证具有相同的LSResourceResolver或ErrorHandler Object，例如Object.equals(Object obj)。但它保证具有功能上相等的LSResourceResolver和ErrorHandler。

validate

             public void validate(Source source) throws SAXException, IOException
            

验证指定的输入。

这只是一个方便方法，用于调用带有null result的validate(Source source, Result result)。

参数:

source - 要验证的XML。必须是XML文档或XML元素，不能为null。为了向后兼容，尝试验证除文档或元素之外的任何内容的结果取决于实现。实现必须识别和处理输入，或抛出IllegalArgumentException。

抛出:

IllegalArgumentException - 如果Source是实现无法验证的XML工件（例如处理指令）。

SAXException - 如果ErrorHandler抛出SAXException，或者发现致命错误且ErrorHandler正常返回。

IOException - 如果验证器正在处理SAXSource且基础的XMLReader抛出IOException。

NullPointerException - 如果source为null。

参见:

• validate(Source source, Result result)

validate

             public abstract void validate(Source source, Result result) throws SAXException, IOException
            

验证指定的输入并将增强的验证结果发送到指定的输出。

此方法对接受的Source/Result类型施加以下限制。

Source / Result 可接受的

	StreamSource	SAXSource	DOMSource	StAXSource
null	OK	OK	OK	OK
StreamResult	OK	IllegalArgumentException	IllegalArgumentException	IllegalArgumentException
SAXResult	IllegalArgumentException	OK	IllegalArgumentException	IllegalArgumentException
DOMResult	IllegalArgumentException	IllegalArgumentException	OK	IllegalArgumentException
StAXResult	IllegalArgumentException	IllegalArgumentException	IllegalArgumentException	OK

要将一个Source验证为另一种Result，请使用身份转换器（参见TransformerFactory.newTransformer()）。

在验证过程中发现的错误将发送到指定的ErrorHandler。

如果文档有效，或者如果文档包含一些错误但没有一个是致命错误且ErrorHandler没有抛出任何异常，则该方法将正常返回。

参数:

source - 要验证的XML。必须是XML文档或XML元素，不能为null。为了向后兼容，尝试验证除文档或元素之外的任何内容的结果取决于实现。实现必须识别和处理输入，或抛出IllegalArgumentException。

result - 接收（可能增强的）XML的Result对象。如果调用方对此不感兴趣，则此参数可以为null。请注意，当使用DOMResult时，验证器可能只是将相同的DOM节点从DOMSource传递给DOMResult（在这种情况下source.getNode()==result.getNode()），它可能复制整个DOM树，或者可能更改源给定的节点。

抛出:

IllegalArgumentException - 如果Result类型与Source类型不匹配，或者如果Source是实现无法验证的XML工件（例如处理指令）。

SAXException - 如果ErrorHandler抛出SAXException，或者发现致命错误且ErrorHandler正常返回。

IOException - 如果验证器正在处理SAXSource且基础的XMLReader抛出IOException。

NullPointerException - 如果source参数为null。

参见:

• validate(Source source)

setErrorHandler

             public abstract void setErrorHandler(ErrorHandler errorHandler)
            

设置ErrorHandler以接收在validate方法调用期间遇到的错误。

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

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

如果从ErrorHandler中抛出任何Throwable，则调用validate方法的调用者将抛出相同的Throwable对象。

Validator不允许在未先向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 {
         // 空操作
     }
 }
 

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

参数:

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

getErrorHandler

             public abstract ErrorHandler getErrorHandler()
            

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

返回:

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

另请参阅:

• setErrorHandler(ErrorHandler)

setResourceResolver

             public abstract void setResourceResolver(LSResourceResolver resourceResolver)
            

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

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

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

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

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

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

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

参数:

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

getResourceResolver

             public abstract LSResourceResolver getResourceResolver()
            

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

返回:

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

另请参阅:

• setErrorHandler(ErrorHandler)

getFeature

             public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException
            

查找特性标志的值。

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

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

参数:

name - 特性名称，非null完全限定的URI。

返回:

特性的当前值（true或false）。

抛出:

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

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

NullPointerException - 当名称参数为null时。

另请参阅:

• setFeature(String, boolean)

setFeature

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

设置特性标志的值。

特性可用于控制Validator解析模式的方式，尽管Validator不需要识别任何特定的特性名称。

特性名称是任何完全限定的URI。Validator可能会公开特性值，但可能无法更改当前值。某些特性值可能在特定上下文中是不可变的或仅在特定上下文中可变，例如在验证之前、期间或之后。

参数:

name - 特性名称，非null完全限定的URI。

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

抛出:

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

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

NullPointerException - 当名称参数为null时。

另请参阅:

• getFeature(String)

setProperty

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

设置属性的值。

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

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

• 在源文件或模式文件中访问外部DTD的访问受到 XMLConstants.ACCESS_EXTERNAL_DTD 属性指定的协议的限制。如果由于此属性的限制而在验证期间拒绝访问，则 SAXException 将由 validate(Source) 方法抛出。

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

参数:

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

object - 属性的请求值。

抛出:

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

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

NullPointerException - 当名称参数为null时。

getProperty

             public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException
            

查找属性的值。

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

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

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

参数:

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

返回:

属性的当前值。

抛出:

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

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

NullPointerException - 当名称参数为null时。

参见:

• setProperty(String, Object)