モジュール java.xml.bind
パッケージ javax.xml.bind.annotation.adapters

クラスXmlAdapter<ValueType,BoundType>

  • 型パラメータ:
    BoundType - JAXBが処理方法を知らない型。 ValueTypeを介してこの型をメモリー内表現として使用できるようにアダプタは記述される。
    ValueType - JAXBが初めから処理方法を知っている型。
    直系の既知のサブクラス:
    CollapsedStringAdapter, HexBinaryAdapter, NormalizedStringAdapter
    public abstract class XmlAdapter<ValueType,BoundType>
extends Object
    Java型をカスタム整列化に適応させます。

    使用法:

    Javaのタイプの中には、自然にXML表現にマッピングされないものがあります。たとえば、HashMapやその他のJavaBean以外のクラスです。 逆に、XML表現はJava型にマップすることができますが、アプリケーションは別のJava型を使用してXML表現にアクセスすることを選択できます。 たとえば、スキーマからJavaへのバインディング規則では、デフォルトでxs:dateTimeがXmlGregorianCalendarにバインドされます。 しかし、アプリケーションがxs:dateTimeをカスタム型、たとえば、MyXmlGregorianCalendarにバインドすることを望む場合もあります。 いずれの場合でも、アプリケーションがXMLコンテンツにアクセスするときに使用するバウンド型と、XML表現へとマップされる値型の間に不一致が存在します。

    このabstractクラスは、バウンド型を値型に、またはその逆に適応させるためのメソッドを定義しています。 整列化および非整列化の実行中に、これらのメソッドはJAXBバインディング・フレームワークによって呼び出されます。

    • XmlAdapter.marshal(...): 整列化の実行中、JAXBバインディング・フレームワークはXmlAdapter.marshal(..)を呼び出してバウンド型を値型に適応させたあと、それをXML表現に整列化します。
    • XmlAdapter.unmarshal(...): 非整列化の実行中、JAXBバインディング・フレームワークは、XML表現を値型に非整列化したあと、XmlAdapter.unmarshal(..)を呼び出して値の型をバウンド型に適応させます。
    そのため、アダプタの記述は次の手順を含みます。
    • このabstractクラスを実装するアダプタを記述します。
    • 注釈XmlJavaTypeAdapterを使用してアダプタを組み込みます。

    例: HashMapのカスタマイズ・マッピング

    次の例は、@XmlAdapterと@XmlJavaTypeAdapterを使用してHashMapのマッピングをカスタマイズする方法を示します。

    ステップ1: HashMapに対する適切なXML表現を決定します。 

    
     <hashmap>
         <entry key="id123">this is a value</entry>
         <entry key="id312">this is another value</entry>
         ...
     </hashmap>

    ステップ2: 上記のXML表現が従うべきスキーマ定義を決定します。 

    

     <xs:complexType name="myHashMapType">
       <xs:sequence>
         <xs:element name="entry" type="myHashMapEntryType"
                        minOccurs = "0" maxOccurs="unbounded"/>
       </xs:sequence>
     </xs:complexType>

     <xs:complexType name="myHashMapEntryType">
       <xs:simpleContent>
         <xs:extension base="xs:string">
           <xs:attribute name="key" type="xs:int"/>
         </xs:extension>
       </xs:simpleContent>
     </xs:complexType>

    ステップ3: 上記のスキーマ定義を生成可能である値型を記述します。 

         public class MyHashMapType {
         List<MyHashMapEntryType> entry;
     }

     public class MyHashMapEntryType {
         @XmlAttribute
         public Integer key;

         @XmlValue
         public String value;
     }

    ステップ4: 値型MyHashMapTypeを、バウンド型HashMapに適応させるアダプタを記述します。これはアプリケーションによって使用されます。 

    
     public final class MyHashMapAdapter extends
                        XmlAdapter<MyHashMapType,HashMap> { ... }

    ステップ5: アダプタを使用します。 

         public class Foo {
         @XmlJavaTypeAdapter(MyHashMapAdapter.class)
         HashMap hashmap;
         ...
     }
    上記のコード・フラグメントは、次のスキーマにマップします。 
    
     <xs:complexType name="Foo">
       <xs:sequence>
         <xs:element name="hashmap" type="myHashMapType">
       </xs:sequence>
     </xs:complexType>
    導入されたバージョン:
    1.6, JAXB 2.0
    関連項目:
    XmlJavaTypeAdapter

    • コンストラクタの詳細

      • XmlAdapter

        protected XmlAdapter()
        派生クラス用の何も実行しないコンストラクタです。

    • メソッドの詳細

      • unmarshal

        public abstract BoundType unmarshal​(ValueType v)
                             throws Exception
        値型をバウンド型に変換します。
        パラメータ:
        v - 変換する値。 nullも可。
        例外:
        Exception - 変換中にエラーが発生した場合。 呼出し側はValidationEventHandlerを介して、このエラーをユーザーに報告する。

      • marshal

        public abstract ValueType marshal​(BoundType v)
                           throws Exception
        バウンド型を値型に変換します。
        パラメータ:
        v - 変換する値。 nullも可。
        例外:
        Exception - 変換中にエラーが発生した場合。 呼出し側はValidationEventHandlerを介して、このエラーをユーザーに報告する。