Menu Close
24.3.3. オプションのアノテーション
概要
Java インターフェースまたは Java クラスを有効にするサービスには @WebService
アノテーションで十分ですが、サービスがサービスプロバイダーとして公開される方法を十分には説明していません。JAX-WS プログラミングモデルは、使用するバインディングなど、サービスの詳細を Java コードに追加するために、多くの任意のアノテーションを使用します。これらのアノテーションをサービスの 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 に設定します。
ベアパラメーターを使用する際に、操作がドキュメントスタイル使用の制限に違反しないように、操作は以下の条件を満たしている必要があります。
- 操作は複数の入力または入出力パラメーターを持たない。
-
操作の戻り値の型が
void
以外の場合、出力または入出力パラメータを持たない。 -
操作の戻り値の型が
void
である場合、複数の出力または入出力パラメーターを持たない。
@WebParam
アノテーションまたは @WebResult
アノテーションを使用して SOAP ヘッダーに配置されるパラメーターは、許可されるパラメーターの数にカウントされません。
ドキュメントラップパラメーター
ドキュメントラップスタイルにより、Java コードと結果となるサービスの XML 表現との間で、より RPC 的なマッピングを使用でます。このスタイルを使用する場合、メソッドのパラメーター一覧のパラメーターはバインディングによって単一の要素にラップされます。この手法の欠点は、Java 実装と伝送時のメッセージ配置方法との間に、新たな間接性のレイヤーが生じることです。
ラップ document\literal スタイルを使用するには、@SOAPBinding
アノテーションの style
プロパティを Style.DOCUMENT に設定し、parameterStyle
プロパティを ParameterStyle.WRAPPED に設定します。
「@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 でどのように見えるか
- メッセージを一方向片道メッセージとして最適化できるかどうか
- メッセージが定義される namespace
@WebMethod アノテーション
@WebMethod
アノテーションは、javax.jws.WebMethod インターフェースによって定義されます。これは SEI のメソッドに配置されます。@WebMethod
アノテーションは、メソッドが関連付けられる操作を記述する wsdl:operation
要素に通常表される情報を提供します。
表24.3「@WebMethod
プロパティー」に、@WebMethod
アノテーションのプロパティーを示します。
@RequestWrapper アノテーション
@RequestWrapper
アノテーションは、javax.xml.ws.RequestWrapper インターフェースによって定義されます。これは SEI のメソッドに配置されます。@RequestWrapper
アノテーションは、メッセージ変換を開始するリクエストメッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、リクエストメッセージをマーシャリングおよびアンマーシャリングする際にランタイムによって使用される要素名および namespace も指定します。
表24.4「@RequestWrapper
プロパティー」に、@RequestWrapper
アノテーションのプロパティーを示します。
表24.4 @RequestWrapper
プロパティー
プロパティー | 説明 |
---|---|
リクエストメッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値はメソッドの名前、または「@WebMethod アノテーション」アノテーションの | |
XML ラッパー要素が定義される namespace を指定します。デフォルト値は SEI のターゲット namespace です。 | |
ラッパー要素を実装する Java クラスの完全な名前を指定します。 |
className
プロパティーのみが必須です。
メソッドに @SOAPBinding
アノテーションも付けられ、その parameterStyle
プロパティーが ParameterStyle.BARE
に設定されている場合、このアノテーションは無視されます。
@ResponseWrapper アノテーション
@ResponseWrapper
アノテーションは、javax.xml.ws.ResponseWrapper インターフェースによって定義されます。これは SEI のメソッドに配置されます。@ResponseWrapper
は、メッセージ変換の応答メッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、応答メッセージをマーシャリングおよびアンマーシャリングする際にランタイムによって使用される要素名および namespace も指定します。
表24.5「@ResponseWrapper
プロパティー」に、@ResponseWrapper
アノテーションのプロパティーを示します。
表24.5 @ResponseWrapper
プロパティー
プロパティー | 説明 |
---|---|
応答メッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値は、Response が追加されたメソッドの名前、または Response が追加された「@WebMethod アノテーション」アノテーションの | |
XML ラッパー要素が定義される namespace を指定します。デフォルト値は SEI のターゲット namespace です。 | |
ラッパー要素を実装する 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
を戻す - Holder インターフェースを実装するパラメーターを持たない
- コンシューマーに戻すことのできる例外を発生しない
例
例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 のメソッドパラメーターは、wsdl:part
要素およびその wsdl:message
要素に対応します。JAX-WS は、メソッドパラメーター用に生成された wsdl:part
要素を記述することのできるアノテーションを提供します。
@WebParam アノテーション
@WebParam
アノテーションは、javax.jws.WebParam インターフェースによって定義されます。これは、SEI で定義されるメソッドのパラメーターに配置されます。@WebParam
アノテーションを使用すると、パラメーターの方向、パラメーターが SOAP ヘッダーに配置されるかどうか、および生成された wsdl:part
の他のプロパティーを指定できます。
表24.7「@WebParam
プロパティー」に、@WebParam
アノテーションのプロパティーを示します。
表24.7 @WebParam
プロパティー
プロパティー | 値 | 説明 |
---|---|---|
生成された WSDL ドキュメントに表示されるパラメーターの名前を指定します。RPC バインディングの場合、これはパラメーターを表す | ||
パラメーターの namespace を指定します。これは、パラメーターが XML 要素にマッピングされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの namespace が使用されます。 | ||
Mode.IN (デフォルト)[a] Mode.OUT Mode.INOUT | パラメーターの方向を指定します。 | |
false (デフォルト) true | パラメーターが SOAP ヘッダーの一部として渡されるかどうかを指定します。 | |
パラメーターの | ||
[a]
Holder インターフェースを実装するパラメーターは、デフォルトで Mode.INOUT にマッピングされます。
|
@WebResult アノテーション
@WebResult
アノテーションは、javax.jws.WebResult インターフェースによって定義されます。これは SEI で定義されるメソッドに配置されます。@WebResult
アノテーションを使用すると、メソッドの戻り値に生成される wsdl:part
のプロパティーを指定できます。
表24.8「@WebResult
プロパティー」に、@WebResult
アノテーションのプロパティーを示します。
表24.8 @WebResult
プロパティー
プロパティー | 説明 |
---|---|
生成された WSDL ドキュメントに表示される戻り値の名前を指定します。RPC バインディングの場合、これは戻り値を表す | |
戻り値の namespace を指定します。これは、戻り値が XML 要素にマッピングされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの namespace が使用されます。 | |
戻り値が 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 ); }