Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS を使用した Web サービス入門 11g リリース 1 (10.3.1) B55565-01 |
|
![]() 戻る |
![]() 次へ |
以下の節では、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 のデータ バインディング プロセスを示します。
この図に示すように、JAXB のデータ バインディング プロセスは、以下のタスクから構成されます。
バインド - XML スキーマを「スキーマ派生の JAXB Java クラス」または値クラスにバインドします。各クラスは、一連の JavaBean スタイルのアクセス メソッド (get
および set
メソッド) を介してコンテンツへのアクセスを提供します。バインディングは、JAXB の「スキーマ コンパイラ」によって管理されます。
アンマーシャリング - XML ドキュメントを変換し、Java プログラムの要素やオブジェクトのツリーを作成します。このツリーは、そのドキュメントのコンテンツおよび構成を表し、独自の Java コードでアクセスできます。コンテンツ ツリーでは、複合型は値クラスへマップされます。属性の宣言や要素 (単純型) は、値クラス内のプロパティまたはフィールドへマップされ、それらの値にアクセスするには get および set メソッドを使用します。アンマーシャリングは、JAXB の「バインディング フレームワーク」によって管理されます。
マーシャリング - Java オブジェクトを XML コンテンツへ変換する。この場合、WSDL オペレーションとしてデプロイされている Java メソッドによって、wsdl:types
セクション内のスキーマ コンポーネントが特定されます。マーシャリングは、JAXB のバインディング フレームワークによって管理されます。
JAXB バインディング言語を使用すると、カスタム バインディング宣言を定義したり、JAXB アノテーションを指定して XML と Java 間のデータ変換を制御することができます。
以降の節で説明する内容は、次のとおりです。
JAXB データ バインディング アーティファクトの開発 - WebLogic Server で JAXB データ バインディング アーティファクトを開発する方法を説明します。
標準データ型のマッピング - サポートされる標準の組み込みデータ型およびユーザ定義データ型について説明します。
JAXB アノテーションを使用した Java-to-XML スキーマ マッピングのカスタマイズ - JWS ファイルで JAXB アノテーションを使用して Java-to-XML スキーマ マッピングを制御およびカスタマイズする方法について説明します。
バインディング宣言を使用した XML Schema-to-Java マッピングのカスタマイズ - 別のファイルや埋め込みインラインで定義されているバインディング宣言を使用して、XML Schema-to-Java マッピングを制御およびカスタマイズする方法について説明します。
WebLogic Server で JAXB データ バインディング アーティファクトを開発する手順は、Java クラス ファイルと WSDL のどちらから開始するかによって異なります。
Java からの開始 : このプログラミング モデルを使用する場合、Java クラスを作成します。JAXB は実行時に Java オブジェクトを「マーシャリング」して XML コンテンツを生成し、この XML コンテンツが SOAP メッセージ内にパッケージ化され、Web サービスの要求または応答として送信されます。
Java-to-XML マッピングを制御するには、「JAXB アノテーションを使用した Java-to-XML スキーマ マッピングのカスタマイズ」を参照し、JWS ファイル内に JAXB アノテーションを含めます。カスタマイズが不要な場合、「組み込みデータ型の Java-to-XML マッピング」および「サポートされるユーザ定義の Java データ型」を参照し、JAXB は標準の組み込みデータ型およびユーザ定義データ型のマッピングを使用します。
このプログラミング モデルの詳細については、「Java から開始する WebLogic Web サービスの開発 : 主な手順」を参照してください。
WSDL からの開始 : このプログラミング モデルを使用する場合、XML スキーマが存在し、JAXB は XML ドキュメントを「アンマーシャリング」して Java オブジェクトを生成します。
XML-to-Java マッピングを制御するには、「バインディング宣言を使用した XML Schema-to-Java マッピングのカスタマイズ」を参照し、WSDL または XML スキーマ内、あるいは外部ファイル内にカスタム バインディング宣言を定義します。カスタマイズが不要な場合、「組み込みデータ型の XML-to-Java マッピング」および「サポートされるユーザ定義の XML データ型」を参照し、標準の組み込みデータ型およびユーザ定義データ型のマッピングを使用します。
このプログラミング モデルの詳細については、「WSDL ファイルから開始する WebLogic Web サービスの開発 : 主な手順」を参照してください。
こららの手順で説明している jwsc
、wsdlc
、または clientgen
Ant タスクを呼び出す場合、以下の点に注意する必要があります。
JAX-WS Web サービスおよび JAXB バインディング アーティファクトを生成するには、type="JAXWS"
属性を指定する必要がある。jwsc
では、<jws>
子要素の一部として type 属性を指定します。
必要に応じて、<binding>
子要素を指定し、JAX-WS および JAXB のデータ バインディングのカスタマイズ情報を格納するカスタマイズ ファイルを指定することができる。カスタマイズ ファイルの作成については、「バインディング宣言を使用した XML Schema-to-Java マッピングのカスタマイズ」を参照してください。カスタマイズが不要な場合、「標準データ型のマッピング」を参照して、JAXB は標準の組み込みデータ型およびユーザ定義データ型のマッピングを使用します。
jwsc
、wsdlc
、または 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 サービスのオペレーションで使用できます。組み込みデータ型には、integer
、string
、time
などがあります。
また、Web サービスの入力パラメータや戻り値として、さまざまなユーザ定義の XML および Java データ型を使用できます。ユーザ定義のデータ型には、XML スキーマや Java の構成要素から作成する <xsd:complexType>
や JavaBean などがあります。jwsc
や clientgen
などの 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 スキーマ データ型 (ターゲット ネームスペース http://www.w3.org/2001/XMLSchema
) と、それぞれに対応する Java データ型をアルファベット順に示します。サポートされるユーザ定義の XML データ型については、「組み込みデータ型の Java-to-XML マッピング」を参照してください。
表 5-1 XML スキーマの組み込みデータ型と Java データ型のマッピング
XML スキーマ データ型 | Java データ型 (小文字はプリミティブ データ型を示す) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
次の例は JAXB 仕様からの抜粋ですが、デフォルトの XML-to-Java バインディングの例を示しています。
<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>
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 データ型と、それぞれに対応する XML スキーマ データ型をアルファベット順に示します。サポートされるユーザ定義の Java データ型については、「サポートされるユーザ定義の Java データ型」を参照してください。
表 5-2 Java データ型と XML スキーマ データ型のマッピング
Java データ型 (小文字はプリミティブ データ型を示す) | XML スキーマ データ型 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
以降の節の表には、jwsc
および wsdlc
Ant タスクでデータ バインディング アーティファクトを自動的に生成できるユーザ定義の XML データ型および Java データ型 (対応する Java 表現または XML 表現など) をまとめます。
これらの表にない XML データ型または Java データ型で、「サポートされる組み込みデータ型」の表に示した組み込みデータ型でもない型の場合は、ユーザ定義データ型のアーティファクトを手動で作成する必要があります。
次の表に、jwsc
および wsdlc
Ant タスクでサポートされる XML スキーマ データ型と、それぞれに対応する Java データ型またはマッピング メカニズムをまとめます。
表 5-3 サポートされているユーザ定義の XML スキーマ データ型
XML スキーマ データ型 | 同等の Java データ型またはマッピング メカニズム |
---|---|
単純型および複合型の両方の要素を持つ |
JavaBeans。 |
単純なコンテンツを含む |
JavaBeans。 |
|
JavaBeans のプロパティ。 |
既存の単純型の制限による新しい単純型の派生 |
同等の単純型の Java データ型。 |
制限要素で使用されるファセット |
シリアライゼーションおよびデシリアライゼーションで強制されないファセット。 |
|
リスト データ型の配列。 |
|
|
制限によって |
同等の Java データ型の配列。 |
単純型からの複合型の派生 |
|
|
|
|
|
|
|
|
ユニオン メンバーの共通の親タイプ。 |
|
Java の XML データ型が組み込みデータ型で通常は Java プリミティブ データ型 ( |
複合型の派生 |
Java の継承を使用してマップされる。 |
抽象型 |
抽象 Java データ型。 |
次の表に、jwsc
および wsdlc
Ant タスクでサポートされるユーザ定義の Java データ型と、それぞれに対応する XML スキーマ データ型をまとめます。
表 5-4 サポートされるユーザ定義の Java データ型
Java データ型 | 同等の XML スキーマ データ型 |
---|---|
サポートされている任意のデータ型をプロパティとする JavaBean |
JavaBean プロパティに対応する要素の |
サポートされるすべてのデータ型の配列および多次元配列 (JavaBean プロパティとして使用する場合) |
|
注意 : 実行時オブジェクトのデータ型は既知の型でなければならない。 |
|
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
|
リテラル配列。 |
必要に応じて、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 アノテーション) を参照。 |
|
クラスに格納されているプロパティを、格納しているクラスがマップされている XML スキーマの複合型のローカル要素へマップする。プロパティとローカル要素のマッピング (@XmlElement) を参照。 |
|
|
|
Web サービスの WSDL によって使用される XML スキーマのグローバル要素に最上位クラスをマップする。最上位クラスとグローバル要素のマッピング (@XmlRootElement) を参照。 |
|
現在のクラスをバインディングする際に他のクラスをバインドする。複数のクラスのバインディング (@XmlSeeAlso) を参照。 |
|
XML スキーマ型にクラスまたは列挙型をマップする。値クラスとスキーマ型のマッピング (@XmlType) を参照。 |
以下の節に、サポートされている組み込みデータ型およびユーザ定義データ型の XML スキーマに対する Java オブジェクトのデフォルト マッピングを示します。
次に、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
アノテーションは、フィールドやプロパティをデフォルトでマッピングするかどうかを指定します。このアノテーションは、以下の Java プログラム要素に対して指定できます。
パッケージ
最上位クラス
@XmlAccessorType
は、@XmlType
(値クラスとスキーマ型のマッピング (@XmlType)) および @XmlRootElement
(最上位クラスとグローバル要素のマッピング (@XmlRootElement)) アノテーションで指定されます。
次の表に、@XmlAccessorType
アノテーションに渡すことができる省略可能な要素を示します。
表 5-6 @XMLAccessorType アノテーションの省略可能な要素
要素 | 説明 |
---|---|
|
|
詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlAccessorType.html
にある Javadoc の「javax.xml.bind.annotation.XmlAccessorType
」を参照してください。例については、「JAXB アノテーションの例」を参照してください。
@XmlElement
アノテーションは、クラスに格納されているプロパティを、格納しているクラスがマップされている XML スキーマの複合型のローカル要素へマップします。このアノテーションは、以下の Java プログラム要素に対して指定できます。
JavaBean プロパティ
非静的な永続フィールド
次の表に、@XmlElement
アノテーションに渡すことができるアノテーション要素を示します。
表 5-7 @XMLElement アノテーションの省略可能な要素
要素 | 説明 |
---|---|
|
JavaBean のプロパティを表す XML 要素のローカル名。この要素のデフォルトは、JavaBean プロパティ名。 |
|
JavaBean のプロパティを表す XML 要素のネームスペース。デフォルトのネームスペースは、格納しているクラスのネームスペースから派生する。 |
|
null を許容するように要素宣言をカスタマイズする。 |
詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlElement.html
にある Javadoc の「javax.xml.bind.annotation.XmlElement
」を参照してください。
@XmlMimeType
アノテーションは、プロパティの XML 表現を制御する MIME タイプを指定します。このアノテーションは、XML の xsd:base64Binary
バイナリにバインドされる Image
や Source
などのデータ型に対して指定できます。
次の表に、@XmlMimeType
アノテーションに渡すことができる必須の要素を示します。
詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlMimeType.html
にある Javadoc の「javax.xml.bind.annotation.XmlMimeType
」を参照してださい。
@XmlRootElement
アノテーションは、Web サービスの WSDL によって使用される XML スキーマのグローバル要素に最上位クラスをマップします。このアノテーションは、以下の Java プログラム要素に対して指定できます。
最上位クラス
列挙型
@XmlRootElement
は、@XmlType
(値クラスとスキーマ型のマッピング (@XmlType)) および @XmlAccessorType
(フィールドおよびプロパティのデフォルト シリアライゼーションの指定 (@XmlAccessorType Annotation)) アノテーションで指定されます。
次の表に、@XmlRootElement
アノテーションに渡すことができる省略可能な要素を示します。
表 5-9 @XmlRootElement アノテーションの省略可能な要素
要素 | 説明 |
---|---|
|
XML 要素のローカル名。この要素のデフォルトはクラス名。 |
|
XML 要素のネームスペース。デフォルトのネームスペースは、クラスのパッケージから派生する。 |
詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/bind/annotation/XmlRootElement.html
にある Javadoc の「javax.xml.bind.annotation.XmlRootElement
」を参照してください。例については、「JAXB アノテーションの例」を参照してください。
@XmlSeeAlso
アノテーションは、現在のクラスをバインドする際にクラスのリストをバインドします。次の表に、@XMLRootElement
アノテーションに渡すことができる省略可能な要素を示します。
@XmlType
アノテーションは、クラスまたは列挙型を XML スキーマ型にマップします。型は単純型または複合型の場合があります。このアノテーションは、以下の Java プログラム要素に対して指定できます。
最上位クラス
列挙型
@XmlType
は、@XmlRootElement
(最上位クラスとグローバル要素のマッピング (@XmlRootElement)) および @XmlAccessorType
(フィールドおよびプロパティのデフォルト シリアライゼーションの指定 (@XmlAccessorType Annotation)) アノテーションで指定されます。
次の表に、@XmlType
アノテーションに渡すことができる省略可能な要素を示します。
表 5-11 @XmlType アノテーションの省略可能な要素
要素 | 説明 |
---|---|
|
クラスのマップ先の XML スキーマ型の名前。 |
|
XML スキーマ型の対象ネームスペースの名前。デフォルトは、クラスを格納しているパッケージがマップされる対象ネームスペース。 |
|
クラスで定義されている 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 アノテーションの例」を参照してください。
WSDL ファイルの分散的特性から、現在のアプリケーションの要件を満たすためにその中身を常に制御または変更できるとは限りません。たとえば、WSDL ファイルを所有していなかったり、パートナがすでに使用している場合は、変更を加えるのは非現実的または不可能です。
WSDL ファイルを直接編集できない場合、カスタム バインディング宣言を指定することによって、WSDL コンポーネントが Java オブジェクトへマップされる方法をカスタマイズすることができます。バインディング宣言を使用すると、非同期性、ラッパー形式など、特定の機能を制御したり、XML スキーマのカスタマイズにより生成される JAXB データ バインディング アーティファクトを制御することもできます。
バインディング宣言は以下のいずれかの方法で定義することができます。
特定の WSDL または XML スキーマ ドキュメントのすべてのバインディング宣言を格納する外部のバインディング宣言ファイルを作成する。「外部バインディング宣言ファイルの作成」を参照。
注意 : カスタマイズが必要な場合、WSDL または XML スキーマ ドキュメントからカスタマイズを分離し、この方法で柔軟性を保つことをお勧めします。 |
WSDL または XML スキーマ ドキュメント内にバインディング宣言を埋め込む。「バインディング宣言の埋め込み」を参照してください。
選択する方法に関係なく、どのバインディング宣言も意味的には同じです。
カスタム バインディング宣言は、次の図に示すようにスコープに関連付けられます。
次の表で、各スコープの意味を説明します。
図 5-12 カスタム バインディング宣言のスコープ
スコープ | 定義 |
---|---|
グローバル スコープ |
グローバル スコープのカスタマイズ値を表す。次に具体的に示す。
|
スキーマ スコープ |
注意 : このスコープが適用されるのは JAXB バインディング宣言のみ。 |
定義スコープ |
グローバル宣言または型定義のバインディング宣言で定義される JAXB カスタマイズ値を表す。定義スコープの値は、グローバル宣言または型定義を参照する要素に適用される。 注意 : このスコープが適用されるのは JAXB バインディング宣言のみ。 |
コンポーネント スコープ |
アノテーションが付けられたスキーマ要素または WSDL に適用されるカスタマイズ値を表す。 |
カスタム バインディング宣言のスコープは、以下の継承およびオーバーライド規則に準拠します。
継承 — カスタマイズ値は上から下へ継承される。たとえば、コンポーネント スコープの WSDL 要素 (JAX-WS) は、グローバル スコープで定義されているカスタマイズ値を継承します。コンポーネント スコープのスキーマ要素 (JAXB) は、グローバル スコープ、スキーマ スコープ、および定義スコープで定義されているカスタマイズ値を継承します。
オーバーライド — カスタマイズ値は下から上へオーバーライドされる。たとえば、コンポーネント スコープの WSDL 要素 (JAX-WS) は、グローバル スコープで定義されているカスタマイズ値をオーバーライドします。コンポーネント スコープのスキーマ要素 (JAXB) は、定義スコープ、スキーマ スコープ、およびグローバル スコープで定義されているカスタマイズ値をオーバーライドします。
以下の節では、カスタム バインディング宣言の作成方法と、標準のカスタム バインディング宣言について説明します。
カスタム バインディング宣言の使用に関する詳細については、以下を参照してください。
https://jax-ws.dev.java.net/nonav/2.1.2m1/docs/customizations.html
の「JAX-WS WSDL Customizations」
JAXB 仕様 (http://jcp.org/en/jsr/detail?id=222
) の「Customizing XML Schema to Java Representation Binding」
特定の WSDL または XML スキーマ ドキュメントのすべてのバインディング宣言を格納する外部のバインディング宣言ファイルを作成します。次に、バインディング宣言ファイルを wsdlc
、jwsc
、または clientgen
Ant タスクの <binding>
子要素に渡します。
以降の節で説明する内容は、次のとおりです。
以下の節では、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 バインディング宣言ファイルは、ネームスペース 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 拡張として jaxws:bindings 要素を使用し、JAX-WS または JAXB バインディング宣言を WSDL ファイルに埋め込む。
「WSDL ファイルへの JAX-WS または JAXB バインディング宣言の埋め込み」を参照してください。
<appinfo>
要素の一部として、JAXB バインディング宣言を XML スキーマに埋め込む。「XML スキーマへの 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 カスタム バインディング宣言」を参照してください。
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 カスタム バインディング宣言の完全なリストについては、https://jax-ws.dev.java.net/nonav/2.1.2/docs/customizations.html
にある「JAX-WS WSDL Customization」を参照してください。
表 5-13 JAX-WS カスタム バインディング宣言
カスタマイズ | 説明 |
---|---|
パッケージ名 |
パッケージ名の定義には、 このカスタマイズを指定しない場合、 このバインディング宣言は、「外部バインディング宣言ファイルの作成」で説明するようにルート バインディング要素の一部として指定したり、次の例で示すように
<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 オペレーションのパラメータや戻り値の型の生成方法を制御するラッパー形式規則を有効化または無効化するには、 このバインディング宣言は、「外部バインディング宣言ファイルの作成」で説明するようにルート バインディング要素の一部として指定したり、以下のいずれかのノード上で指定することができる。
次の例では、 <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 ファイルのコンパイル時に このバインディング宣言は、「外部バインディング宣言ファイルの作成」で説明するようにルート バインディング要素の一部として指定したり、以下のいずれかのノード上で指定することができる。
次の例では、非同期のポーリング オペレーションおよびコールバック オペレーションを無効化している。 <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> |
プロバイダ |
プロバイダ インタフェースとして一部をマークするには、 |
クラス名 |
クラス名の定義には、
次の例では、実装クラスのクラス名を定義している。
<bindings node="wsdl:definitions/wsdl:service[@name='SimpleService']">
<class name="myService"></class>
</bindings>
|
メソッド名 |
生成された 次の例では、
<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
<method name="Greeting"></method>
</bindings>
|
Java パラメータ名 |
生成された 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 テキストを指定するには、 たとえば、次の例では、メソッド レベルで Javadoc を定義している。 <bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']"> <method name="Hello"> <javadoc>Prints hello.</javadoc> </method> </bindings> |
ハンドラ チェーン |
ハンドラをカスタマイズまたは追加するには、 |
次の表に、一般的な JAXB のカスタマイズをまとめます。
注意 : 次の表には、開始時に役立つ JAXB カスタム バインディング宣言のみをまとめています。すべての JAXB カスタム バインディング宣言の完全なリストと説明については、JAXB 仕様、または、Sun Java EE 5 Tutorial の 「Customizing JAXB Bindings」(http://jcp.org/en/jsr/detail?id=222 ) を参照してください。 |
表 5-14 JAXB カスタム バインディング宣言
カスタマイズ | 説明 |
---|---|
グローバル バインディング |
グローバル スコープでバインディング宣言を定義するには、
<jaxb:globalBindings collectionType ="java.util.myArray" generateIsSetMethod="false"> <jaxb:javaType name="java.util.Date" xmlType="xsd:date" </jaxb:javaType> </jaxb:globalBindings> |
スキーマ バインディング |
スキーマ スコープでバインディング宣言を定義するには、 例として、次の表の「パッケージ名」に関する説明を参照してください。 |
パッケージ名 |
スキーマのパッケージ名を定義するには、 このカスタマイズを指定しない場合、 たとえば、次の例では、
<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> |
クラス名 |
スキーマ要素のクラス名を定義するには、 次の例では、
<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 プロパティ名 |
スキーマ要素のプロパティ名を定義するには、 次の例では、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 データ型 (組み込みデータ型またはアプリケーション固有のデータ型) のバインディングをカスタマイズするには、 たとえば、グローバル バインディング (上記の) を参照してください。 |
Javadoc |
要素の 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> |