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 方法之前在其 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 提供者都支持的屬性。但是，一些提供者可能支持它們自己的特定於提供者的屬性集。

從以下版本開始：

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