- 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情報セット保持表現をサポートすることもできます。- 導入されたバージョン:
- 1.6, 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構文木で更新されます。
-
-
-
メソッドの詳細
-
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の場合- 導入されたバージョン:
- 1.6, JAXB 2.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の場合
-
-