JavaTM 2 Platform
Standard Ed. 5.0

javax.xml.validation
类 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. 即使 SAX 允许 urilocalNameqname 中的一些值为 null,startElement/endElement 事件也必须接收其非 null String。类似地,用户指定的 ContentHandler 将接收所有 3 个参数的非 null String。
  2. 应用程序必须确保正确调用 ValidatorHandlerContentHandler.startPrefixMapping(String,String)ContentHandler.endPrefixMapping(String)。类似地,用户指定的 ContentHandler 将接收 startPrefixMapping/endPrefixMapping 事件。如果 ValidatorHandler 引入了额外的名称空间绑定,则用户指定的 ContentHandler 将接收额外的 startPrefixMapping/endPrefixMapping 事件。
  3. ContentHandler.startElement(String,String,String,Attributes)Attributes 可以包括也可以不包括 xmlns* 属性。

每次调用 startDocument 方法时将自动重置 ValidatorHandler

识别的属性和功能

此规范定义了以下功能,所有 ValidatorHandler 实现必须识别这些功能。

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

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

(注意,无论功能如何切换,名称空间绑定总是通过用户所指定的 ContentHandlerContentHandler.startPrefixMapping(String,String)ContentHandler.endPrefixMapping(String) 方法通知应用程序。)

注意,此功能 影响 ValidatorHandler 接收 SAX 事件的方式。它仅更改其扩充 SAX 事件的方式。

此功能默认设置为 false

从以下版本开始:
1.5

构造方法摘要
protected ValidatorHandler()
          派生类的构造方法。
 
方法摘要
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()
          获取此 ValidatorHandlerTypeInfoProvider 实现。
abstract  void setContentHandler(ContentHandler receiver)
          设置 ContentHandler,它接收扩充的验证结果。
abstract  void setErrorHandler(ErrorHandler errorHandler)
          设置 ErrorHandler 以接收验证期间遇到的错误。
 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
 
从接口 org.xml.sax.ContentHandler 继承的方法
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping
 

构造方法详细信息

ValidatorHandler

protected ValidatorHandler()
派生类的构造方法。

构造方法不执行动作。

派生类必须创建具有 null ErrorHandlernull LSResourceResolverValidatorHandler 对象。

方法详细信息

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 {
         // noop
     }
 }
 

当创建新 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; // always return 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()
获取此 ValidatorHandlerTypeInfoProvider 实现。

在解析期间可以查询所获取的 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 - 当名称参数为 null 时。
另请参见:
setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
设置功能标志的值。

功能可用于控制 ValidatorHandler 解析模式的方式,虽然 ValidatorHandler 无需识别任何指定的属性名称。

功能名称是任何完全限定的 URI。ValidatorHandler 有可能公开功能值,但不能更改当前值。某些功能值可能只有在特定上下文中才是不可变的或可变的,例如在验证前、验证中或验证之后。

参数:
name - 功能名称,它是非 null 的完全限定 URI。
value - 所请求的功能值(true 或 false)。
抛出:
SAXNotRecognizedException - 如果不能分配或检索功能值。
SAXNotSupportedException - 当 ValidatorHandler 可以识别功能名称,但不能设置请求的值时。
NullPointerException - 当名称参数为 null 时。
另请参见:
getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
设置属性值。

属性名称是任何完全限定的 URI。ValidatorHandler 有可能识别属性名称,但不能更改当前值。某些属性值可能只有在特定上下文中才是不可变的或可变的,例如在验证前、验证中或验证之后。

ValidatorHandler 无需识别设置任何特定的属性名称。

参数:
name - 属性名称,它是非 null 的完全限定 URI。
object - 所请求的属性值。
抛出:
SAXNotRecognizedException - 如果不能分配或检索属性值。
SAXNotSupportedException - 当 ValidatorHandler 可以识别属性名称,但不能设置请求的值时。
NullPointerException - 当名称参数为 null 时。

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
查找属性值。

属性名称是任何完全限定的 URI。ValidatorHandler 有可能识别属性名称,但暂时不能返回其值。某些属性值可能只有在特定上下文中才能使用,例如在验证前、验证中或验证之后。

ValidatorHandler 无需识别任何指定的属性名称。

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

参数:
name - 属性名称,它是非 null 的完全限定 URI。
返回:
属性的当前值。
抛出:
SAXNotRecognizedException - 如果不能分配或检索属性值。
SAXNotSupportedException - 当 XMLReader 可以识别属性名称,但不能确定其此时的值时。
NullPointerException - 当名称参数为 null 时。
另请参见:
setProperty(String, Object)

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策