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

Style.DOCUMENT (デフォルト)

Style.RPC

SOAP メッセージのスタイルを指定します。RPC スタイルが指定されている場合、SOAP ボディーの各メッセージ部分はパラメーターまたは戻り値で、soap:body 要素内のラッパー要素に表示されます。ラッパー要素内のメッセージ部分は操作パラメーターに対応し、操作のパラメーターと同じ順序で表示される必要があります。DOCUMENT スタイルを指定する場合、SOAP 本体の内容は有効な XML ドキュメントである必要がありますが、その形式はそれほど厳密に制限されていません。

use

Use.LITERAL (デフォルト)

Use.ENCODED[a]

SOAP メッセージのデータをストリーミングする方法を指定します。

parameterStyle [b]

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 アノテーションのプロパティーを説明します。

表24.3 @WebMethod プロパティー

プロパティー説明

operationName

関連する wsdl:operation 要素の name 値を指定します。デフォルト値はメソッドの名前です。

action

メソッド用に生成される soap:operation 要素の soapAction 属性の値を指定します。デフォルト値は空の文字列です。

exclude

メソッドをサービスインターフェイスから除外するかどうかを指定します。デフォルトは false です。

@RequestWrapper アノテーション

@RequestWrapper アノテーションは、javax.xml.ws.RequestWrapper インターフェイスによって定義されます。これは、SEI のメソッドに配置されます。@RequestWrapper アノテーションは、メッセージ変換を開始するリクエストメッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、リクエストメッセージをマーシャリングおよびアンマーシャリングするときにランタイムが使用する要素名と名前空間も指定します。

表24.4「@RequestWrapper プロパティー」 は @RequestWrapper アノテーションのプロパティーを説明します。

表24.4 @RequestWrapper プロパティー

プロパティー説明

localName

要求メッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値はメソッドの名前または 「@WebMethod アノテーション」 アノテーションの operationName プロパティーの値です。

targetNamespace

XML ラッパー要素が定義される名前空間を指定します。デフォルト値は、SEI のターゲット名前空間です。

className

ラッパー要素を実装する Java クラスのフルネームを指定します。

注記

className プロパティーのみが必要になります。

重要

メソッドに @SOAPBinding アノテーションが付けられ、その parameterStyle プロパティーが ParameterStyle.BARE に設定されている場合、このアノテーションは無視されます。

@ResponseWrapper アノテーション

@ResponseWrapper アノテーションは、javax.xml.ws.ResponseWrapper インターフェイスによって定義されます。これは、SEI のメソッドに配置されます。@ResponseWrapper は、メッセージ変換の応答メッセージのメソッドパラメーターのラッパー Bean を実装する Java クラスを指定します。また、応答メッセージをマーシャリングおよびアンマーシャリングするときにランタイムが使用する要素名と名前空間も指定します。

表24.5「@ResponseWrapper プロパティー」 は @ResponseWrapper アノテーションのプロパティーを説明します。

表24.5 @ResponseWrapper プロパティー

プロパティー説明

localName

応答メッセージの XML 表現でラッパー要素のローカル名を指定します。デフォルト値は、Response が追加されたメソッドの名前、または Response が追加された「@WebMethod アノテーション」アノテーションの operationName プロパティーの値のいずれかです。

targetNamespace

XML ラッパー要素が定義されている名前空間を指定します。デフォルト値は、SEI のターゲット名前空間です。

className

ラッパー要素を実装する 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

障害要素のローカル名を指定します。

targetNamespace

障害要素が定義されている名前空間を指定します。デフォルト値は、SEI のターゲット名前空間です。

faultName

例外を実装する Java クラスのフルネームを指定します。

重要

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 プロパティー

プロパティー値説明

name

 

生成された WSDL ドキュメントに表示されるパラメーターの名前を指定します。RPC バインディングの場合、これはパラメーターを表す wsdl:part の名前です。ドキュメントバインディングの場合、これはパラメーターを表す XML 要素のローカル名です。JAX-WS 仕様によると、デフォルトは argN です。ここで、N はゼロベースの引数インデックスに置き換えてください (例: arg0、arg1 など)。

targetNamespace

 

パラメーターの名前空間を指定します。これは、パラメーターが XML 要素にマップされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの名前空間を使用します。

mode

Mode.IN (デフォルト)[a]

Mode.OUT

Mode.INOUT

パラメーターの方向を指定します。

header

false (デフォルト)

true

パラメーターを SOAP ヘッダーの一部として渡すかどうかを指定します。

partName

 

パラメーターの wsdl:part 要素の name 属性の値を指定します。このプロパティーは、ドキュメントスタイルの SOAP バインディングに使用されます。

[a] ホルダーインターフェイスを実装するパラメーターはすべて、デフォルトで Mode.INOUT にマップされます。

@WebResult アノテーション

@WebResult アノテーションは、javax.jws.WebResult インターフェイスによって定義されます。これは、SEI で定義されたメソッドに配置されます。@WebResult アノテーションを使用すると、メソッドの戻り値に対して生成される wsdl:part のプロパティーを指定できます。

表24.8「@WebResult プロパティー」 @WebResult アノテーションのプロパティーを説明します。

表24.8 @WebResult プロパティー

プロパティー説明

name

生成された WSDL ドキュメントに表示される戻り値の名前を指定します。RPC バインディングの場合、これは戻り値を表す wsdl:part の名前です。ドキュメントバインディングの場合、これは戻り値を表す XML 要素のローカル名です。デフォルト値は return です。

targetNamespace

戻り値の名前空間を指定します。これは、戻り値が XML 要素にマップされるドキュメントバインディングでのみ使用されます。デフォルトでは、サービスの名前空間を使用します。

header

戻り値が SOAP ヘッダーの一部として渡されるかどうかを指定します。

partName

戻り値の wsdl:part 要素の name 属性の値を指定します。このプロパティーは、ドキュメントスタイルの 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
  );
}