Binder (Java Platform SE 6)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM Platform
Standard Ed. 6

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

javax.xml.bind
クラス Binder<XmlNode>

java.lang.Object
  javax.xml.bind.Binder<XmlNode>

public abstract class Binder<XmlNode>
extends Object
extends Object

同じ XML 文書を表現する、XML 情報セットノードと JAXB オブジェクトの同期を可能にします。

このクラスのインスタンスは、情報セット保持ビューの XML ノードと、XML 文書の JAXB 表現の間の関連付けを保持します。2 つのビュー間のナビゲーションは、getXMLNode(Object) および getJAXBNode(Object) メソッドによって提供されます。

他方のビューが変更されずにそのままの場合、情報セット保持ビューまたは文書の JAXB 表現のどちらか一方を変更することができます。Binder では、updateXML(Object, Object) または updateJAXB(Object) の適切な Binder 更新メソッドを使用し、一方のビューへの変更が他方のビューに反映されるように同期を取ることができます。

次に、一般的な使用シナリオを示します。

XML 文書を XML 情報セット表現に読み込みます。
XML 情報セットビューを JAXB ビューに非整列化します (unmarshal(Object))(リソースの節約のために、XML 情報セットビューのサブツリーのみを JAXB ビューに非整列化することもできます)。
アプリケーションが XML 文書の JAXB ビューにアクセスする、または、それを更新します。
updateXML(Object) が、 JAXB ビューに対する変更を XML 情報セットビューに対して同期します。更新処理では、可能なかぎり多くの元の XML 情報セットが保持されます (つまり、コメント、PI など)。

Binder インスタンスは、ファクトリメソッド JAXBContext.createBinder() または JAXBContext.createBinder(Class) を使用して作成されます。

テンプレートパラメータ XmlNode は、XML 情報セット保持表現のルートインタフェースまたはルートクラスです。Binder の実装では、org.w3c.dom.Node.class の XmlNode 値を最低限サポートする必要があります。Binder の実装で、別の XML 情報セット保持表現をサポートすることもできます。

導入されたバージョン:: JAXB 2.0

コンストラクタの概要
`Binder()`

メソッドの概要

abstract ValidationEventHandler getEventHandler()
現在のイベントハンドラ、または、それが設定されていない場合はデフォルトイベントハンドラを返します。

abstract Object getJAXBNode(XmlNode xmlNode)
指定した XML 要素に関連付けられている JAXB オブジェクトを取得します。

abstract Object getProperty(String name)
Binder の基本となる実装の特定のプロパティーを取得します。

abstract Schema getSchema()
setSchema(Schema) メソッドによって最後に設定された Schema オブジェクト (null を含む) を取得します。

abstract XmlNode getXMLNode(Object jaxbObject)
指定した JAXB オブジェクトに関連付けられている XML 要素を取得します。

abstract void marshal(Object jaxbObject, XmlNode xmlNode)
JAXB オブジェクトツリーを新しい XML 文書に整列化します。

abstract void setEventHandler(ValidationEventHandler handler)
アプリケーションで ValidationEventHandler を登録できるようにします。

abstract void setProperty(String name, Object value)
Binder の基本となる実装に特定のプロパティーを設定します。

abstract void setSchema(Schema schema)
整列化、非整列化、更新メソッドが XML コンテンツで検証を実行するかどうかを指定します。

abstract Object unmarshal(XmlNode xmlNode)
XML 情報セットビューを JAXB オブジェクトツリーに非整列化します。

abstract 



<T> JAXBElement<T>

unmarshal(XmlNode xmlNode,
          Class<T> declaredType)

指定された declaredType で XML ルート要素を JAXB オブジェクトツリーに非整列化します。

abstract Object updateJAXB(XmlNode xmlNode)
XML ノードを引数とし、それに関連付けられた JAXB オブジェクトとその下位オブジェクトを更新します。

abstract XmlNode updateXML(Object jaxbObject)
JAXB オブジェクトを引数とし、それに関連付けられた XML ノードとその下位ノードを更新します。

abstract XmlNode updateXML(Object jaxbObject, XmlNode xmlNode)
JAXB オブジェクトツリーの変更がそれと関連付けられている XML 構文木で更新されます。

クラス java.lang.Object から継承されたメソッド
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

コンストラクタの詳細

Binder

public Binder()

メソッドの詳細

unmarshal

public abstract Object unmarshal(XmlNode xmlNode)
                          throws JAXBException

XML 情報セットビューを JAXB オブジェクトツリーに非整列化します。

このメソッドは Unmarshaller.unmarshal(Node) と類似していますが、XML ノードと生成された JAXB オブジェクト間の関連付けを保持することが加わり、updateXML(Object, Object) または updateJAXB(Object) による後の更新処理を可能にします。

getSchema() が null 以外の場合、この操作中に xmlNode とその子孫が検証されます。

