Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS Webサービス・スタート・ガイド 11g リリース1(10.3.6) B61645-04 |
|
前 |
次 |
この章では、Java Architecture for XML Binding (JAXB)データ・バインディングの使用方法について説明します。
この章では、以下のトピックについて説明します。
様々なシステム間でのデータ交換にはXMLが標準的に使用されているため、Webサービス・アプリケーションには、Javaアプリケーションから直接XML形式データへアクセスする手段が必要となります。具体的には、XMLコンテンツをJavaアプリケーションで読み取れる形式に変換する必要があります。データ・バインディングでは、XML表現とJava表現間のデータ変換を記述します。
JAX-WSでは、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 WebLogic Server WebLogic 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> <!-- Stock Keeping Unit, a code for identifying products --> <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){...} /** Optional to set Comment property. */ 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){...} /** Type constraint on Quantity setter value 0..99.*/ int getQuantity(){...} void setQuantity(int){...} float getUSPrice(){...} void setUSPrice(float){...} /** Optional to set Comment property. */ String getComment(){...} void setComment(String){...} XMLGregorianCalendar getShipDate(); void setShipDate(XMLGregorianCalendar); /** Type constraint on PartNum setter value "\d{3}-[A-Z]{2}".*/ String getPartNum(){...} void setPartNum(String){...} }; /** Local structural constraint 1 or more instances of Items.ItemType.*/ List<Items.ItemType> getItem(){...} } public class ObjectFactory { // type factories Object newInstance(Class javaInterface){...} PurchaseOrderType createPurchaseOrderType(){...} USAddress createUSAddress(){...} Items createItems(){...} Items.ItemType createItemsItemType(){...} // element factories 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データ型またはマッピング・メカニズム |
---|---|
単純型および複合型の両方の要素を持つ |
JavaBean |
単純なコンテンツを含む |
JavaBean |
|
JavaBeanのプロパティ。 |
既存の単純型の制限による新しい単純型の派生 |
同等の単純型の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://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/package-summary.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://download.oracle.com/javaee/5/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://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/XmlElement.html
にあるJavadocの「javax.xml.bind.annotation.XmlElement」
を参照してください。
@XmlMimeType
アノテーションは、プロパティのXML表現を制御するMIMEタイプを指定します。このアノテーションは、XMLのxsd:base64Binary
バイナリにバインドされるImage
やSource
などのデータ型に対して指定できます。
次の表に、@XmlMimeType
アノテーションに渡すことができる必須の要素を示します。
詳細は、http://download.oracle.com/javaee/5/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://download.oracle.com/javaee/5/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://download.oracle.com/javaee/5/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)は、定義スコープ、スキーマ・スコープ、およびグローバル・スコープで定義されているカスタマイズ値をオーバーライドします。
以下の項では、カスタム・バインディング宣言の作成方法と、標準のカスタム・バインディング宣言について説明します。
カスタム・バインディング宣言の使用に関する詳細は、以下を参照してください。
JAX-WS WSDLのカスタマイズ(http://jax-ws.java.net/nonav/2.1.2/docs/customizations.html
)
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 (http://jax-ws.java.net/nonav/2.1.2/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カスタム・バインディング宣言」を参照してください。
jaxb: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 (http://jax-ws.java.net/nonav/2.1.2/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カスタム・バインディング宣言の完全なリストについては、http://jax-ws.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仕様(http://jcp.org/en/jsr/detail?id=222 )またはJava EE 5 Tutorialの「Customizing JAXB Bindings」を参照してください。 |
表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> |