24.3. コードに注釈を付ける
24.3.1. JAX-WS アノテーションの概要
JAX-WS アノテーションは、SEI を完全に指定されたサービス定義にマップするために使用されるメタデータを指定します。注釈で提供される情報には、次のものがあります。
- サービスのターゲット名前空間。
- リクエストメッセージを保持するために使用されるクラスの名前
- 応答メッセージを保持するために使用されるクラスの名前
- 操作が一方向操作の場合
- サービスが使用するバインディングスタイル
- カスタム例外に使用されるクラスの名前
- サービスによって使用されるタイプが定義される名前空間
ほとんどの注釈には適切なデフォルトがあり、それらに値を指定する必要はありません。ただし、アノテーションで提供する情報が多いほど、サービス定義がより適切に指定されます。明確に指定されたサービス定義は、分散アプリケーションのすべての部分が連携する可能性を高めます。
24.3.2. 必要なアノテーション
概要
Java コードからサービスを作成するには、コードに 1 つのアノテーションを追加するだけで済みます。@WebService アノテーションを SEI と実装クラスの両方に追加する必要があります。
@WebService アノテーション
@WebService アノテーションは javax.jws.WebService インターフェイスによって定義され、サービスとして使用されるインターフェイスまたはクラスに配置されます。@WebService には、表24.1「@WebService プロパティー」 で説明されているプロパティーがあります。
表24.1 @WebService プロパティー
| プロパティー | 説明 |
|---|---|
|
サービスインターフェイスの名前を指定します。このプロパティーは、WSDL コントラクトのサービスのインターフェイスを定義する | |
| サービスが定義されているターゲット名前空間を指定します。このプロパティーが指定されていない場合、ターゲット名前空間はパッケージ名から派生します。 | |
|
公開されたサービスの名前を指定します。このプロパティーは、公開されたサービスを定義する | |
| サービスの WSDL コントラクトが保存されている URL を指定します。これは、相対 URL を使用して指定する必要があります。デフォルトは、サービスがデプロイされている URL です。 | |
| 実装クラスが実装する SEI のフルネームを指定します。このプロパティーは、属性がサービス実装クラスで使用される場合にのみ指定されます。 | |
|
サービスが公開されるエンドポイントの名前を指定します。このプロパティーは、公開されたサービスのエンドポイントの詳細を指定する | |
[a]
SEI から WSDL を生成する場合、実装クラスの名前の代わりにインターフェイスの名前が使用されます。
| |
@WebService アノテーションのプロパティーに値を指定する必要はありません。ただし、できるだけ多くの情報を提供することをお勧めします。
SEI に注釈を付ける
SEI では、@WebService アノテーションを追加する必要があります。SEI はサービスを定義するコントラクトなので、@WebService アノテーションのプロパティーにサービスの詳細をできるだけ多く指定する必要があります。
例24.3「@WebService アノテーションあるインターフェイス」は、@WebService アノテーションにより 例24.1「シンプルな SEI」 で定義したインターフェイスを示しています。
例24.3 @WebService アノテーションあるインターフェイス
package com.fusesource.demo;
import javax.jws.*;
@WebService(name="quoteUpdater",
targetNamespace="http:\\demos.redhat.com",
serviceName="updateQuoteService",
wsdlLocation="http:\\demos.redhat.com\quoteExampleService?wsdl",
portName="updateQuotePort")
public interface quoteReporter
{
public Quote getQuote(String ticker);
}
例24.3「@WebService アノテーションあるインターフェイス」 の @WebService アノテーションは以下を行います。
サービスインターフェイスを定義する wsdl:portType 要素の name 属性の値が quoteUpdater であることを指定します。
サービスのターゲット名前空間が http:\\demos.redhat.com であることを指定します。
公開されたサービスを定義する wsdl:service 要素の name の値が updateQuoteService であることを指定します。
サービスが WSDL コントラクトを http:\\demos.redhat.com\quoteExampleService?wsdl で公開することを指定します。
サービスを公開するエンドポイントを定義する wsdl:port 要素の name 属性の値が updateQuotePort であることを指定します。
サービス実装に注釈を付ける
また、SEI に @WebService アノテーションを付ける必要があります。また、サービス実装クラスに @WebService アノテーションを付ける必要があります。アノテーションをサービス実装クラスに追加する場合は、endpointInterface プロパティーのみを指定する必要があります。例24.4「アノテーション付きサービス実装クラス」 に示すようにプロパティーは、SEI のフルネームに設定する必要があります。
例24.4 アノテーション付きサービス実装クラス
package org.eric.demo;
import javax.jws.*;
@WebService(endpointInterface="com.fusesource.demo.quoteReporter")
public class stockQuoteReporter implements quoteReporter
{
public Quote getQuote(String ticker)
{
...
}
}24.3.3. 任意のアノテーション
概要
Java インターフェイスまたは Java クラスを有効にするサービスには @WebService アノテーションで十分ですが、サービスがサービスプロバイダーとして公開される方法を完全に説明しません。JAX-WS プログラミングモデルは、使用するバインディングなど、サービスに関する詳細を Java コードに追加するために、いくつかのオプションのアノテーションを使用します。これらのアノテーションをサービスの SEI に追加します。
SEI で提供する詳細が多いほど、開発者は、SEI が定義する機能を使用できるアプリケーションを実装しやすくなります。また、ツールによって生成された WSDL ドキュメントをより具体的にします。
概要
アノテーションを使用したバインディングプロパティーの定義
サービスに SOAP バインディングを使用している場合は、JAX-WS アノテーションを使用していくつかのバインディングプロパティーを指定できます。これらのプロパティーは、サービスの WSDL コントラクトで指定できるプロパティーに直接対応しています。パラメータースタイルなどの一部の設定では、メソッドの実装方法が制限される場合があります。これらの設定は、メソッドパラメーターに注釈を付けるときに使用できる注釈にも影響を与える可能性があります。
@SOAPBinding アノテーション
@SOAPBinding アノテーションは javax.jws.soap.SOAPBinding インターフェイスによって定義されます。デプロイ時にサービスによって使用される SOAP バインディングに関する詳細を提供します。@SOAPBinding アノテーションが指定されていない場合、サービスはラップされた doc/literal SOAP バインディングを使用して公開されます。
@SOAPBinding アノテーションを SEI および SEI の任意のメソッドに追加できます。メソッドで使用される場合は、メソッドの @SOAPBinding アノテーションの設定が優先されます。
表24.2「@SOAPBinding プロパティー」 @SOAPBinding アノテーションのプロパティーを表示します。
表24.2 @SOAPBinding プロパティー
| プロパティー | 値 | 説明 |
|---|---|---|
| Style.DOCUMENT (デフォルト) Style.RPC |
SOAP メッセージのスタイルを指定します。RPC スタイルが指定されている場合、SOAP ボディーの各メッセージ部分はパラメーターまたは戻り値で、 | |
| Use.LITERAL (デフォルト) Use.ENCODED[a] | SOAP メッセージのデータをストリーミングする方法を指定します。 | |
|
| ParameterStyle.BARE ParameterStyle.WRAPPED (デフォルト) | WSDL コントラクトのメッセージ部分に対応するメソッドパラメーターを SOAP メッセージ本文に配置する方法を指定します。BARE が指定されている場合、各パラメーターはメッセージルートの子要素としてメッセージ本文に配置されます。WRAPPED が指定されている場合、すべての入力パラメーターは要求メッセージで単一の要素にラップされ、すべての出力パラメーターは応答メッセージで単一の要素にラップされます。 |
[a]
Use.ENCODED は現在サポートされていません。
[b]
style を RPC に設定する場合は、WRAPPED パラメータースタイルを使用する必要があります。
| ||
ベアスタイルパラメーターを文書化する
ドキュメントベアスタイルは、Java コードと結果として得られるサービスの XML 表現との間の最も直接的なマッピングです。このスタイルを使用する場合、スキーマタイプは、操作のパラメーターリストで定義された入力パラメーターと出力パラメーターから直接生成されます。
ベア document\literal スタイルを使用するには、@SOAPBinding アノテーションの style プロパティーを Style.DOCUMENT に設定し、parameterStyle プロパティーを ParameterStyle.BARE に設定します。
ベアパラメーターを使用するときに操作がドキュメントスタイルの使用制限に違反しないようにするには、操作が次の条件に準拠している必要があります。
- 操作には、入力パラメーターまたは入出力パラメーターを 1 つだけ含める必要があります。
-
操作に
void以外の型がある場合、出力または入出力パラメーターを含めることはできません。 -
操作に
voidを返すタイプがある場合は、複数の出力または入出力パラメーターは必要ありません。
@WebParam アノテーションまたは @WebResult アノテーションを使用して SOAP ヘッダーに配置されるパラメーターは、許可されるパラメーターの数にカウントされません。
ドキュメントでラップされたパラメーター
ドキュメントラップスタイルにより、Java コードと結果のサービスの XML 表現との間のマッピングのような RPC が可能になります。このスタイルを使用する場合、メソッドのパラメーターリスト内のパラメーターは、バインディングによって単一の要素にラップされます。これの欠点は、Java 実装とメッセージがネットワーク上に配置される方法との間に間接層が追加されることです。
ベア document\literal スタイルを使用するには、@SOAPBinding アノテーションの style プロパティーを Style.DOCUMENT に設定し、parameterStyle プロパティーを ParameterStyle.BARE に設定します。
「@RequestWrapper アノテーション」 注釈と「@ResponseWrapper アノテーション」 注釈を使用して、ラッパーの生成方法をある程度制御できます。
例
例24.5「SOAP バインディングアノテーションを使用したドキュメントベア SOAP バインディングの指定」 は、ドキュメントベア SOAP メッセージを使用する SEI を示しています。
例24.5 SOAP バインディングアノテーションを使用したドキュメントベア SOAP バインディングの指定
package org.eric.demo;
import javax.jws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;
@WebService(name="quoteReporter")
@SOAPBinding(parameterStyle=ParameterStyle.BARE)
public interface quoteReporter
{
...
}概要
アノテーションを使用した操作プロパティーの定義
ランタイムが Java メソッド定義を XML 操作定義にマップすると、次のような詳細が提供されます。
- 交換されたメッセージが XML でどのように表示されるか
- メッセージを一方向メッセージとして最適化できる場合
- メッセージが定義されている名前空間
@WebMethod アノテーション
@WebMethod アノテーションは javax.jws.WebMethod インターフェイスによって定義されます。これは、SEI のメソッドに配置されます。@WebMethod アノテーションは、通常、メソッドが関連付けられる操作を記述する wsdl:operation 要素で表される情報を提供します。
表24.3「@WebMethod プロパティー」 @WebMethod アノテーションのプロパティーを説明します。
@RequestWrapper アノテーション
@RequestWrapper アノテーションは、javax.xml.ws.RequestWrapper インターフェイスによって定義されます。これは、SEI のメソッドに配置されます。@RequestWrapper アノテーションは、メッセージ変換を開始するリクエストメッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、リクエストメッセージをマーシャリングおよびアンマーシャリングするときにランタイムが使用する要素名と名前空間も指定します。
表24.4「@RequestWrapper プロパティー」 は @RequestWrapper アノテーションのプロパティーを説明します。
表24.4 @RequestWrapper プロパティー
| プロパティー | 説明 |
|---|---|
|
要求メッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値はメソッドの名前または 「@WebMethod アノテーション」 アノテーションの | |
| XML ラッパー要素が定義される名前空間を指定します。デフォルト値は、SEI のターゲット名前空間です。 | |
| ラッパー要素を実装する Java クラスのフルネームを指定します。 |
className プロパティーのみが必要になります。
メソッドに @SOAPBinding アノテーションが付けられ、その parameterStyle プロパティーが ParameterStyle.BARE に設定されている場合、このアノテーションは無視されます。
@ResponseWrapper アノテーション
@ResponseWrapper アノテーションは、javax.xml.ws.ResponseWrapper インターフェイスによって定義されます。これは、SEI のメソッドに配置されます。@ResponseWrapper は、メッセージ変換の応答メッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、応答メッセージをマーシャリングおよびアンマーシャリングするときにランタイムが使用する要素名と名前空間も指定します。
表24.5「@ResponseWrapper プロパティー」 は @ResponseWrapper アノテーションのプロパティーを説明します。
表24.5 @ResponseWrapper プロパティー
| プロパティー | 説明 |
|---|---|
|
応答メッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値は、Response が追加されたメソッドの名前、または Response が追加された「@WebMethod アノテーション」アノテーションの | |
| XML ラッパー要素が定義されている名前空間を指定します。デフォルト値は、SEI のターゲット名前空間です。 | |
| ラッパー要素を実装する Java クラスのフルネームを指定します。 |
className プロパティーのみが必要になります。
メソッドに @SOAPBinding アノテーションが付けられ、その parameterStyle プロパティーが ParameterStyle.BARE に設定されている場合、このアノテーションは無視されます。
@WebFault アノテーション
@WebFault アノテーションは javax.xml.ws.WebFault インターフェイスによって定義されます。これは、SEI によって出力される例外に配置されます。@WebFault アノテーションを使用して、Java 例外を wsdl:fault 要素にマッピングします。この情報は、サービスとそのコンシューマーの両方が処理できる表現に例外をマーシャリングするために使用されます。
表24.6「@WebFault プロパティー」 @WebFault アノテーションのプロパティーを説明します。
表24.6 @WebFault プロパティー
name プロパティーが必要です。
@Oneway アノテーション
@Oneway アノテーションは javax.jws.Oneway インターフェイスによって定義されます。これは、サービスからの応答を必要としない SEI のメソッドに配置されます。@Oneway アノテーションは、応答を待機せず、応答を処理するリソースを予約しないことで、メソッドの実行を最適化するようにランタイムに指示します。
このアノテーションは、次の条件を満たすメソッドでのみ使用できます。
-
このページは
voidを返します。 - ホルダーインターフェイスを実装するパラメーターはありません
- コンシューマーに返すことができる例外を出力しません
例
例24.6「注釈付きメソッドを使用した SEI」 は、メソッドに注釈が付けられた SEI を示しています。
例24.6 注釈付きメソッドを使用した SEI
package com.fusesource.demo;
import javax.jws.*;
import javax.xml.ws.*;
@WebService(name="quoteReporter")
public interface quoteReporter
{
@WebMethod(operationName="getStockQuote")
@RequestWrapper(targetNamespace="http://demo.redhat.com/types",
className="java.lang.String")
@ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
className="org.eric.demo.Quote")
public Quote getQuote(String ticker);
}概要
注釈を使用したパラメータープロパティーの定義
SEI の method パラメーターは、wsdl:message 要素とその wsdl:part 要素に対応します。JAX-WS は、メソッドパラメーター用に生成された wsdl:part 要素を記述することのできるアノテーションを提供します。
@WebParam アノテーション
@WebParam アノテーションは、javax.jws.WebParam インターフェイスによって定義されます。これは、SEI で定義されたメソッドのパラメーターに配置されます。@WebParam アノテーションを使用すると、パラメーターの方向、パラメーターが SOAP ヘッダーに配置されるかどうか、および生成された wsdl:part の他のプロパティーを指定できます。
表24.7「@WebParam プロパティー」 @WebParam アノテーションのプロパティーを説明します。
表24.7 @WebParam プロパティー
| プロパティー | 値 | 説明 |
|---|---|---|
|
生成された WSDL ドキュメントに表示されるパラメーターの名前を指定します。RPC バインディングの場合、これはパラメーターを表す | ||
| パラメーターの名前空間を指定します。これは、パラメーターが XML 要素にマップされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの名前空間を使用します。 | ||
| Mode.IN (デフォルト)[a] Mode.OUT Mode.INOUT | パラメーターの方向を指定します。 | |
| false (デフォルト) true | パラメーターを SOAP ヘッダーの一部として渡すかどうかを指定します。 | |
|
パラメーターの | ||
[a]
ホルダーインターフェイスを実装するパラメーターはすべて、デフォルトで Mode.INOUT にマップされます。
| ||
@WebResult アノテーション
@WebResult アノテーションは、javax.jws.WebResult インターフェイスによって定義されます。これは、SEI で定義されたメソッドに配置されます。@WebResult アノテーションを使用すると、メソッドの戻り値に対して生成される wsdl:part のプロパティーを指定できます。
表24.8「@WebResult プロパティー」 @WebResult アノテーションのプロパティーを説明します。
表24.8 @WebResult プロパティー
| プロパティー | 説明 |
|---|---|
|
生成された WSDL ドキュメントに表示される戻り値の名前を指定します。RPC バインディングの場合、これは戻り値を表す | |
| 戻り値の名前空間を指定します。これは、戻り値が XML 要素にマップされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの名前空間を使用します。 | |
| 戻り値が SOAP ヘッダーの一部として渡されるかどうかを指定します。 | |
|
戻り値の |
例
例24.7「完全に注釈が付けられた SEI」 は、完全に注釈が付けられた SEI を示しています。
例24.7 完全に注釈が付けられた SEI
package com.fusesource.demo;
import javax.jws.*;
import javax.xml.ws.*;
import javax.jws.soap.*;
import javax.jws.soap.SOAPBinding.*;
import javax.jws.WebParam.*;
@WebService(targetNamespace="http://demo.redhat.com",
name="quoteReporter")
@SOAPBinding(style=Style.RPC, use=Use.LITERAL)
public interface quoteReporter
{
@WebMethod(operationName="getStockQuote")
@RequestWrapper(targetNamespace="http://demo.redhat.com/types",
className="java.lang.String")
@ResponseWrapper(targetNamespace="http://demo.redhat.com/types",
className="org.eric.demo.Quote")
@WebResult(targetNamespace="http://demo.redhat.com/types",
name="updatedQuote")
public Quote getQuote(
@WebParam(targetNamespace="http://demo.redhat.com/types",
name="stockTicker",
mode=Mode.IN)
String ticker
);
}24.3.4. Apache CXF アノテーション
24.3.4.1. WSDL ドキュメント
@WSDLDocumentation アノテーション
@WSDLDocumentation アノテーションは、org.apache.cxf.annotations.WSDLDocumentation インターフェイスによって定義されます。SEI または SEI メソッドに配置できます。
このアノテーションを使用するとドキュメントを追加でき、SEI が WSDL に変換された後に wsdl:documentation 要素内に表示されます。デフォルトでは、ドキュメント要素はポートタイプ内に表示されますが、配置プロパティーを指定して、ドキュメントを WSDL ファイルの他の場所に表示することができます。「@WSDLDocumentation プロパティー」 は @WSDLDocumentation アノテーションがサポートするプロパティーを表示します。
24.3.4.2. @WSDLDocumentation プロパティー
| プロパティー | 説明 |
|---|---|
|
| (必須) ドキュメントテキストを含む文字列。 |
|
| (オプション) WSDL ファイルのどこにこのドキュメントを表示するかを指定します。可能な配置値のリストについては、「WSDL コントラクトへの配置」 を参照してください。 |
|
|
(任意) 配置が |
@WSDLDocumentationCollection annotation
@WSDLDocumentationCollection アノテーションは、org.apache.cxf.annotations.WSDLDocumentationCollection インターフェイスによって定義されます。SEI または SEI メソッドに配置できます。
この注釈は、単一の配置場所またはさまざまな配置場所に複数のドキュメント要素を挿入するために使用されます。
WSDL コントラクトへの配置
WSDL コントラクトでドキュメントが表示される場所を指定するには、タイプ WSDLDocumentation.Placement の placement プロパティーを指定します。プレースメントには、次のいずれかの値を指定できます。
-
WSDLDocumentation.Placement.BINDING -
WSDLDocumentation.Placement.BINDING_OPERATION -
WSDLDocumentation.Placement.BINDING_OPERATION_FAULT -
WSDLDocumentation.Placement.BINDING_OPERATION_INPUT -
WSDLDocumentation.Placement.BINDING_OPERATION_OUTPUT -
WSDLDocumentation.Placement.DEFAULT -
WSDLDocumentation.Placement.FAULT_MESSAGE -
WSDLDocumentation.Placement.INPUT_MESSAGE -
WSDLDocumentation.Placement.OUTPUT_MESSAGE -
WSDLDocumentation.Placement.PORT_TYPE -
WSDLDocumentation.Placement.PORT_TYPE_OPERATION -
WSDLDocumentation.Placement.PORT_TYPE_OPERATION_FAULT -
WSDLDocumentation.Placement.PORT_TYPE_OPERATION_INPUT -
WSDLDocumentation.Placement.PORT_TYPE_OPERATION_OUTPUT -
WSDLDocumentation.Placement.SERVICE -
WSDLDocumentation.Placement.SERVICE_PORT -
WSDLDocumentation.Placement.TOP
@WSDLDocumentation の例
「@WSDLDocumentation の使用」 に、@WSDLDocumentation アノテーションを SEI およびそのメソッドの 1 つに追加する方法を示します。
24.3.4.3. @WSDLDocumentation の使用
@WebService
@WSDLDocumentation("A very simple example of an SEI")
public interface HelloWorld {
@WSDLDocumentation("A traditional form of greeting")
String sayHi(@WebParam(name = "text") String text);
}
「ドキュメントで生成された WSDL」 で表示される WSDL は、「@WSDLDocumentation の使用」 の SEI から生成されるため、ドキュメント 要素のデフォルト配置は、それぞれ PORT_TYPE と PORT_TYPE _OPERATION になります。
24.3.4.4. ドキュメントで生成された WSDL
<wsdl:definitions ... >
...
<wsdl:portType name="HelloWorld">
<wsdl:documentation>A very simple example of an SEI</wsdl:documentation>
<wsdl:operation name="sayHi">
<wsdl:documentation>A traditional form of greeting</wsdl:documentation>
<wsdl:input name="sayHi" message="tns:sayHi">
</wsdl:input>
<wsdl:output name="sayHiResponse" message="tns:sayHiResponse">
</wsdl:output>
</wsdl:operation>
</wsdl:portType>
...
</wsdl:definitions>@WSDLDocumentationCollection の例
「@WSDLDocumentationCollection を使用する」 では 、@WSDLDocumentationCollection アノテーションを SEI に追加する方法を説明します。
24.3.4.5. @WSDLDocumentationCollection を使用する
@WebService
@WSDLDocumentationCollection(
{
@WSDLDocumentation("A very simple example of an SEI"),
@WSDLDocumentation(value = "My top level documentation",
placement = WSDLDocumentation.Placement.TOP),
@WSDLDocumentation(value = "Binding documentation",
placement = WSDLDocumentation.Placement.BINDING)
}
)
public interface HelloWorld {
@WSDLDocumentation("A traditional form of Geeky greeting")
String sayHi(@WebParam(name = "text") String text);
}24.3.4.6. メッセージのスキーマ検証
@SchemaValidation アノテーション
@SchemaValidation アノテーションは org.apache.cxf.annotations.SchemaValidation インターフェイスによって定義されます。これは、SEI および個々の SEI メソッドに配置できます。
このアノテーションは、このエンドポイントに送信される XML メッセージのスキーマ検証をオンにします。これは、着信 XML メッセージの形式に問題があると思われる場合のテスト目的に役立ちます。パフォーマンスに大きな影響を与えるため、デフォルトでは検証は無効になっています。
スキーマ検証タイプ
スキーマ検証の動作は、type パラメーターによって制御されます。この値は、org.apache.cxf.annotations.SchemaValidation.SchemaValidationType 型の列挙になります。「スキーマ検証タイプの値」 は使用可能な検証タイプのリストを示します。
24.3.4.7. スキーマ検証タイプの値
| 型 | 説明 |
|---|---|
|
| クライアントとサーバーの着信メッセージにスキーマ検証を適用します。 |
|
| クライアントとサーバー上の送信メッセージにスキーマ検証を適用します。 |
|
| クライアントとサーバーの着信メッセージと発信メッセージの両方にスキーマ検証を適用します。 |
|
| すべてのスキーマ検証が無効になっています。 |
|
| スキーマ検証を要求メッセージに適用します。つまり、検証を送信クライアントメッセージと受信サーバーメッセージに適用します。 |
|
| スキーマ検証を応答メッセージに適用します。つまり、検証を着信クライアントメッセージと発信サーバーメッセージに適用します。 |
例
次の例は、MyService SEI に基づいてエンドポイントのメッセージのスキーマ検証を有効にする方法を示しています。アノテーションを SEI 全体に適用する方法と、SEI の個々のメソッドに適用する方法に注意してください。
@WebService
@SchemaValidation(type = SchemaValidationType.BOTH)
public interface MyService {
Foo validateBoth(Bar data);
@SchemaValidation(type = SchemaValidationType.NONE)
Foo validateNone(Bar data);
@SchemaValidation(type = SchemaValidationType.IN)
Foo validateIn(Bar data);
@SchemaValidation(type = SchemaValidationType.OUT)
Foo validateOut(Bar data);
@SchemaValidation(type = SchemaValidationType.REQUEST)
Foo validateRequest(Bar data);
@SchemaValidation(type = SchemaValidationType.RESPONSE)
Foo validateResponse(Bar data);
}24.3.4.8. データバインディングの指定
@DataBinding annotation
@DataBinding アノテーションは、org.apache.cxf.annotations.DataBinding インターフェイスによって定義されます。SEI に配置されます。
このアノテーションは、データバインディングを SEI に関連付けるために使用され、デフォルトの JAXB データバインディングを置き換えます。@DataBinding アノテーションの値は、データバインディングを提供するクラス ClassName.class である必要があります。
サポートされているデータバインディング
次のデータバインディングは現在、Apache CXF でサポートされています。
org.apache.cxf.jaxb.JAXBDataBinding(デフォルト) 標準の JAXB データバインディング。
org.apache.cxf.sdo.SDODataBindingService Data Objects (SDO) データバインディングは、Apache Tuscany SDO 実装に基づいています。Maven ビルドのコンテキストでこのデータバインディングを使用する場合は、
cxf-rt-databinding-sdoアーティファクトに依存関係を追加する必要があります。org.apache.cxf.aegis.databinding.AegisDatabindingMaven ビルドのコンテキストでこのデータバインディングを使用する場合は、
cxf-rt-databinding-aegisアーティファクトに依存関係を追加する必要があります。org.apache.cxf.xmlbeans.XmlBeansDataBindingMaven ビルドのコンテキストでこのデータバインディングを使用する場合は、
cxf-rt-databinding-xmlbeansアーティファクトに依存関係を追加する必要があります。org.apache.cxf.databinding.source.SourceDataBindingこのデータバインディングは、Apache CXF コアに属しています。
org.apache.cxf.databinding.stax.StaxDataBindingこのデータバインディングは、Apache CXF コアに属しています。
例
「データバインディングの設定」 SDO バインディングを HelloWorld SEI に関連付ける方法を説明します。
24.3.4.9. データバインディングの設定
@WebService
@DataBinding(org.apache.cxf.sdo.SDODataBinding.class)
public interface HelloWorld {
String sayHi(@WebParam(name = "text") String text);
}24.3.4.10. メッセージの圧縮
@GZIP アノテーション
@GZIP アノテーションは org.apache.cxf.annotations.GZIP インターフェイスによって定義されます。SEI に配置されます。
メッセージの GZIP 圧縮を有効にします。GZIP はネゴシエートされた拡張機能です。つまり、クライアントからの最初の要求は gzipped ではありませんが、Accept ヘッダーが追加され、サーバーが GZIP 圧縮をサポートする場合、応答は gzipped になり、後続のリクエストも指定します。
「@GZIP Properties」 は、@GZIP アノテーションでサポートされるオプションのプロパティーを示しています。
24.3.4.11. @GZIP Properties
| プロパティー | 説明 |
|---|---|
|
| このプロパティーで指定されたサイズよりも小さいメッセージは gzip 圧縮され ません。デフォルトは -1(制限なし) です。 |
@FastInfoset
@FastInfoset アノテーションは、org.apache.cxf.annotations.FastInfoset インターフェイスによって定義されます。SEI に配置されます。
メッセージに FastInfoset 形式を使用できるようにします。FastInfoset は、XML のバイナリーエンコーディング形式であり、メッセージサイズと XML メッセージの処理パフォーマンスの両方を最適化することを目的としています。詳細については、Fast Infoset に関する次の Sun の記事を参照してください。
FastInfoset は、ネゴシエートされた拡張機能です。つまり、クライアントからの最初のリクエストは FastInfoset 形式では追加されませんが、Accept ヘッダーが追加され、サーバーが FastInfoset をサポートしていると、応答は FastInfoset になり、後続のリクエストも行われます。
「@FastInfoset プロパティー」 は、@FastInfoset アノテーションでサポートされる任意のプロパティーを表示します。
24.3.4.12. @FastInfoset プロパティー
| プロパティー | 説明 |
|---|---|
|
|
ネゴシエートする代わりに、FastInfoset 形式の使用を強制するブールプロパティー。 |
@GZIP の例
「GZIP の有効化」 は、HelloWorld SEI で GZIP 圧縮を有効にする方法を示します。
24.3.4.13. GZIP の有効化
@WebService
@GZIP
public interface HelloWorld {
String sayHi(@WebParam(name = "text") String text);
}@FastInfoset の例
「FastInfoset の有効化」 は、HelloWorld SEI の FastInfoset 形式を有効にする方法を示します。
24.3.4.14. FastInfoset の有効化
@WebService
@FastInfoset
public interface HelloWorld {
String sayHi(@WebParam(name = "text") String text);
}24.3.4.15. エンドポイントでのロギングを有効にする
@Logging annotation
@Logging アノテーションは、org.apache.cxf.annotations.Logging インターフェイスによって定義されます。SEI に配置されます。
このアノテーションにより、SEI に関連付けられているすべてのエンドポイントのロギングが可能になります。「@Logging Properties」 は、このアノテーションで設定できるオプションのプロパティーを示しています。
24.3.4.16. @Logging Properties
| プロパティー | 説明 |
|---|---|
|
| サイズ制限を指定します。これを超えると、ログでメッセージが切り捨てられます。デフォルトは 64K です。 |
|
|
受信メッセージをログに記録する場所を指定します。 |
|
|
送信メッセージをログに記録する場所を指定します。 |
例
「注釈を使用した設定のロギング」で、HelloWorld SEI でロギングを有効にする方法を説明します。ここでは、受信メッセージは <stdout> に送信され、発信メッセージは <logger> に送信されます。
24.3.4.17. 注釈を使用した設定のロギング
@WebService
@Logging(limit=16000, inLocation="<stdout>")
public interface HelloWorld {
String sayHi(@WebParam(name = "text") String text);
}24.3.4.18. エンドポイントへのプロパティーとポリシーの追加
概要
プロパティーとポリシーの両方を使用して、設定データをエンドポイントに関連付けることができます。それらの本質的な違いは、プロパティー が Apache CXF 固有の設定メカニズムであるのに対し、ポリシー は標準の WSDL 設定メカニズムであるということです。ポリシーは通常 WS 仕様および標準に基づいており、通常は WSDL コントラクトに表示される wsdl:policy 要素を定義して設定されます。これとは対照的に、プロパティーは Apache CXF 固有のもので、通常は Apache CXF Spring 設定ファイルで jaxws:properties 要素を定義して設定されます。
ただし、ここで説明するように、アノテーションを使用して Java でプロパティー設定と WSDL ポリシー設定を定義することもできます。
24.3.4.19. プロパティーの追加
@EndpointProperty annotation
@EndpointProperty アノテーションは、org.apache.cxf.annotations.EndpointProperty インターフェイスによって定義されます。SEI に配置されます。
このアノテーションは、Apache CXF 固有の設定をエンドポイントに追加します。エンドポイントのプロパティーは、Spring 設定ファイルで指定することもできます。たとえば、エンドポイントに WS-Security を設定するには、以下のように Spring 設定ファイルの jaxws:properties 要素を使用してエンドポイントプロパティーを追加できます。
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxws="http://cxf.apache.org/jaxws"
... >
<jaxws:endpoint
id="MyService"
address="https://localhost:9001/MyService"
serviceName="interop:MyService"
endpointName="interop:MyServiceEndpoint"
implementor="com.foo.MyService">
<jaxws:properties>
<entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
<entry key="ws-security.signature.properties" value="etc/keystore.properties"/>
<entry key="ws-security.encryption.properties" value="etc/truststore.properties"/>
<entry key="ws-security.encryption.username" value="useReqSigCert"/>
</jaxws:properties>
</jaxws:endpoint>
</beans>
あるいは、「@EndpointProperty アノテーションを使用した WS-Security の設定」に示すように、@EndpointProperty アノテーションを SEI に追加して、Java で前述の設定を指定できます。
24.3.4.20. @EndpointProperty アノテーションを使用した WS-Security の設定
@WebService
@EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback")
@EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties")
@EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties")
@EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
public interface HelloWorld {
String sayHi(@WebParam(name = "text") String text);
}@EndpointProperties annotation
@EndpointProperties アノテーションは、org.apache.cxf.annotations.EndpointProperties インターフェイスによって定義されます。SEI に配置されます。
このアノテーションは、複数の @EndpointProperty アノテーションをリストにグループ化する方法を提供します。@EndpointProperties を使用すると、「@EndpointProperties アノテーションを使用した WS-Security の設定」 に示すように 「@EndpointProperty アノテーションを使用した WS-Security の設定」 を再書き込みできます。
24.3.4.21. @EndpointProperties アノテーションを使用した WS-Security の設定
@WebService
@EndpointProperties(
{
@EndpointProperty(name="ws-security.callback-handler" value="interop.client.UTPasswordCallback"),
@EndpointProperty(name="ws-security.signature.properties" value="etc/keystore.properties"),
@EndpointProperty(name="ws-security.encryption.properties" value="etc/truststore.properties"),
@EndpointProperty(name="ws-security.encryption.username" value="useReqSigCert")
})
public interface HelloWorld {
String sayHi(@WebParam(name = "text") String text);
}24.3.4.22. ポリシーの追加
@Policy アノテーション
@Policy アノテーションは org.apache.cxf.annotations.Policy インターフェイスによって定義されます。SEI または SEI メソッドに配置できます。
このアノテーションは、WSDL ポリシーを SEI または SEI メソッドに関連付けるために使用されます。ポリシーは、標準の wsdl:policy 要素を含む XML ファイルを参照する URI を提供することにより指定されます。SEI から WSDL コントラクトが生成される場合は (たとえば、java2ws コマンドラインツールを使用して)、WSDL にこのポリシーを追加するかどうかを指定できます。
「@Policy プロパティー」 に、@Policy アノテーションでサポートされるプロパティーを示します。
24.3.4.23. @Policy プロパティー
| プロパティー | 説明 |
|---|---|
|
| (必須) ポリシー定義を含むファイルの場所。 |
|
|
(オプション) WSDL を生成するときに、生成されたコントラクトにポリシーを含めるかどうか。デフォルトは |
|
| (オプション) WSDL ファイルのどこにこのドキュメントを表示するかを指定します。可能な配置値のリストについては、「WSDL コントラクトへの配置」 を参照してください。 |
|
|
(任意) 配置が |
@Policies アノテーション
@Policies アノテーションは org.apache.cxf.annotations.Policies インターフェイスで定義されます。SEI または SEI メソッドに配置できます。
このアノテーションは、複数の @Policy アノテーションをリストにグループ化する方法を提供します。
WSDL コントラクトへの配置
ポリシーが WSDL コントラクトのどこに表示されるかを指定するには、Policy.Placement 型である placement プロパティーを指定します。プレースメントには、次のいずれかの値を指定できます。
Policy.Placement.BINDING Policy.Placement.BINDING_OPERATION Policy.Placement.BINDING_OPERATION_FAULT Policy.Placement.BINDING_OPERATION_INPUT Policy.Placement.BINDING_OPERATION_OUTPUT Policy.Placement.DEFAULT Policy.Placement.PORT_TYPE Policy.Placement.PORT_TYPE_OPERATION Policy.Placement.PORT_TYPE_OPERATION_FAULT Policy.Placement.PORT_TYPE_OPERATION_INPUT Policy.Placement.PORT_TYPE_OPERATION_OUTPUT Policy.Placement.SERVICE Policy.Placement.SERVICE_PORT
@Policy の例
以下の例は、WSDL ポリシーを HelloWorld SEI に関連付け、ポリシーを sayHi メソッドに関連付ける方法を示しています。ポリシー自体は、annotationpolicies ディレクトリーの下に、ファイルシステムの XML ファイルに保存されます。
@WebService
@Policy(uri = "annotationpolicies/TestImplPolicy.xml",
placement = Policy.Placement.SERVICE_PORT),
@Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
placement = Policy.Placement.PORT_TYPE)
public interface HelloWorld {
@Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
placement = Policy.Placement.PORT_TYPE_OPERATION),
String sayHi(@WebParam(name = "text") String text);
}@Policies の例
以下の例のように、@Policies アノテーションを使用して、複数の @Policy アノテーションをリストにグループ化できます。
@WebService
@Policies({
@Policy(uri = "annotationpolicies/TestImplPolicy.xml",
placement = Policy.Placement.SERVICE_PORT),
@Policy(uri = "annotationpolicies/TestPortTypePolicy.xml",
placement = Policy.Placement.PORT_TYPE)
})
public interface HelloWorld {
@Policy(uri = "annotationpolicies/TestOperationPTPolicy.xml",
placement = Policy.Placement.PORT_TYPE_OPERATION),
String sayHi(@WebParam(name = "text") String text);
}