Binder の JAXBContext に、@xsi:type を介して指定可能な xmlNode の XML 要素名または型から JAXB マップクラスへのマッピングが含まれない場合、このメソッドは UnmarshalException をスローします。この unmarshal(Object, Class) メソッドにより、アプリケーションが xmlNode をマップすべき、JAXB マップクラスを指定できるようになります。

パラメータ:: xmlNode - 非整列化する XML データが含まれる文書または要素。
戻り値:: 新しく作成される JAXB オブジェクトツリーのルートオブジェクト
例外:: JAXBException - 非整列化の実行中に予想外のエラーが発生した場合; UnmarshalException - ValidationEventHandler の handleEvent メソッドから false が返されるか、Binder が XML から Java へのバインディングを実行できない場合; IllegalArgumentException - ノードパラメータが null の場合

unmarshal

public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode,
                                             Class<T> declaredType)
                                  throws JAXBException

指定された declaredType で XML ルート要素を JAXB オブジェクトツリーに非整列化します。

「宣言型による非整列化」を実装します。

このメソッドは Unmarshaller.unmarshal(Node, Class) と類似していますが、XML ノードと生成された JAXB オブジェクト間の関連付けを保持することが加わり、updateXML(Object, Object) または updateJAXB(Object) による後の更新処理を可能にします。

getSchema() が null 以外の場合、この操作中に xmlNode とその子孫が検証されます。

パラメータ:: xmlNode - 非整列化する XML データが含まれる文書または要素。; declaredType - node の XML データを保持する、適切な JAXB マップクラス
戻り値:: node の JAXB 要素表現
例外:: JAXBException - 非整列化の実行中に予想外のエラーが発生した場合; UnmarshalException - ValidationEventHandler の handleEvent メソッドから false が返されるか、Binder が XML から Java へのバインディングを実行できない場合; IllegalArgumentException - いずれかの入力パラメータが null の場合
導入されたバージョン:: JAXB2.0

marshal

public abstract void marshal(Object jaxbObject,
                             XmlNode xmlNode)
                      throws JAXBException

JAXB オブジェクトツリーを新しい XML 文書に整列化します。

このメソッドは Marshaller.marshal(Object, Node) と類似していますが、JAXB オブジェクトと生成された XML ノード間の関連付けを保持することが加わり、updateXML(Object, Object) または updateJAXB(Object) などによる後の更新処理を可能にします。

getSchema() が null 以外の場合、この操作中に整列化された XML コンテンツが検証されます。

パラメータ:: jaxbObject - 整列化するコンテンツツリー; xmlNode - このパラメータは、子を受け入れるノードである必要がある
例外:: JAXBException - 整列化の実行中に予想外の問題が発生した場合; MarshalException - ValidationEventHandler の handleEvent メソッドから false が返されるか、Binder が jaxbObject (または jaxbObject から到達可能なオブジェクト) を整列化できない場合; IllegalArgumentException - いずれかのメソッドパラメータが null の場合

getXMLNode

public abstract XmlNode getXMLNode(Object jaxbObject)

指定した JAXB オブジェクトに関連付けられている XML 要素を取得します。

JAXB オブジェクトツリーが XML フラグメントにいったん関連付けられると、このメソッドを使用して 2 つのツリー間のナビゲーションが可能になります。

XML 要素と JAXB オブジェクト間の関連付けは、バインドメソッドと更新メソッドによって確立されます。この関連付けは部分的であり、すべての XML 要素が関連付けられた JAXB オブジェクトを持つわけでなく、また、すべての JAXB オブジェクトが関連付けられた XML 要素を持つわけでないことに注意してください。

パラメータ:: jaxbObject - JAXB オブジェクトツリーを返したバインドメソッドまたは更新メソッドの事前の呼び出しから到達可能なインスタンス
戻り値:: 指定した JAXB オブジェクトがこの Binder に認識されない場合、または XML 要素に関連付けられていない場合は null
例外:: IllegalArgumentException - jaxbObject パラメータが null の場合

getJAXBNode

public abstract Object getJAXBNode(XmlNode xmlNode)

指定した XML 要素に関連付けられている JAXB オブジェクトを取得します。

XML 要素と JAXB オブジェクト間の関連付けは、非整列化、整列化および更新メソッドによって確立されます。この関連付けは部分的であり、すべての XML 要素が関連付けられた JAXB オブジェクトを持つわけでなく、また、すべての JAXB オブジェクトが関連付けられた XML 要素を持つわけでないことに注意してください。

戻り値:: 指定した XML ノードがこの Binder に認識されない場合、または JAXB オブジェクトに関連付けられていない場合は null
例外:: IllegalArgumentException - ノードパラメータが null の場合

updateXML

public abstract XmlNode updateXML(Object jaxbObject)
                           throws JAXBException

JAXB オブジェクトを引数とし、それに関連付けられた XML ノードとその下位ノードを更新します。

