ヘッダーをスキップ
Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS を使用した Web サービス入門
11g リリース 1 (10.3.1)
B55565-01
  目次
目次

戻る
戻る
 
次へ
次へ

5 JAXB データ バインディングの使用

以下の節では、JAXB データ バインディングの使用について説明します。

JAXB を使用したデータ バインディングの概要

さまざまなシステム間でのデータ交換には XML が標準的に使用されているため、Web サービス アプリケーションには、Java アプリケーションから直接 XML 形式データへアクセスする手段が必要となります。具体的には、XML コンテンツを Java アプリケーションで読み取れる形式に変換する必要があります。「データ バインディング」では、XML 表現と Java 表現間のデータ変換を記述します。

JAX-WS では、Java Architecture for XML Binding (JAXB) (http://jcp.org/en/jsr/detail?id=222 を参照) を使用してあらゆるデータ バインディング タスクを管理します。具体的には、JAXB により Java メソッド シグネチャと WSDL のメッセージおよびオペレーションがバインドされるため、実行時の変換が自動的に処理される一方で、そのマッピングをカスタマイズすることができます。これにより、XML に関する知識がそれほどなくても、XML データと処理関数を、Java テクノロジに基づくアプリケーションに簡単に組み込むことができます。

次の図に、JAXB のデータ バインディング プロセスを示します。

図 5-1 JAXB でのデータ バインディング

図 5-1 の説明は図の下のリンクをクリックしてください。
「図 5-1 JAXB でのデータ バインディング」の説明

この図に示すように、JAXB のデータ バインディング プロセスは、以下のタスクから構成されます。

JAXB バインディング言語を使用すると、カスタム バインディング宣言を定義したり、JAXB アノテーションを指定して XML と Java 間のデータ変換を制御することができます。

以降の節で説明する内容は、次のとおりです。

JAXB データ バインディング アーティファクトの開発

WebLogic Server で JAXB データ バインディング アーティファクトを開発する手順は、Java クラス ファイルと WSDL のどちらから開始するかによって異なります。

こららの手順で説明している jwscwsdlc、または clientgen Ant タスクを呼び出す場合、以下の点に注意する必要があります。

jwscwsdlc、または clientgen Ant タスクの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「Ant タスク リファレンス」を参照してください。

標準データ型のマッピング

WebLogic Web サービスでは、JAXB 2.0 (JSR 222) 仕様 (http://jcp.org/en/jsr/detail?id=222) の規定に従って組み込みの XML スキーマ、Java、および SOAP のデータ型がサポートされており、追加のプログラミング手順を踏まずに、そうしたデータ型を Web サービスのオペレーションで使用できます。組み込みデータ型には、integerstringtime などがあります。

また、Web サービスの入力パラメータや戻り値として、さまざまなユーザ定義の XML および Java データ型を使用できます。ユーザ定義のデータ型には、XML スキーマや Java の構成要素から作成する <xsd:complexType> や JavaBean などがあります。jwscclientgen などの WebLogic Web サービス Ant タスクでは、ユーザ定義のデータ型を XML 表現と Java 表現の間で変換するのに必要なデータ バインディング アーティファクトが自動的に生成されます。XML 表現は SOAP リクエストや応答メッセージで使用し、Java 表現は Web サービスを実装する JWS で使用します。

以下の節では、JAXB でサポートされている組み込みデータ型およびユーザ定義データ型について説明します。

サポートされる組み込みデータ型

次の節では、WebLogic Web サービスがサポートする組み込みデータ型およびその XML 表現と Java 表現間のマッピングについて説明します。Web サービスを実装するバックエンド コンポーネントのパラメータと戻り値のデータ型が、組み込みデータ型のセットの中にある限り、データは WebLogic Server によって、XML と Java 間で自動的に変換されます。

ユーザ定義のデータ型を使用する場合は、XML と Java 間でデータを変換するデータ バインディング アーティファクトを作成する必要があります。WebLogic Server には、ほとんどのユーザ定義データ型のデータ バインディング アーティファクトを自動的に生成可能な jwsc および wsdlc Ant タスクが用意されています。サポートされる XML データ型と Java データ型については、「サポートされるユーザ定義のデータ型」を参照してください。

組み込みデータ型の XML-to-Java マッピング

次の表に、サポートされる XML スキーマ データ型 (ターゲット ネームスペース http://www.w3.org/2001/XMLSchema) と、それぞれに対応する Java データ型をアルファベット順に示します。サポートされるユーザ定義の XML データ型については、「組み込みデータ型の Java-to-XML マッピング」を参照してください。

表 5-1 XML スキーマの組み込みデータ型と Java データ型のマッピング

XML スキーマ データ型 Java データ型 (小文字はプリミティブ データ型を示す)

anySimpleType (この型の xsd:element 用)

java.lang.Object

anySimpleType (この型の xsd:attribute 用)

java.lang.String

base64Binary

byte[]

boolean

boolean

byte

byte

date

java.xml.datatype.XMLGregorianCalendar

dateTime

javax.xml.datatype.XMLGregorianCalendar

decimal

java.math.BigDecimal

double

double

duration

javax.xml.datatype.Duration

float

float

g

java.xml.datatype.XMLGregorianCalendar

hexBinary

byte[]

int

int

integer

java.math.BigInteger

long

long

NOTATION

javax.xml.namespace.QName

Qname

javax.xml.namespace.QName

short

short

string

java.lang.String

time

java.xml.datatype.XMLGregorianCalendar

unsignedByte

short

unsignedInt

long

unsignedShort

int


次の例は JAXB 仕様からの抜粋ですが、デフォルトの XML-to-Java バインディングの例を示しています。

XML スキーマ
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="purchaseOrder" type="PurchaseOrderType"/>
<xsd:element name="comment" type="xsd:string"/>
<xsd:complexType name="PurchaseOrderType">
     <xsd:sequence>
          <xsd:element name="shipTo" type="USAddress"/>
          <xsd:element name="billTo" type="USAddress"/>
          <xsd:element ref="comment" minOccurs="0"/>
          <xsd:element name="items" type="Items"/>
     </xsd:sequence>
     <xsd:attribute name="orderDate" type="xsd:date"/>
</xsd:complexType>
<xsd:complexType name="USAddress">
     <xsd:sequence>
          <xsd:element name="name" type="xsd:string"/>
          <xsd:element name="street" type="xsd:string"/>
          <xsd:element name="city" type="xsd:string"/>
          <xsd:element name="state" type="xsd:string"/>
          <xsd:element name="zip" type="xsd:decimal"/>
     </xsd:sequence>
<xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US"/>
</xsd:complexType>
<xsd:complexType name="Items">
     <xsd:sequence>
          <xsd:element name="item" minOccurs="1" maxOccurs="unbounded">
               <xsd:complexType>
                    <xsd:sequence>
                         <xsd:element name="productName" type="xsd:string"/>
                         <xsd:element name="quantity">
                              <xsd:simpleType>
                                   <xsd:restriction base="xsd:positiveInteger">
                                        <xsd:maxExclusive value="100"/>
                                   </xsd:restriction>
                              </xsd:simpleType>
                         </xsd:element>
                         <xsd:element name="USPrice" type="xsd:decimal"/>
                         <xsd:element ref="comment" minOccurs="0"/>
                         <xsd:element name="shipDate" type="xsd:date"
                              minOccurs="0"/>
                    </xsd:sequence>
                    <xsd:attribute name="partNum" type="SKU" use="required"/>
               </xsd:complexType>
          </xsd:element>
     </xsd:sequence>
</xsd:complexType>
<!-- 最小在庫管理単位、製品を識別するためのコード -->
<xsd:simpleType name="SKU">
     <xsd:restriction base="xsd:string">
          <xsd:pattern value="\d{3}-[A-Z]{2}"/>
     </xsd:restriction>
</xsd:simpleType>
</xsd:schema>
デフォルト Java バインディング
import javax.xml.datatype.XMLGregorianCalendar; import java.util.List;
public class PurchaseOrderType {
     USAddress getShipTo(){...} 
     void setShipTo(USAddress){...}
     USAddress getBillTo(){...} 
     void setBillTo(USAddress){...}
     /** Comment プロパティの設定 (省略可能) */
     String getComment(){...} 
     void setComment(String){...}
     Items getItems(){...}
     void setItems(Items){...}
     XMLGregorianCalendar getOrderDate() 
     void setOrderDate(XMLGregorianCalendar)
};
public class USAddress {
     String getName(){...} 
     void setName(String){...}
     String getStreet(){...} 
     void setStreet(String){...}
     String getCity(){...} 
     void setCity(String){...}
     String getState(){...} 
     void setState(String){...}
     int getZip(){...} 
     void setZip(int){...}
     static final String COUNTRY="USA";
};
public class Items {
     public class ItemType {
          String getProductName(){...} 
          void setProductName(String){...}
          /** セッター値 0..99 の型制約.*/
          int getQuantity(){...} 
          void setQuantity(int){...}
          float getUSPrice(){...} 
          void setUSPrice(float){...}
          /** Comment プロパティの設定 (省略可能) */
          String getComment(){...} 
          void setComment(String){...}
          XMLGregorianCalendar getShipDate();
          void setShipDate(XMLGregorianCalendar);
          /** PartNum セッター値 "\d{3}-[A-Z]{2}"の型制約 */
          String getPartNum(){...} void setPartNum(String){...}
     };
     /** ItemType のローカルの構造的制約の 1 つまたは複数のインスタンス。ItemType.*/
     List<Items.ItemType> getItem(){...}
}
public class ObjectFactory {
     // 型ファクトリ
     Object newInstance(Class javaInterface){...}
     PurchaseOrderType createPurchaseOrderType(){...}
     USAddress createUSAddress(){...}
     Items createItems(){...}
     Items.ItemType createItemsItemType(){...}
     // 要素ファクトリ
JAXBElement<PurchaseOrderType>createPurchaseOrder(PurchaseOrderType){...}
     JAXBElement<String> createComment(String value){...}
}

組み込みデータ型の Java-to-XML マッピング

次の表に、サポートされている Java データ型と、それぞれに対応する XML スキーマ データ型をアルファベット順に示します。サポートされるユーザ定義の Java データ型については、「サポートされるユーザ定義の Java データ型」を参照してください。

表 5-2 Java データ型と XML スキーマ データ型のマッピング

Java データ型 (小文字はプリミティブ データ型を示す) XML スキーマ データ型

boolean

boolean

byte

byte

double

double

float

float

long

long

int

int

javax.activation.DataHandler

base64Binary

java.awt.Image

base64Binary

java.lang.Object

anyType

java.lang.String

string

java.math.BigInteger

integer

java.math.BigDecimal

decimal

java.net.URI

string

java.util.Calendar

dateTime

java.util.Date

dateTime

java.util.UUID

string

javax.xml.datatype.XMLGregorianCalendar

anySimpleType

javax.xml.datatype.Duration

duration

javax.xml.namespace.QName

Qname

javax.xml.transform.Source

base64Binary

short

short


サポートされるユーザ定義のデータ型

以降の節の表には、jwsc および wsdlc Ant タスクでデータ バインディング アーティファクトを自動的に生成できるユーザ定義の XML データ型および Java データ型 (対応する Java 表現または XML 表現など) をまとめます。

これらの表にない XML データ型または Java データ型で、「サポートされる組み込みデータ型」の表に示した組み込みデータ型でもない型の場合は、ユーザ定義データ型のアーティファクトを手動で作成する必要があります。

サポートされるユーザ定義の XML データ型

次の表に、jwsc および wsdlc Ant タスクでサポートされる XML スキーマ データ型と、それぞれに対応する Java データ型またはマッピング メカニズムをまとめます。

表 5-3 サポートされているユーザ定義の XML スキーマ データ型

XML スキーマ データ型 同等の Java データ型またはマッピング メカニズム

単純型および複合型の両方の要素を持つ <xsd:complexType>

JavaBeans。

単純なコンテンツを含む <xsd:complexType>

JavaBeans。

<xsd:complexType><xsd:attribute>

JavaBeans のプロパティ。

既存の単純型の制限による新しい単純型の派生

同等の単純型の Java データ型。

制限要素で使用されるファセット

シリアライゼーションおよびデシリアライゼーションで強制されないファセット。

<xsd:list>

リスト データ型の配列。

wsdl:arrayType 属性を使用した制限によって soapenc:Array から派生する配列

arrayType データ型と同等の Java データ型の配列。

制限によって soapenc:Array から派生する配列

同等の Java データ型の配列。

単純型からの複合型の派生

_value というプロパティのある JavaBean。_value の型は、この節の規則に従って単純型からマップされる。

<xsd:anyType>

java.lang.Object

<xsd:any>

javax.xml.soap.SOAPElement

<xsd:any[]>

javax.xml.soap.SOAPElement[]

<xsd:union>

ユニオン メンバーの共通の親タイプ。

<xsi:nil> および <xsd:nillable> 属性

Java の null 値。

XML データ型が組み込みデータ型で通常は Java プリミティブ データ型 (intshort など) にマップされる場合、その XML データ型は実際には同等のオブジェクト ラッパー型 (java.lang.Integerjava.lang.Short など) にマップされる。

複合型の派生

Java の継承を使用してマップされる。

抽象型

抽象 Java データ型。


サポートされるユーザ定義の Java データ型

次の表に、jwsc および wsdlc Ant タスクでサポートされるユーザ定義の Java データ型と、それぞれに対応する XML スキーマ データ型をまとめます。

表 5-4 サポートされるユーザ定義の Java データ型

Java データ型 同等の XML スキーマ データ型

サポートされている任意のデータ型をプロパティとする JavaBean

JavaBean プロパティに対応する要素の <xsd:sequence> をコンテンツ モデルとする <xsd:complexType>

サポートされるすべてのデータ型の配列および多次元配列 (JavaBean プロパティとして使用する場合)

maxOccurs 属性が unbounded に設定されている <xsd:complexType> 内の要素。

java.lang.Object

注意 : 実行時オブジェクトのデータ型は既知の型でなければならない。

<xsd:anyType>

java.util.Collection

リテラル配列。

java.util.List

リテラル配列。

java.util.ArrayList

リテラル配列。

java.util.LinkedList

リテラル配列。

java.util.Vector

リテラル配列。

java.util.Stack

リテラル配列。

java.util.Set

リテラル配列。

java.util.TreeSet

リテラル配列。

java.utils.SortedSet

リテラル配列。

java.utils.HashSet

リテラル配列。


JAXB アノテーションを使用した Java-to-XML スキーマ マッピングのカスタマイズ

必要に応じて、JAXB アノテーションを使用して Java-to-XML スキーマ マッピングのデフォルト バインディング規則をオーバーライドすることができます。表 5-5 に、Java オブジェクトを XML にマッピングする方法を制御するために JWS ファイルに含めることができる JAXB マッピング アノテーションを示します。これらの各アノテーションは、javax.xml.bind.annotation パッケージ (http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/package-tree.html を参照) で利用できます。

表 5-5 JAXB マッピング アノテーション

アノテーション

説明

@XmlAccessorType

デフォルトでフィールドやプロパティをマップするかどうかを指定する。フィールドおよびプロパティのデフォルト シリアライゼーションの指定 (@XmlAccessorType アノテーション) を参照。

@XmlElement

クラスに格納されているプロパティを、格納しているクラスがマップされている XML スキーマの複合型のローカル要素へマップする。プロパティとローカル要素のマッピング (@XmlElement) を参照。

@XMLMimeType

image/jpeg など、プロパティの XML 表現を制御する MIME タイプとテキスト表現を関連付ける。MIME タイプの指定 (@XmlMimeType アノテーション) を参照。

@XmlRootElement

Web サービスの WSDL によって使用される XML スキーマのグローバル要素に最上位クラスをマップする。最上位クラスとグローバル要素のマッピング (@XmlRootElement) を参照。

@XmlSeeAlso

現在のクラスをバインディングする際に他のクラスをバインドする。複数のクラスのバインディング (@XmlSeeAlso) を参照。

@XmlType

XML スキーマ型にクラスまたは列挙型をマップする。値クラスとスキーマ型のマッピング (@XmlType) を参照。


以下の節に、サポートされている組み込みデータ型およびユーザ定義データ型の XML スキーマに対する Java オブジェクトのデフォルト マッピングを示します。

JAXB アノテーションの例

次に、JAXB アノテーションの例を示します。

@XmlRootElement(name = "ComplexService", namespace ="http://examples.org")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "basicStruct", propOrder = {
    "intValue",
    "stringArray",
    "stringValue"
)
public class BasicStruct {
    protected int intValue;
    @XmlElement(nillable = true)
    protected List<String> stringArray;
    protected String stringValue;
    public int getIntValue() {
        return intValue;
    }
    public void setIntValue(int value) {
        this.intValue = value;
    }
    public List<String> getStringArray() {
        if (stringArray == null) {
            stringArray = new ArrayList<String>();
        }
        return this.stringArray;
    }

    public String getStringValue() {
        return stringValue;
    }
    public void setStringValue(String value) {
        this.stringValue = value;
    }
}

フィールドおよびプロパティのデフォルト シリアライゼーションの指定 (@XmlAccessorType アノテーション)

@XmlAccessorType アノテーションは、フィールドやプロパティをデフォルトでマッピングするかどうかを指定します。このアノテーションは、以下の Java プログラム要素に対して指定できます。

  • パッケージ

  • 最上位クラス

@XmlAccessorType は、@XmlType (値クラスとスキーマ型のマッピング (@XmlType)) および @XmlRootElement (最上位クラスとグローバル要素のマッピング (@XmlRootElement)) アノテーションで指定されます。

次の表に、@XmlAccessorType アノテーションに渡すことができる省略可能な要素を示します。

表 5-6 @XMLAccessorType アノテーションの省略可能な要素

要素 説明

value

XMLAccessType.valuevalue を指定する。value は以下のいずれかの値。

  • FIELD — フィールドが XML にバインドされる。

  • PROPERTY — JavaBean プロパティ (ゲッター/セッターのペア) が XML にバインドされる。

  • PUBLIC_MEMBER — パブリック フィールドおよび JavaBean プロパティが XML にバインドされる。これがデフォルト。

  • NONE — フィールドも JavaBean プロパティも XML にバインドされない。


詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlAccessorType.html にある Javadoc の「javax.xml.bind.annotation.XmlAccessorType」を参照してください。例については、「JAXB アノテーションの例」を参照してください。

プロパティとローカル要素のマッピング (@XmlElement)

@XmlElement アノテーションは、クラスに格納されているプロパティを、格納しているクラスがマップされている XML スキーマの複合型のローカル要素へマップします。このアノテーションは、以下の Java プログラム要素に対して指定できます。

  • JavaBean プロパティ

  • 非静的な永続フィールド

次の表に、@XmlElement アノテーションに渡すことができるアノテーション要素を示します。

表 5-7 @XMLElement アノテーションの省略可能な要素

要素 説明

name

JavaBean のプロパティを表す XML 要素のローカル名。この要素のデフォルトは、JavaBean プロパティ名。

namespace

JavaBean のプロパティを表す XML 要素のネームスペース。デフォルトのネームスペースは、格納しているクラスのネームスペースから派生する。

nillable

null を許容するように要素宣言をカスタマイズする。


詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlElement.html にある Javadoc の「javax.xml.bind.annotation.XmlElement」を参照してください。

MIME タイプの指定 (@XmlMimeType アノテーション)

@XmlMimeType アノテーションは、プロパティの XML 表現を制御する MIME タイプを指定します。このアノテーションは、XML の xsd:base64Binary バイナリにバインドされる ImageSource などのデータ型に対して指定できます。

次の表に、@XmlMimeType アノテーションに渡すことができる必須の要素を示します。

表 5-8 @XMLMimeType アノテーションの必須要素

要素 説明

value

image/jpegtext/xml など、MIME タイプのテキスト表現を指定する。


詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlMimeType.html にある Javadoc の「javax.xml.bind.annotation.XmlMimeType」を参照してださい。

最上位クラスとグローバル要素のマッピング (@XmlRootElement)

@XmlRootElement アノテーションは、Web サービスの WSDL によって使用される XML スキーマのグローバル要素に最上位クラスをマップします。このアノテーションは、以下の Java プログラム要素に対して指定できます。

  • 最上位クラス

  • 列挙型

@XmlRootElement は、@XmlType (値クラスとスキーマ型のマッピング (@XmlType)) および @XmlAccessorType(フィールドおよびプロパティのデフォルト シリアライゼーションの指定 (@XmlAccessorType Annotation)) アノテーションで指定されます。

次の表に、@XmlRootElement アノテーションに渡すことができる省略可能な要素を示します。

表 5-9 @XmlRootElement アノテーションの省略可能な要素

要素 説明

name

XML 要素のローカル名。この要素のデフォルトはクラス名。

namespace

XML 要素のネームスペース。デフォルトのネームスペースは、クラスのパッケージから派生する。


詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlRootElement.html にある Javadoc の「javax.xml.bind.annotation.XmlRootElement」を参照してください。例については、「JAXB アノテーションの例」を参照してください。

複数のクラスのバインディング (@XmlSeeAlso)

@XmlSeeAlso アノテーションは、現在のクラスをバインドする際にクラスのリストをバインドします。次の表に、@XMLRootElement アノテーションに渡すことができる省略可能な要素を示します。

表 5-10 @XmlSeeAlso アノテーションの省略可能な要素

要素 説明

value

現在のクラスをバインドする際に JAXB で使用されるクラスのリスト。


値クラスとスキーマ型のマッピング (@XmlType)

@XmlType アノテーションは、クラスまたは列挙型を XML スキーマ型にマップします。型は単純型または複合型の場合があります。このアノテーションは、以下の Java プログラム要素に対して指定できます。

  • 最上位クラス

  • 列挙型

@XmlType は、@XmlRootElement (最上位クラスとグローバル要素のマッピング (@XmlRootElement)) および @XmlAccessorType (フィールドおよびプロパティのデフォルト シリアライゼーションの指定 (@XmlAccessorType Annotation)) アノテーションで指定されます。

次の表に、@XmlType アノテーションに渡すことができる省略可能な要素を示します。

表 5-11 @XmlType アノテーションの省略可能な要素

要素 説明

name

クラスのマップ先の XML スキーマ型の名前。

namespace

XML スキーマ型の対象ネームスペースの名前。デフォルトは、クラスを格納しているパッケージがマップされる対象ネームスペース。

propOrder

クラスで定義されている JavaBean プロパティ名のリスト。このリストは、クラスが XML スキーマの複合型へマップされる際の XML スキーマ要素の順番を定義する。リスト内の各名前は、JavaBean プロパティの Java 識別子の名前。すべての JavaBean プロパティをリストする必要がある。


詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlType.html にある Javadoc の「javax.xml.bind.annotation.XmlType」を参照してください。例については、「JAXB アノテーションの例」を参照してください。

バインディング宣言を使用した XML Schema-to-Java マッピングのカスタマイズ

WSDL ファイルの分散的特性から、現在のアプリケーションの要件を満たすためにその中身を常に制御または変更できるとは限りません。たとえば、WSDL ファイルを所有していなかったり、パートナがすでに使用している場合は、変更を加えるのは非現実的または不可能です。

WSDL ファイルを直接編集できない場合、カスタム バインディング宣言を指定することによって、WSDL コンポーネントが Java オブジェクトへマップされる方法をカスタマイズすることができます。バインディング宣言を使用すると、非同期性、ラッパー形式など、特定の機能を制御したり、XML スキーマのカスタマイズにより生成される JAXB データ バインディング アーティファクトを制御することもできます。

バインディング宣言は以下のいずれかの方法で定義することができます。

選択する方法に関係なく、どのバインディング宣言も意味的には同じです。

カスタム バインディング宣言は、次の図に示すようにスコープに関連付けられます。

図 5-2 カスタム バインディング宣言のスコープ

図 5-2 の説明は図の下のリンクをクリックしてください。
「図 5-2 カスタム バインディング宣言のスコープ」の説明

次の表で、各スコープの意味を説明します。

図 5-12 カスタム バインディング宣言のスコープ

スコープ 定義

グローバル スコープ

グローバル スコープのカスタマイズ値を表す。次に具体的に示す。

  • JAX-WS バインディング宣言の場合、ルート要素の一部として定義されるカスタマイズ値を表す。「ルート要素の指定」を参照。

  • JAXB アノテーションの場合、<globalBindings> バインディング宣言内に格納されるカスタマイズ値を表す。グローバル スコープの値は、ソース スキーマのすべてのスキーマ要素の他に、含まれる、またはインポートされるあらゆるスキーマに適用される。

スキーマ スコープ

<schemaBindings> バインディング宣言内に格納される JAXB カスタマイズ値を表す。スキーマ スコープの値は、スキーマの対象ネームスペース内の要素に適用される。

注意 : このスコープが適用されるのは JAXB バインディング宣言のみ。

定義スコープ

グローバル宣言または型定義のバインディング宣言で定義される JAXB カスタマイズ値を表す。定義スコープの値は、グローバル宣言または型定義を参照する要素に適用される。

注意 : このスコープが適用されるのは JAXB バインディング宣言のみ。

コンポーネント スコープ

アノテーションが付けられたスキーマ要素または WSDL に適用されるカスタマイズ値を表す。


カスタム バインディング宣言のスコープは、以下の継承およびオーバーライド規則に準拠します。

以下の節では、カスタム バインディング宣言の作成方法と、標準のカスタム バインディング宣言について説明します。

カスタム バインディング宣言の使用に関する詳細については、以下を参照してください。

外部バインディング宣言ファイルの作成

特定の WSDL または XML スキーマ ドキュメントのすべてのバインディング宣言を格納する外部のバインディング宣言ファイルを作成します。次に、バインディング宣言ファイルを wsdlcjwsc、または clientgen Ant タスクの <binding> 子要素に渡します。

以降の節で説明する内容は、次のとおりです。

JAX-WS バインディング宣言を使用した外部バインディング宣言ファイルの作成

以下の節では、JAX-WS バインディング宣言ファイルのルート要素および子要素の指定方法について説明します。定義可能なカスタム バインディング宣言については、「JAX-WS カスタム バインディング宣言」を参照してください。

ルート要素の指定

jaxws:bindings 宣言は、その他すべてのバインディング宣言のルートであり、WSDL ファイルの場所および XML スキーマが従うネームスペース http://java.sun.com/xml/ns/jaxws を定義します。

ルート宣言は次の形式で指定します。

<jaxws:bindings
    wsdlLocation="uri_of_wsdl"
    jaxws:xmlns="http://java.sun.com/xml/ns/jaxws">

uri_of_wsdl に WSDL ファイルの URI を指定します。

表 5-5 で定義しているパッケージ、ラッパー形式、および非同期性マッピングのカスタマイズは、外部カスタマイズ ファイルにおけるルート バインディング宣言の一部として「グローバル」に定義できます。グローバル バインディングは、wsdlLocation 属性によって参照される WSDL 内の wsdl:definition のスコープ全体に適用されます。

次に、パッケージ名、ラッパー形式、非同期マッピングのカスタマイズを定義するルート バインディング要素の例を示します。

<jaxws:bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL"
  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
    <package name="example.webservices.simple.simpleservice">
    <enableWrapperStyle>true</enableWrapperStyle>
    <enableAsyncMapping>false</enableAsyncMapping>
</jaxws:bindings>
子要素の指定

ルートの jaxws:bindings 要素には、子要素を含めることができます。カスタマイズしている WSDL ノードは、node 属性で XPath 式を渡すことによって指定します。

コンパイルされた WSDL ファイル内に埋め込まれた XML スキーマは、標準の JAXB バインディングを使用してカスタマイズすることができます。詳細については、JAX-WS WSDL Customizations (https://jax-ws.dev.java.net/nonav/2.1.2m1/docs/customizations.html) の「XML Schema Customization」を参照してください。定義可能なカスタム JAXB バインディング宣言については、「JAXB カスタム バインディング宣言」を参照してください。

たとえば、次の例では、WSDL ドキュメントの wsdl:definitions ノードのパッケージ名を examples.webservices.complex.complexservice として定義しています。

<jaxws:bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL
  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
  <jaxws:bindings node="wsdl:definitions" 
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <jaxws:package name="examples.webservices.simple.simpleservice"/>
</bindings>

JAXB バインディング宣言を使用した外部バインディング宣言ファイルの作成

JAXB バインディング宣言ファイルは、ネームスペース http://java.sun.com/xml/ns/jaxb の XML スキーマに従う XML ドキュメントです。以下の節では、JAXB バインディング宣言ファイルのルート要素および子要素の指定方法について説明します。定義可能なカスタム バインディング宣言については、「JAXB カスタム バインディング宣言」を参照してください。

ルート要素の指定

jaxws:bindings 宣言は、その他すべてのバインディング宣言のルートであり、ルート宣言は次の形式で指定します。

<jaxb:bindings
    schemaLocation="uri_of_schema">

uri_of_schema に XML スキーマ ファイルの URI を指定します。

子要素の指定

ルートの jaxb:bindings 要素には、子要素を含めることができます。カスタマイズしているスキーマ ノードは、node 属性で XPath 式を渡すことによって指定します。

たとえば、次の例では、パッケージ名を examples.webservices.simple.simpleservice として定義しています。

<jaxb:bindings
   schemaLocation="simpleservice.xsd">
   <jaxb:bindings node="//xs:simpleType[@name='value1']">
       <jaxb:package name="examples.webservices.simple.simpleservice"/>
   </jaxb:bindings>
</jaxb:bindings>

バインディング宣言の埋め込み

バインディング宣言は、以下のいずれかの方法で WSDL ファイルに埋め込むことができます。

WSDL ファイルへの JAX-WS または JAXB バインディング宣言の埋め込み

バインディング宣言は、WSDL 拡張として jaxws:bindings 要素を使用して WSDL ファイルに埋め込むことができます。定義可能なカスタム バインディング宣言については、「JAX-WS カスタム バインディング宣言」を参照してください。

たとえば、次の例では、SimpleServiceImpl サービス エンドポイント インタフェース (またはポート) のクラス名を SimpleService として定義しています。

<wsdl:portType name="SimpleServiceImpl">
     <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
            <jaxws:class name="SimpleService"/>
     </jaxws:bindings>
</wsdl:portType>

このバインディング宣言を指定しなかった場合、サービス エンドポイント インタフェースのデフォルト クラス名は、wsdl:portType 名、すなわち SimpleServiceImpl に設定されます。

コンパイルされた WSDL ファイル内に埋め込まれた XML スキーマは、標準の JAXB バインディングを使用してカスタマイズすることができます。詳細については、JAX-WS WSDL Customizations (https://jax-ws.dev.java.net/nonav/2.1.2m1/docs/customizations.html) の「XML Schema Customizations」を参照してください。定義可能なカスタム JAXB バインディング宣言については、「JAXB カスタム バインディング宣言」を参照してください。

XML スキーマへの JAXB バインディング宣言の埋め込み

JAXB カスタム宣言は、次に示すように XML スキーマの <appinfo> 要素内に埋め込むことができます。

<xs:annotation>
    <xs:appinfo>
        <binding declaration>
    </xs:appinfo>
</xs:annotation>

たとえば、次の例では、スキーマのパッケージ名を定義しています。

<schema xmlns="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.w3.org/2001/XMLSchema"
    xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
    jaxb:version="2.0">
    <annotation>
        <appinfo>
           <jaxb:schemaBindings>
            <jaxb:package name="example.webservices.simple.simpleservice"/>
           </jaxb:schemaBindings>
        </appinfo>
    </annotation>
</schema>

JAX-WS カスタム バインディング宣言

次の表に、一般的な JAX-WS のカスタマイズをまとめます。JAX-WS カスタム バインディング宣言の完全なリストについては、https://jax-ws.dev.java.net/nonav/2.1.2/docs/customizations.html にある「JAX-WS WSDL Customization」を参照してください。

表 5-13 JAX-WS カスタム バインディング宣言

カスタマイズ 説明

パッケージ名

パッケージ名の定義には、jaxws:package バインディング宣言を使用する。

このカスタマイズを指定しない場合、wsdlc Ant タスクが、WSDL の targetNamespace に基づいてパッケージ名を生成する。このデータ バインディングのカスタマイズは、wsdlcjwsc、または clientgen Ant タスクの packageName 属性によってオーバーライドされる。詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「wsdlc」を参照してください。

このバインディング宣言は、「外部バインディング宣言ファイルの作成」で説明するようにルート バインディング要素の一部として指定したり、次の例で示すように wsdl:definitions ノード上で指定することができる。

<bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation=
  "http://localhost:7001/simple/SimpleService?WSDL"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions" 
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <package name="example.webservices.simple.simpleService"/>
</bindings>

ラッパー形式規則

WSDL オペレーションのパラメータや戻り値の型の生成方法を制御するラッパー形式規則を有効化または無効化するには、jaxws:enablesWrapperStyle バインディング宣言を使用する。

このバインディング宣言は、「外部バインディング宣言ファイルの作成」で説明するようにルート バインディング要素の一部として指定したり、以下のいずれかのノード上で指定することができる。

  • wsdl:definitions — すべての wsdl:portType 属性のすべての wsdl:operations に適用される。

  • wsdl:portTypewsdl:portType 内のすべての wsdl:operations に適用される。

  • wsdl:operationwsdl:operation にのみ適用される。

次の例では、wsdl:definitions ノードのラッパー形式規則を無効化している。

<bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions" 
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <enableWrapperStyle>
       false
    </enableWrapperStyle>
</bindings>

非同期性

WSDL ファイルのコンパイル時に clientgen Ant タスクに、通常の同期メソッドとともに非同期のポーリング オペレーションおよびコールバック オペレーションを生成させるには、jaxws:enableAsycMapping バインディング宣言を使用する。

このバインディング宣言は、「外部バインディング宣言ファイルの作成」で説明するようにルート バインディング要素の一部として指定したり、以下のいずれかのノード上で指定することができる。

  • wsdl:definitions — すべての wsdl:portType 属性のすべての wsdl:operations に適用される。

  • wsdl:portTypewsdl:portType 内のすべての wsdl:operations に適用される。

  • wsdl:operationwsdl:operation にのみ適用される。

次の例では、非同期のポーリング オペレーションおよびコールバック オペレーションを無効化している。

<bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions" 
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <enableAsyncMapping>
       false
    </enableAsyncMapping>
</bindings>

プロバイダ

プロバイダ インタフェースとして一部をマークするには、jaxws:provider バインディング宣言を使用する。このバインディング宣言は、wsdl:portType の一部として指定できる。このバインディング宣言は、WSDL ファイルから開始するサービスの開発時に適用される。

クラス名

クラス名の定義には、jaxws:class バインディング宣言を使用する。このバインディング宣言は、以下のいずれかのノードに対して指定できる。

  • wsdl:portType — インタフェース クラス名を定義する。

  • wsdl:fault — フォールト クラス名を定義する。

  • soap:headerfault — 例外クラス名を定義する。

  • wsdl:service — 実装クラス名を定義する。

次の例では、実装クラスのクラス名を定義している。

<bindings node="wsdl:definitions/wsdl:service[@name='SimpleService']">
    <class name="myService"></class> 
</bindings>

メソッド名

生成された Service クラスのポート アクセサ メソッドまたはサービス エンドポイント インタフェースの生成された Java メソッドの名前をカスタマイズするには、jaxws:method バインディング宣言を使用する。

次の例では、wsdl:operation EchoHello の Java メソッド名を定義している。

<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
    <method name="Greeting"></method> 
</bindings>

Java パラメータ名

生成された Java メソッドのパラメータ名をカスタマイズするには、jaxws:parameter バインディング宣言を使用する。この宣言を使用すると、wsdl:portTypewsdl:operation のメソッド パラメータを変更できる。

次の例では、wsdl:operation echoHello の Java メソッド名を定義している。

<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
    <parameter part="definitions/message[@name='EchoHello']/
    part[@name='parameters']" element="hello"
    name="greeting"/> 
</bindings>

Javadoc

パッケージ、クラス、またはメソッドの Javadoc テキストを指定するには、jaxws:javadoc バインディング宣言を使用する。

たとえば、次の例では、メソッド レベルで Javadoc を定義している。

<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
    <method name="Hello">
       <javadoc>Prints hello.</javadoc>
    </method> 
</bindings>

ハンドラ チェーン

ハンドラをカスタマイズまたは追加するには、javaee:handlerchain バインディング宣言を使用する。インライン ハンドラは、Web Services Metadata for the Java Platform 仕様 (JSR) (http://www.jcp.org/en/jsr/detail?id=181) で定義されているハンドラ チェーン コンフィグレーションに従う必要がある。


JAXB カスタム バインディング宣言

次の表に、一般的な JAXB のカスタマイズをまとめます。


注意 :

次の表には、開始時に役立つ JAXB カスタム バインディング宣言のみをまとめています。すべての JAXB カスタム バインディング宣言の完全なリストと説明については、JAXB 仕様、または、Sun Java EE 5 Tutorial の 「Customizing JAXB Bindings」(http://jcp.org/en/jsr/detail?id=222) を参照してください。

表 5-14 JAXB カスタム バインディング宣言

カスタマイズ 説明

グローバル バインディング

グローバル スコープでバインディング宣言を定義するには、<globalBindings> バインディング宣言を使用する (図 5-2 を参照)。

<globalBindings> バインディング宣言には属性および要素を指定することができる。たとえば、以下のバインディング宣言では次の属性および要素を定義している。

  • collectionType 属性 : java.util.List インタフェースを実装し、生成される実装内のすべてのリストを表すために使用される型クラス myArray を指定する。

  • generateIsSetMethod 属性 : ゲッターおよびセッター プロパティ メソッドに対応する isSet() メソッドを生成する。

  • javaType 要素 : XML スキーマのアトミック データ型と Java データ型 (組み込みデータ型またはアプリケーション固有のデータ型) のバインディングをカスタマイズする。

<jaxb:globalBindings
    collectionType ="java.util.myArray"
    generateIsSetMethod="false">
    <jaxb:javaType name="java.util.Date"
        xmlType="xsd:date"
    </jaxb:javaType>
</jaxb:globalBindings>

スキーマ バインディング

スキーマ スコープでバインディング宣言を定義するには、<schemaBindings> バインディング宣言を使用する (図 5-2 を参照)。

例として、次の表の「パッケージ名」に関する説明を参照してください。

パッケージ名

スキーマのパッケージ名を定義するには、<schemaBindings> バインディング宣言の <package> 要素を使用する (表 5-12 を参照)。

このカスタマイズを指定しない場合、wsdlc Ant タスクが、WSDL の targetNamespace に基づいてパッケージ名を生成する。このデータ バインディングのカスタマイズは、wsdlcjwsc、または clientgen Ant タスクの packageName 属性によってオーバーライドされる。詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「wsdlc」を参照してください。

たとえば、次の例では、simpleservice.xsd ファイルから生成されるすべての JAXB クラスのパッケージ名を定義している。

<jaxb:bindings
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   schemaLocation="simpleservice.xsd"
   node="/xs:schema">
   <jaxb:schemaBindings>
      <jaxb:package name="examples.jaxb"/>
   </jaxb:schemaBindings>
</jaxb:bindings>

次に、インポートされた XML スキーマのパッケージ名を定義する方法を示す。

<jaxb:bindindgs
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    node="//xs:schema/xs:import[@namespace='http://examples.webservices.org/complexservice']">
    <jaxb:schemaBindings>
        <jaxb:package name="examples.jaxb"/>
        </jaxb:schemaBindings>
    </jaxb:bindings>

クラス名

スキーマ要素のクラス名を定義するには、<class> バインディング宣言を使用する。

次の例では、xsd:complexType のクラス名を定義している。

<xs:complexType name="ComplexType">
    <xs:annotation><xs:appinfo>
           <jaxb:javadoc>This is my class.</jaxb:javadoc>
       </jaxb:class>
    </xs:appinfo></xs:annotation>
</xs:complexType>

Java プロパティ名

スキーマ要素のプロパティ名を定義するには、<property> バインディング宣言を使用する。

次の例では、Java プロパティ名を定義する方法について説明します。

<jaxb:bindindgs
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    node="//xs:schema/">
    <jaxb:schemaBindings>
        <jaxb:property generateIsSetMethod="true"/> 
    </jaxb:schemaBindings>
</jaxb:bindings>

Java データ型

XML スキーマのアトミック データ型と Java データ型 (組み込みデータ型またはアプリケーション固有のデータ型) のバインディングをカスタマイズするには、<javaType> バインディング宣言を使用する。

たとえば、グローバル バインディング (上記の) を参照してください。

Javadoc

要素の Javadoc を指定するには、<class> または <property> バインディング宣言の <javadoc> 子要素を使用する。

次に例を示す。

<xs:complexType name="ComplexType">
    <xs:annotation><xs:appinfo>
<jaxb:class name="MyClass"> 
           <jaxb:javadoc>This is my class.</jaxb:javadoc>
       </jaxb:class>
    </xs:appinfo></xs:annotation>
</xs:complexType>