機械翻訳について

javax.xml.bind

クラスBinder<XmlNode>

java.lang.Object

javax.xml.bind.Binder<XmlNode>

public abstract class Binder<XmlNode>
extends Object

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

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

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

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

• 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オブジェクトを取得します。

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

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の場合