これは、次のメソッドの簡易メソッドです。

 updateXML( jaxbObject, getXMLNode(jaxbObject));

例外:: JAXBException - 対応する XML コンテンツの更新中に予想外の問題が発生した場合; IllegalArgumentException - jaxbObject パラメータが null の場合

updateXML

public abstract XmlNode updateXML(Object jaxbObject,
                                  XmlNode xmlNode)
                           throws JAXBException

JAXB オブジェクトツリーの変更がそれと関連付けられている XML 構文木で更新されます。

この操作は、「インプレース」整列化処理と捉えることができます。相違点は、新しい XML ツリー全体を作成するのではなく、この操作は既存のツリーを更新し、可能なかぎり多くの XML を保持しようとする点です。

たとえば、JAXB にバインドされていない不明な XML 要素または属性は未変更なままです (それに対して、整列化操作ではこうした要素や属性を含まない新しいツリーが作成されます)。

副作用として、この操作は XML ノードと JAXB オブジェクトの関連付けを更新します。

パラメータ:: jaxbObject - 変更された可能性のある JAXB オブジェクトツリーのルート; xmlNode - 更新ターゲットの XML 構文木のルート
戻り値:: 更新された XML ノードを返す。通常、これは xmlNode として渡したものと同じノードだが、オブジェクトのタグ名が変更された場合など、別のオブジェクトになる可能性もある
例外:: JAXBException - 対応する XML コンテンツの更新中に予想外の問題が発生した場合; IllegalArgumentException - いずれかの入力パラメータが null の場合

updateJAXB

public abstract Object updateJAXB(XmlNode xmlNode)
                           throws JAXBException

XML ノードを引数とし、それに関連付けられた JAXB オブジェクトとその下位オブジェクトを更新します。

この操作は、「インプレース」非整列化処理と捉えることができます。相違点は、新しい JAXB ツリー全体を作成するのでなく、この操作は既存のツリーを更新し、可能なかぎり多くの JAXB オブジェクトを再利用する点です。

副作用として、この操作は XML ノードと JAXB オブジェクトの関連付けを更新します。

戻り値:: 更新された JAXB オブジェクトを返す。通常、これは事前の marshal(Object,Object) または updateJAXB(Object) メソッドの呼び出しで返されたオブジェクトと同じである。しかし、XML 要素名が変更された場合など、別のオブジェクトになる可能性もある
例外:: JAXBException - コンテンツがマップされた、対応する JAXB の更新中に予想外の問題が発生した場合; IllegalArgumentException - ノードパラメータが null の場合

setSchema

public abstract void setSchema(Schema schema)

整列化、非整列化、更新メソッドが XML コンテンツで検証を実行するかどうかを指定します。

パラメータ:: schema - 検証を無効にするには null に設定
関連項目:: Unmarshaller.setSchema(Schema)

getSchema

public abstract Schema getSchema()

setSchema(Schema) メソッドによって最後に設定された Schema オブジェクト (null を含む) を取得します。

戻り値:: 検証する Schema オブジェクト、または、存在しない場合、null

setEventHandler

public abstract void setEventHandler(ValidationEventHandler handler)
                              throws JAXBException

アプリケーションで ValidationEventHandler を登録できるようにします。

ValidationEventHandler は、Binder 非整列化、整列化および更新メソッドのいずれかを呼び出している途中で検証エラーが発生した場合、JAXB プロバイダによって呼び出されます。

このメソッドを null パラメータとともに呼び出した場合、Binder はデフォルトのデフォルトイベントハンドラに戻されます。

パラメータ:: handler - 検証イベントハンドラ
例外:: JAXBException - イベントハンドラの設定中にエラーが発生した場合

getEventHandler

public abstract ValidationEventHandler getEventHandler()
                                                throws JAXBException

現在のイベントハンドラ、または、それが設定されていない場合はデフォルトイベントハンドラを返します。

戻り値:: 現在の ValidationEventHandler。それが設定されていない場合はデフォルトイベントハンドラ
例外:: JAXBException - 現在のイベントハンドラの取得中にエラーが発生した場合

setProperty

public abstract void setProperty(String name,
                                 Object value)
                          throws PropertyException

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

パラメータ:: name - 設定するプロパティーの名前。この値は、定数フィールドの 1 つかユーザーが指定した文字列を使用して指定できる; value - 設定するプロパティーの値
例外:: PropertyException - 指定したプロパティーまたは値の処理中にエラーが発生した場合; IllegalArgumentException - name パラメータが null の場合

getProperty

public abstract Object getProperty(String name)
                            throws PropertyException

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

パラメータ:: name - 取得するプロパティーの名前
戻り値:: 要求されたプロパティーの値
例外:: PropertyException - 指定したプロパティーまたは値プロパティー名の取得中にエラーが発生した場合; IllegalArgumentException - name パラメータが null の場合