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

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 に設定します。

ベアパラメーターを使用する際に、操作がドキュメントスタイル使用の制限に違反しないように、操作は以下の条件を満たしている必要があります。

  • 操作は複数の入力または入出力パラメーターを持たない。
  • 操作の戻り値の型が 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 アノテーションのプロパティーを示します。

表24.3 @WebMethod プロパティー

プロパティー説明

operationName

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

action

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

exclude

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

@RequestWrapper アノテーション

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

表24.4「@RequestWrapper プロパティー」に、@RequestWrapper アノテーションのプロパティーを示します。

表24.4 @RequestWrapper プロパティー

プロパティー説明

localName

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

targetNamespace

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

className

ラッパー要素を実装する Java クラスの完全な名前を指定します。

注記

className プロパティーのみが必須です。

重要

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

@ResponseWrapper アノテーション

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

表24.5「@ResponseWrapper プロパティー」に、@ResponseWrapper アノテーションのプロパティーを示します。

表24.5 @ResponseWrapper プロパティー

プロパティー説明

localName

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

targetNamespace

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

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

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

targetNamespace

fault 要素が定義される namespace を指定します。デフォルト値は SEI のターゲット namespace です。

faultName

例外を実装する Java クラスの完全な名前を指定します。

重要

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

プロパティー値説明

name

 

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

targetNamespace

 

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

mode

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

Mode.OUT

Mode.INOUT

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

header

false (デフォルト)

true

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

partName

 

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

[a] Holder インターフェースを実装するパラメーターは、デフォルトで 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

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

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
  );
}