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 方法之前在其 Validator、 Unmarshaller 或 Marshaller 上设置事件处理程序,则默认事件处理程序将接收遇到的所有错误或警告的通知。默认事件处理程序将使当前操作在遇到第一个错误或致命错误之后暂停(但将在接收警告后尝试继续完成操作)。
有三种处理解组、验证和编组期间遇到的事件的方式:
- 使用默认事件处理程序
- 如果没有通过 setEventHandler API 在 Validator、 Unmarshaller 或 Marshaller 上指定事件处理程序,则将使用默认事件处理程序。
- 实现和注册一个自定义事件处理程序
- 复杂事件处理的客户端应用程序可以实现 ValidationEventHandler 接口,并向 Unmarshaller 和/或 Validator 注册它。
- 使用
ValidationEventCollector
实用工具- 为了方便起见,可以提供特殊的事件处理程序,只收集执行解组、验证和编组操作期间创建的任何 ValidationEvent 对象,并将它们作为 java.util.Collection 返回给客户端应用程序。
验证和格式良好
验证事件的处理因为客户端应用程序配置方式的不同而各有不同,以便能够按前一节中描述的方式处理它们。但是,在某些情况下,JAXB 提供者指示无法再以可靠的方式检测和报告错误。在这些情况下,JAXB 提供者会将 ValidationEvent 的严重性设置为 FATAL_ERROR,以指示应该终止解组、验证或编组操作。默认事件处理程序和 ValidationEventCollector 实用工具类必须在收到致命错误通知后终止处理。提供自己的 ValidationEventHandler 的客户端应用程序也应该在收到致命错误通知后终止处理。如果不终止处理,则可能发生不可预料的行为。
当前没有任何需要 Validator 上的所有 JAXB 提供者都支持的属性。但是,一些提供者可能支持它们自己的特定于提供者的属性集。
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 开始 |
方法详细信息 |
---|
void setEventHandler(ValidationEventHandler handler) throws JAXBException
如果调用 validate
期间遇到任何验证错误,则 JAXB 提供者将调用验证事件处理程序。如果客户端应用程序没有在调用验证方法之前注册验证事件处理程序,那么验证事件将由默认事件处理程序处理,默认事件处理程序将在遇到第一个错误或致命错误之后终止验证操作。
调用带有 null 参数的此方法将导致 Validator 重新使用默认事件处理程序。
handler
- 验证事件处理程序
JAXBException
- 如果在设置事件处理程序期间遇到错误
ValidationEventHandler getEventHandler() throws JAXBException
JAXBException
- 如果在设置当前事件处理程序时遇到错误
boolean validate(Object subrootObj) throws JAXBException
客户端应用程序可以使用此方法在运行时根据需要来验证 Java 内容树。此方法可用于验证 Java 内容树的任意子树。全局约束检查不会作为此操作的一部分执行(即 ID/IDREF 约束)。
subrootObj
- 将从其所在位置开始执行验证的对象
JAXBException
- 如果验证期间发生任何预料不到的问题
ValidationException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Validator 无法验证以
subrootObj 为根的内容树
IllegalArgumentException
- 如果 subrootObj 参数为 null
boolean validateRoot(Object rootObj) throws JAXBException
客户端应用程序可以使用此方法在运行时根据需要来验证 Java 内容树。此方法用于验证整个 Java 内容树。全局约束检查将作为此操作的一部分执行(即 ID/IDREF 约束)。
rootObj
- 将从其所在位置开始执行验证的根对象
JAXBException
- 如果验证期间发生任何不可预料的问题
ValidationException
- 如果
ValidationEventHandler
从其
handleEvent 方法返回 false 或者
Validator 无法验证以
rootObj 为根的内容树
IllegalArgumentException
- 如果 rootObj 参数为 null
void setProperty(String name, Object value) throws PropertyException
name
- 要设置的属性的名称。此值可以使用一个常量字段来指定,也可以是用户提供的字符串。
value
- 要设置的属性值
PropertyException
- 如果处理给定属性或值时发生错误
IllegalArgumentException
- 如果 name 参数为 null
Object getProperty(String name) throws PropertyException
name
- 将检索的属性的名称
PropertyException
- 如果检索给定属性或值属性名称时发生错误
IllegalArgumentException
- 如果 name 参数为 null