Binder (Java Platform SE 7)

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, 2013, 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