JavaTM Platform
Standard Ed. 6

javax.xml.bind
接口 Validator


已过时。 从 JAXB 2.0 开始

public interface Validator

自 JAXB 2.0 开始,此类已过时,成为一个可选项。

Validator 类负责控制运行时期间对内容树的验证。

三种形式的验证

解组时验证
这种形式的验证使客户端应用程序能够接收关于将 XML 数据解组到 Java 内容树中时检测到的验证错误和警告的信息,并且与其他类型的验证完全没有关系。要启用或禁用它,请参阅 Unmarshaller.setValidating 的 javadoc。所有 JAXB 1.0 提供者都必须支持此操作。
按需验证
这种形式的验证使客户端应用程序能够接收关于在 Java 内容树中检测到的验证错误和警告的信息。客户端应用程序在任何点上都可以在 Java 内容树(或其任意子树)上调用 Validator.validate 方法。所有 JAXB 1.0 提供这都必须支持此操作。
快速失败验证
当对 Java 内容树所做的修改违反规范中定义的 Java 属性的类型约束时,这种形式的验证使客户端应用程序能够接收关于这些修改的即时反馈。JAXB 提供者不需要支持这种类型的验证。在不支持这种类型的验证的 JAXB 提供者中,一些提供者可能要求在模式编译时确定是否允许客户端应用程序在运行时请求进行快速失败验证。

Validator 类负责管理按需验证。Unmarshaller 类负责管理解组操作期间的解组时验证。虽然没有在编组操作期间启用验证的正式方法,但 Marshaller 可以检测错误,并将这些错误报告给已在它自身上注册的 ValidationEventHandler

使用默认事件处理程序

如果客户端应用程序没有在调用 validate、unmarshal 或 marshal 方法之前在其 ValidatorUnmarshallerMarshaller 上设置事件处理程序,则默认事件处理程序将接收遇到的所有错误或警告的通知。默认事件处理程序将使当前操作在遇到第一个错误或致命错误之后暂停(但将在接收警告后尝试继续完成操作)。

处理验证事件

有三种处理解组、验证和编组期间遇到的事件的方式:
使用默认事件处理程序
如果没有通过 setEventHandler API 在 ValidatorUnmarshallerMarshaller 上指定事件处理程序,则将使用默认事件处理程序。
实现和注册一个自定义事件处理程序
复杂事件处理的客户端应用程序可以实现 ValidationEventHandler 接口,并向 Unmarshaller 和/或 Validator 注册它。
使用 ValidationEventCollector 实用工具
为了方便起见,可以提供特殊的事件处理程序,只收集执行解组、验证和编组操作期间创建的任何 ValidationEvent 对象,并将它们作为 java.util.Collection 返回给客户端应用程序。

验证和格式良好

验证事件的处理因为客户端应用程序配置方式的不同而各有不同,以便能够按前一节中描述的方式处理它们。但是,在某些情况下,JAXB 提供者指示无法再以可靠的方式检测和报告错误。在这些情况下,JAXB 提供者会将 ValidationEvent 的严重性设置为 FATAL_ERROR,以指示应该终止解组、验证或编组操作。默认事件处理程序和 ValidationEventCollector 实用工具类必须在收到致命错误通知后终止处理。提供自己的 ValidationEventHandler 的客户端应用程序也应该在收到致命错误通知后终止处理。如果不终止处理,则可能发生不可预料的行为。

支持的属性

当前没有任何需要 Validator 上的所有 JAXB 提供者都支持的属性。但是,一些提供者可能支持它们自己的特定于提供者的属性集。

从以下版本开始:
JAXB1.0
另请参见:
JAXBContext, Unmarshaller, ValidationEventHandler, ValidationEvent, ValidationEventCollector

