Validator (Java EE 5)

该 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 提供者都支持的属性。但是，一些提供者可能支持它们自己的特定于提供者的属性集。

public interface Validator

As of JAXB 2.0, this class is deprecated and optional.

The Validator class is responsible for controlling the validation of content trees during runtime.

Three Forms of Validation

Unmarshal-Time Validation

This form of validation enables a client application to receive information about validation errors and warnings detected while unmarshalling XML data into a Java content tree and is completely orthogonal to the other types of validation. To enable or disable it, see the javadoc for Unmarshaller.setValidating. All JAXB 1.0 Providers are required to support this operation.

On-Demand Validation

This form of validation enables a client application to receive information about validation errors and warnings detected in the Java content tree. At any point, client applications can call the Validator.validate method on the Java content tree (or any sub-tree of it). All JAXB 1.0 Providers are required to support this operation.

Fail-Fast Validation

This form of validation enables a client application to receive immediate feedback about modifications to the Java content tree that violate type constraints on Java Properties as defined in the specification. JAXB Providers are not required support this type of validation. Of the JAXB Providers that do support this type of validation, some may require you to decide at schema compile time whether or not a client application will be allowed to request fail-fast validation at runtime.

The Validator class is responsible for managing On-Demand Validation. The Unmarshaller class is responsible for managing Unmarshal-Time Validation during the unmarshal operations. Although there is no formal method of enabling validation during the marshal operations, the Marshaller may detect errors, which will be reported to the ValidationEventHandler registered on it.

Using the Default EventHandler

If the client application does not set an event handler on their Validator, Unmarshaller, or Marshaller prior to calling the validate, unmarshal, or marshal methods, then a default event handler will receive notification of any errors or warnings encountered. The default event handler will cause the current operation to halt after encountering the first error or fatal error (but will attempt to continue after receiving warnings).

Handling Validation Events

There are three ways to handle events encountered during the unmarshal, validate, and marshal operations:

Use the default event handler

The default event handler will be used if you do not specify one via the setEventHandler API's on Validator, Unmarshaller, or Marshaller.

Implement and register a custom event handler

Client applications that require sophisticated event processing can implement the ValidationEventHandler interface and register it with the Unmarshaller and/or Validator.

Use the ValidationEventCollector utility

For convenience, a specialized event handler is provided that simply collects any ValidationEvent objects created during the unmarshal, validate, and marshal operations and returns them to the client application as a java.util.Collection.

Validation and Well-Formedness

Validation events are handled differently depending on how the client application is configured to process them as described in the previous section. However, there are certain cases where a JAXB Provider indicates that it is no longer able to reliably detect and report errors. In these cases, the JAXB Provider will set the severity of the ValidationEvent to FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations should be terminated. The default event handler and ValidationEventCollector utility class must terminate processing after being notified of a fatal error. Client applications that supply their own ValidationEventHandler should also terminate processing after being notified of a fatal error. If not, unexpected behaviour may occur.

Supported Properties

There currently are not any properties required to be supported by all JAXB Providers on Validator. However, some providers may support their own set of provider specific properties.

Since:

JAXB1.0

Version:

$Revision: 1.4 $ $Date: 2005/07/29 20:56:02 $

Author:

• Ryan Shoemaker, Sun Microsystems, Inc.
• Kohsuke Kawaguchi, Sun Microsystems, Inc.
• Joe Fialli, Sun Microsystems, Inc.

See Also:

JAXBContext, Unmarshaller, ValidationEventHandler, ValidationEvent, ValidationEventCollector

public void setEventHandler(ValidationEventHandler handler) throws JAXBException
允许应用程序注册一个验证事件处理程序。

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

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

handler	验证事件处理程序
Throws	JAXBException: 如果在设置事件处理程序时发生错误
deprecated	从 JAXB 2.0 开始

英文文档：

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException

Deprecated. since JAXB2.0

Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to validate. If the client application does not register a validation event handler before invoking the validate method, then validation events will be handled by the default event handler which will terminate the validate operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Validator to revert back to the default default event handler.

Parameters:

handler - the validation event handler

Throws:

JAXBException - if an error was encountered while setting the event handler

public ValidationEventHandler getEventHandler() throws JAXBException
当前的事件处理程序；如果没有设置，则返回默认事件处理程序。

return	当前的 ValidationEventHandler；如果没有设置，则返回默认的事件处理程序
Throws	JAXBException: 如果获取当前的事件处理程序时遇到错误
deprecated	从 JAXB 2.0 开始

英文文档：

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException

Deprecated. since JAXB2.0

Return the current event handler or the default event handler if one hasn't been set.

Returns:

the current ValidationEventHandler or the default event handler if it hasn't been set

Throws:

JAXBException - if an error was encountered while getting the current event handler

public boolean validate(Object subrootObj) throws JAXBException
从 subrootObj 开始验证 Java 内容树。

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

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

英文文档：

validate

boolean validate(Object subrootObj)
                 throws JAXBException

Deprecated. since JAXB2.0

Validate the Java content tree starting at subrootObj.

Client applications can use this method to validate Java content trees on-demand at runtime. This method can be used to validate any arbitrary subtree of the Java content tree. Global constraint checking will not be performed as part of this operation (i.e. ID/IDREF constraints).

Parameters:

subrootObj - the obj to begin validation at

Returns:

true if the subtree rooted at subrootObj is valid, false otherwise

Throws:

JAXBException - if any unexpected problem occurs during validation

ValidationException - If the ValidationEventHandler returns false from its handleEvent method or the Validator is unable to validate the content tree rooted at subrootObj

IllegalArgumentException - If the subrootObj parameter is null

public boolean validateRoot(Object rootObj) throws JAXBException
验证以 rootObj 为根的 Java 内容树。

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

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

英文文档：

validateRoot

boolean validateRoot(Object rootObj)
                     throws JAXBException

Deprecated. since JAXB2.0

Validate the Java content tree rooted at rootObj.

Client applications can use this method to validate Java content trees on-demand at runtime. This method is used to validate an entire Java content tree. Global constraint checking will be performed as part of this operation (i.e. ID/IDREF constraints).

Parameters:

rootObj - the root obj to begin validation at

Returns:

true if the tree rooted at rootObj is valid, false otherwise

Throws:

JAXBException - if any unexpected problem occurs during validation

ValidationException - If the ValidationEventHandler returns false from its handleEvent method or the Validator is unable to validate the content tree rooted at rootObj

IllegalArgumentException - If the rootObj parameter is null

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

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

英文文档：

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException

Deprecated. since JAXB2.0

Set the particular property in the underlying implementation of Validator. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:

name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.

value - the value of the property to be set

Throws:

PropertyException - when there is an error processing the given property or value

IllegalArgumentException - If the name parameter is null

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

name	将检索的属性名称
return	所请求属性的值
Throws	PropertyException: 如果检索给定属性或值属性名称时发生错误
Throws	IllegalArgumentException: 如果 name 参数为 null
deprecated	从 JAXB 2.0 开始

英文文档：

getProperty

Object getProperty(String name)
                   throws PropertyException

Deprecated. since JAXB2.0

Get the particular property in the underlying implementation of Validator. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:

name - the name of the property to retrieve

Returns:

the value of the requested property

Throws:

PropertyException - when there is an error retrieving the given property or value property name

IllegalArgumentException - If the name parameter is null

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.