38.2. XML スキーマプリミティブの Java クラスの指定

デフォルトでは、XML スキーマ型は Java プリミティブ型にマップされます。これは XML スキーマと Java の間の最も論理的なマッピングですが、アプリケーション開発者の要件を常に満たすとは限りません。XML スキーマプリミティブ型を追加情報を保持できる Java クラスにマップしたり、XML プリミティブ型を単純な型置換を可能にするクラスにマップしたりすることができます。

JAXB javaType カスタマイズ要素を使用すると、XML スキーマプリミティブ型と Java プリミティブ型間のマッピングをカスタマイズできます。これを使用して、グローバルレベルと個々のインスタンスレベルの両方でマッピングをカスタマイズできます。javaType 要素は、単純型定義の一部として、または複合型定義の一部として使用できます。

javaType カスタマイズ要素を使用する場合は、プリミティブ型の XML 表現とターゲット Java クラス間の変換方法を指定する必要があります。一部のマッピングには、デフォルトの変換方法があります。デフォルトのマッピングがない場合、Apache CXF は必要なメソッドの開発を容易にする JAXB メソッドを提供します。

javaType カスタマイズ要素は、表38.1「XML スキーマタイプの Java クラスの生成をカスタマイズするための属性」 に記載されている 4 つの属性を取ります。

javaType カスタマイズ要素は、3 つの方法で使用できます。

Apache CXF は、XML スキーマのプリミティブ型をランダムな Java クラスに変換できません。javaType 要素を使用して XML スキーマプリミティブ型のマッピングをカスタマイズする場合、コードジェネレーターは、カスタマイズされた XML スキーマプリミティブ型をマーシャリングおよびアンマーシャリングするために使用されるアダプタークラスを作成します。サンプルのアダプタークラスを 例38.10「JAXB アダプタークラス」 に示します。

public class Adapter1 extends XmlAdapter<String, javaType>
{
  public javaType unmarshal(String value)
  {
    return(parseMethod(value));
  }

  public String marshal(javaType value)
  {
    return(printMethod(value));
  }
}

parseMethod および printMethod は、対応する parseMethod 属性および printMethod 属性の値に置き換えてください。値は、有効な Java メソッドを識別する必要があります。メソッドの名前は、次の 2 つの方法のいずれかで指定できます。

parseMethod 属性の値が指定されていない場合、コードジェネレーターは、name 属性で指定された Java クラスに最初のパラメーターが Java String オブジェクトのコンストラクターがあると想定します。生成されたアダプターの unmarshal() メソッドは、想定されたコンストラクターを使用して Java オブジェクトに XML データを設定します。

printMethod 属性の値が指定されていない場合、コードジェネレーターは、name 属性で指定された Java クラスに toString() メソッドがあると想定します。生成されたアダプターの marshal() メソッドは、想定された toString() メソッドを使用して Java オブジェクトを XML データに変換します。

javaType 要素の name 属性が Java プリミティブ型または Java プリミティブのラッパー型のいずれかを指定する場合、コードジェネレーターはデフォルトのコンバーターを使用します。デフォルトのコンバーターの詳細については、「デフォルトのプリミティブ型コンバーター」 を参照してください。

「コンバーターの指定」 に記載のとおり、javaType カスタマイズ要素を使用すると、XML スキーマプリミティブ型の各カスタマイズに対してアダプタークラスの生成が 1 つトリガーされます。このアダプターの名前は、AdapterN のパターンを使用して順番に付けられます。2 つのプリミティブタイプのカスタマイズを指定する場合、コードジェネレーターは Adapter1 と Adapter2 の 2 つのアダプタークラスを作成します。

XML スキーマ構造用に生成されたコードは、影響を受ける XML スキーマ構造がグローバルに定義された要素であるか、複合型の一部として定義されているかによって異なります。

XML スキーマ構造がグローバルに定義された要素である場合、その型に対して生成されたオブジェクトファクトリーメソッドは、デフォルトのメソッドから次のように変更されます。

例38.11「グローバル要素のカスタマイズされたオブジェクトファクトリーメソッド」 は、例38.7「グローバルプリミティブ型のカスタマイズ」 に示すカスタマイズの影響を受ける要素のオブジェクトファクトリーメソッドを示します。

 @XmlElementDecl(namespace = "http://widgetVendor.com/types/widgetTypes", name = "shorty")
 @XmlJavaTypeAdapter(org.w3._2001.xmlschema.Adapter1.class)
 public JAXBElement<Integer> createShorty(Integer value) {
     return new JAXBElement<Integer>(_Shorty_QNAME, Integer.class, null, value);
 }

XML スキーマ構造が複合型の一部として定義されている場合、生成された Java プロパティーは次のように変更されます。

例38.12「カスタマイズされた複合タイプ」 は、例38.7「グローバルプリミティブ型のカスタマイズ」 に示すカスタマイズの影響を受ける要素のオブジェクトファクトリーメソッドを示します。

public class NumInventory {

    @XmlElement(required = true, type = String.class) @XmlJavaTypeAdapter(Adapter1.class) @XmlSchemaType(name = "short") protected Integer numLeft;
    @XmlElement(required = true)
    protected String size;

    public Integer getNumLeft() {
        return numLeft;
    }

    public void setNumLeft(Integer value) {
        this.numLeft = value;
    }

    public String getSize() {
        return size;
    }

    public void setSize(String value) {
        this.size = value;
    }

}

parseMethod 属性と printMethod 属性で指定されたメソッドを呼び出す必要があることを除き、Apache CXF ランタイムは、XML プリミティブ型と javaType 要素によって指定された Java クラス間の変換方法を認識しません。ランタイムが呼び出すメソッドの実装を提供するのはあなたの責任です。実装されたメソッドは、XML プリミティブ型の字句構造を処理できる必要があります。

データ変換メソッドの実装を簡素化するために、Apache CXF は javax.xml.bind.DatatypeConverter クラスを提供します。このクラスは、すべての XML スキーマプリミティブ型を解析および出力するためのメソッドを提供します。解析メソッドは XML データの文字列表現を取り、表34.1「XML スキーマのプリミティブ型から Java ネイティブ型へのマッピング」 で定義されたデフォルトタイプのインスタンスを返します。print メソッドはデフォルトタイプのインスタンスを取り、XML データの文字列表現を返します。

DatatypeConverter クラスの Java ドキュメントは、https://docs.oracle.com/javase/8/docs/api/javax/xml/bind/DatatypeConverter.html にあります。

Java プリミティブ型、または Java プリミティブ型のラッパークラスのいずれかを javaType 要素の name 属性で指定する場合には、parseMethod 属性または printMethod 属性の値を指定する必要はありません。値が指定されていない場合、Apache CXF ランタイムはデフォルトのコンバーターを置き換えます。

デフォルトのデータコンバーターは JAXB DatatypeConverter クラスを使用して XML データを解析します。デフォルトのコンバーターは、変換を機能させるために必要な型キャストも提供します。