Binder (Java Platform SE 8)

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()

コンストラクタ
コンストラクタと説明
`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の場合

バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright© 1993, 2014, Oracle and/or its affiliates. All rights reserved.

クラスBinder<XmlNode>

コンストラクタのサマリー

メソッドのサマリー

クラス java.lang.Objectから継承されたメソッド

コンストラクタの詳細

Binder

メソッドの詳細

unmarshal

unmarshal

marshal

getXMLNode

getJAXBNode

updateXML

updateXML

updateJAXB

setSchema

getSchema

setEventHandler

getEventHandler

setProperty

getProperty