方法摘要
 ValidationEventHandler getEventHandler()
          已过时。 从 JAXB2.0 开始
 Object getProperty(String name)
          已过时。 从 JAXB2.0 开始
 void setEventHandler(ValidationEventHandler handler)
          已过时。 从 JAXB2.0 开始
 void setProperty(String name, Object value)
          已过时。 从 JAXB2.0 开始
 boolean validate(Object subrootObj)
          已过时。 从 JAXB2.0 开始
 boolean validateRoot(Object rootObj)
          已过时。 从 JAXB2.0 开始
 

方法详细信息

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
已过时。 从 JAXB2.0 开始

允许应用程序注册一个验证事件处理程序。

如果调用 validate 期间遇到任何验证错误,则 JAXB 提供者将调用验证事件处理程序。如果客户端应用程序没有在调用验证方法之前注册验证事件处理程序,那么验证事件将由默认事件处理程序处理,默认事件处理程序将在遇到第一个错误或致命错误之后终止验证操作。

调用带有 null 参数的此方法将导致 Validator 重新使用默认事件处理程序。

参数:
handler - 验证事件处理程序
抛出:
JAXBException - 如果在设置事件处理程序期间遇到错误

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
已过时。 从 JAXB2.0 开始

返回当前的事件处理程序,如果没有设置事件处理程序,则返回默认事件处理程序。

返回:
当前的 ValidationEventHandler,如果没有设置该处理程序,则返回默认事件处理程序
抛出:
JAXBException - 如果在设置当前事件处理程序时遇到错误

validate

boolean validate(Object subrootObj)
                 throws JAXBException
已过时。 从 JAXB2.0 开始

subrootObj 开始验证 Java 内容树。

客户端应用程序可以使用此方法在运行时根据需要来验证 Java 内容树。此方法可用于验证 Java 内容树的任意子树。全局约束检查不会作为此操作的一部分执行(即 ID/IDREF 约束)。

参数:
subrootObj - 将从其所在位置开始执行验证的对象
返回:
如果以 subrootObj 为根的子树有效,则返回 true;否则返回 false
抛出:
JAXBException - 如果验证期间发生任何预料不到的问题
ValidationException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Validator 无法验证以 subrootObj 为根的内容树
IllegalArgumentException - 如果 subrootObj 参数为 null

validateRoot

boolean validateRoot(Object rootObj)
                     throws JAXBException
已过时。 从 JAXB2.0 开始

验证以 rootObj 为根的 Java 内容树。

客户端应用程序可以使用此方法在运行时根据需要来验证 Java 内容树。此方法用于验证整个 Java 内容树。全局约束检查作为此操作的一部分执行(即 ID/IDREF 约束)。

参数:
rootObj - 将从其所在位置开始执行验证的根对象
返回:
如果以 rootObj 为根的树有效,则返回 true;否则返回 false
抛出:
JAXBException - 如果验证期间发生任何不可预料的问题
ValidationException - 如果 ValidationEventHandler 从其 handleEvent 方法返回 false 或者 Validator 无法验证以 rootObj 为根的内容树
IllegalArgumentException - 如果 rootObj 参数为 null

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
已过时。 从 JAXB2.0 开始

设置 Validator 底层实现中的特定属性。此方法只能用于设置上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图设置未定义的属性将导致抛出 PropertyException。请参阅支持的属性

参数:
name - 要设置的属性的名称。此值可以使用一个常量字段来指定,也可以是用户提供的字符串。
value - 要设置的属性值
抛出:
PropertyException - 如果处理给定属性或值时发生错误
IllegalArgumentException - 如果 name 参数为 null

getProperty

Object getProperty(String name)
                   throws PropertyException
已过时。 从 JAXB2.0 开始

获取 Validator 底层实现中的特定属性。此方法只可用于获取上文中标准 JAXB 定义的属性之一或特定于提供者的属性。试图获取未定义的属性将导致抛出 PropertyException。请参阅支持的属性

参数:
name - 将检索的属性的名称
返回:
所请求属性的值
抛出:
PropertyException - 如果检索给定属性或值属性名称时发生错误
IllegalArgumentException - 如果 name 参数为 null

JavaTM Platform
Standard Ed. 6

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

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