javax.xml.bind

インタフェース Validator

非推奨。

JAXB 2.0 以降

public interface Validator

JAXB 2.0 の時点で、このクラスは非推奨でオプションのクラスとなりました。

Validator クラスは、実行時にコンテンツツリーの検証を制御します。

3 つの形式の検証

非整列化時の検証

この検証形式では、XML データを Java コンテンツツリーに非整列化する途中で検出された検証エラーと警告に関する情報をクライアントアプリケーションは受け取ることができ、ほかの検証形式と完全に交錯します。これを有効または無効にするには、javadoc の Unmarshaller.setValidating を参照してください。すべての JAXB 1.0 プロバイダは、この操作をサポートする必要があります。

オンデマンド検証

この検証形式では、Java コンテンツツリーで検出された検証エラーおよび警告に関する情報をクライアントアプリケーションは受け取ることができます。任意の時点で、クライアントアプリケーションは Java コンテンツツリー (または、それの任意のサブツリー) に対して Validator.validate メソッドを呼び出すことができます。すべての JAXB 1.0 プロバイダは、この操作をサポートする必要があります。

フェイルファスト検証

この検証形式では、クライアントアプリケーションは、仕様で定義された Java プロパティーの型制約に違反する Java コンテンツツリー変更に関するフィードバックを即座に受け取ることができます。JAXB プロバイダがこの型の検証をサポートすることは必須ではありません。この型の検証をサポートしている JAXB プロバイダのなかには、クライアントアプリケーションが実行時のフェイルファスト検証を要求することを許可するかどうかをスキーマコンパイル時に決定する必要があるものもあります。

Validator クラスは、オンデマンド検証の管理を担当します。Unmarshaller クラスは、非整列化操作中の非整列化時検証の管理を担当します。整列化操作中の検証を有効にする正式なメソッドはありませんが、Marshaller はエラーを検出し、自身に登録されている ValidationEventHandler に報告します。

デフォルトイベントハンドラの使用

検証、非整列化、整列化メソッドの呼び出しの前に、クライアントアプリケーションが Validator、Unmarshaller、Marshaller にイベントハンドラを設定していない場合、デフォルトイベントハンドラが発生したエラーまたは警告の通知を受け取ります。デフォルトイベントハンドラは、最初のエラーまたは致命的なエラーの検出後、現在の操作を停止させます (警告を受け取ったあとは、続行させることを試みます)。

検証イベントの処理

非整列化、検証、整列化操作中に発生したイベントを処理する方法には、次の 3 つがあります。

デフォルトイベントハンドラの使用

Validator、Unmarshaller、または Marshaller に対し setEventHandler API を介してイベントハンドラを指定しなかった場合、デフォルトイベントハンドラが使用されます。

カスタムイベントハンドラの実装と登録

高度なイベント処理を必要とするクライアントアプリケーションは、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 プロパティーまたはプロバイダ固有のプロパティーの 1 つを設定する目的にのみ使用できます。未定義のプロパティーを設定しようとした場合、PropertyException がスローされます。「サポートされているプロパティー」を参照してください。

パラメータ:

name - 設定するプロパティーの名前。この値は、定数フィールドの 1 つかユーザーが指定した文字列を使用して指定できる。

value - 設定するプロパティーの値

例外:

PropertyException - 指定したプロパティーまたは値の処理中にエラーが発生した場合

IllegalArgumentException - name パラメータが null の場合

getProperty

Object getProperty(String name)
                   throws PropertyException

非推奨。 JAXB2.0 以降

Validator の基本となる実装の特定のプロパティーを取得します。このメソッドは、先に述べた定義済みの標準 JAXB プロパティーまたはプロバイダ固有のプロパティーの 1 つを取得する目的にのみ使用できます。未定義のプロパティーを取得しようとした場合、PropertyException がスローされます。「サポートされているプロパティー」を参照してください。

パラメータ:

name - 取得するプロパティーの名前

戻り値:

要求されたプロパティーの値

例外:

PropertyException - 指定したプロパティーまたは値プロパティー名の取得中にエラーが発生した場合

IllegalArgumentException - name パラメータが null の場合