4 JWSファイルのプログラミング

この章では、Java API for XML-based Web services (JAX-WS)を使用したWebLogic Webサービスを実装するJWSファイルのプログラミング方法について説明します。

この章では、以下のトピックについて説明します。

• JWSファイルとJWSアノテーションの概要

• JWSファイルのJava要件

• JWSファイルのプログラミング: 一般的な手順

• Webサービスの実行時情報へのアクセス

• ステートレス・セッションEJBを実装すべき場合

• ユーザー定義のJavaデータ型のプログラミング

• JWSファイルからの別のWebサービスの呼出し

• SOAP 1.2の使用

• XMLスキーマの検証

• JWSプログラミングのベスト・プラクティス

JWSファイルとJWSアノテーションの概要

WebLogic Webサービスをゼロからプログラムする方法は2つあります。

1. JSR-181、JAX-WS仕様、およびWebLogic Webサービス・プログラミング・モデルで規定されているように、標準のEJBまたはJavaクラスにWebサービスJavaアノテーションを付けます。

2. デプロイメント記述子、WSDLファイル、データ・マッピング記述子、データ・バインディング・アーティファクト(ユーザー定義のデータ型用)など、JSR-109で指定されている様々なXML記述子ファイルやアーティファクトと、標準のEJBまたはJavaクラスを結合します。

上のオプション1を実行することを強くお薦めします。ユーザー自身がXMLメタデータ記述子を作成しなくても、必要な記述子やアーティファクトはJWSにユーザーが含めたアノテーションに基づいてWebLogic Antタスクおよびランタイムによって生成されます。このプロセスの方がはるかに簡単なだけでなく、Webサービスの情報が多数のJavaファイルやXMLファイル内に分散されず、JWSファイルで集中管理されます。

アノテーション付きのJava Webサービス(JWS)ファイルは、Webサービスの中核部分です。このファイルにはWebサービスの動作を決定するJavaコードが含まれています。JWSファイルは、Javaメタデータ・アノテーションを使用してWebサービスの形式や特性を指定した、通常のJavaクラス・ファイルです。JWSファイルでは、Web Services Metadata for the Java Platform仕様(JSR-181)(http://www.jcp.org/en/jsr/detail?id=181を参照)で定義される標準的なJWSアノテーションに加え、作成中のWebサービスの種類(JAX-WSまたはJAX-RPC)に基づいたその他のアノテーション・セットの使用が可能です。JAX-WS WebサービスおよびJAX-RPC Webサービスに対してサポートされているJWSアノテーションの完全なリストについては、『『Oracle WebLogic Server WebLogic Webサービス・リファレンス』』のWebサービスのアノテーション・サポートに関する項を参照してください。

JWSファイルをプログラミングする際は、基本的なWebサービス機能をプログラムするためにアノテーションを含めます。アノテーションは、JWSファイル内の様々なレベル、様々なターゲットで使用されます。一部はクラス・レベルで使用され、そのアノテーションがJWSファイル全体に適用されることを示します。また、メソッド・レベルで使用するものや、パラメータ・レベルで使用するものもあります。

JWSファイルのJava要件

JWSファイルをプログラミングする場合は、Web Services Metadata for the Java Platform仕様(JSR-181)(http://www.jcp.org/en/jsr/detail?id=181)で指定された一連の要件に従う必要があります。特に、Webサービスを実装するJavaクラスは、次の要件に従う必要があります。

• パブリック・クラスでなければなりません。finalクラスやabstractクラスとして宣言することはできません。

• デフォルトのパブリック・コンストラクタを持つ必要があります。

• finalize()メソッドは定義できません。

• 少なくとも、クラス・レベルで@WebService JWSアノテーションを指定して、そのJWSファイルがWebサービスを実装することを指定する必要があります。

• @WebService.endpointInterfaceアノテーションを使用して、サービス・エンドポイント・インタフェースを参照できます。この場合は、サービス・エンドポイント・インタフェースが存在することを前提としています。JWSファイルでは@WebService.endpointInterface、@WebService.serviceNameおよび@WebService.targetNamespace以外のJWSアノテーションを指定することはできません。

• JWSファイルにサービス・エンドポイント・インタフェースが実装されていない場合は、java.lang.Objectから継承されたもの以外のすべてのパブリック・メソッドが、Webサービス操作として公開されます。この動作は、@WebMethodアノテーションを使用して、公開するパブリック・メソッドを明示的に指定することによって、オーバーライドできます。@WebMethodアノテーションが存在する場合は、それが適用されるメソッドのみが公開されます。

JWSファイルのプログラミング: 一般的な手順

次の手順では、Webサービスを実装するJWSファイルをプログラミングするための一般的な手順を説明します。

注意: JWSファイルを作成してあり、そこにJWSアノテーションを追加する予定であることを前提としています。

各JWSアノテーションの詳細は、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のJWSアノテーション・リファレンスに関する項を参照してください。

表4-1 JWSファイルのプログラミング手順

#	手順	説明
1	JWSファイルで使用する標準のJWSアノテーションをインポートします。	標準のJWSアノテーションはjavax.jws、javax.jws.soap、またはjavax.xml.wsパッケージにあります。例: import javax.jws.WebMethod; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; import javax.xml.ws.BindingType;
2	必要に応じて、追加のアノテーションをインポートします。	サポートされているJWSアノテーションの完全なリストについては、『Oracle WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスのアノテーション・サポートに関する項を参照してください。
3	必須の標準@WebService JWSアノテーションをクラス・レベルで追加して、JavaクラスがWebサービスを公開することを指定します。	「JWSファイルがWebサービスを実装することの指定(@WebServiceアノテーション)」を参照してください。
4	標準の@SOAPBinding JWSアノテーションをクラス・レベルで追加して、WebサービスとSOAPメッセージ・プロトコルの間のマッピングを指定する(オプション)	特に、このアノテーションを使用して、Webサービスがドキュメント・リテラルか、ドキュメント・エンコードかなどを指定します。「WebサービスとSOAPメッセージ・プロトコルのマッピングの指定(@SOAPBindingアノテーション)」を参照してください。 このJWSアノテーションは必須ではありませんが、JWSファイルで明示的に指定し、クライアント・アプリケーションがWebサービスの呼出しに使用するSOAPバインディングのタイプを明確にすることをお薦めします。
5	クラス・レベルでJAX-WS @BindingType JWSアノテーションを追加し、Webサービス・エンドポイント実装クラスに使用するバインディング・タイプを指定します。(オプション)	「エンドポイントに使用するバインディングの指定(@BindingTypeアノテーション)」を参照してください。
6	パブリック操作として公開するJWSファイルの各メソッドで標準の@WebMethodアノテーションを追加する(オプション)	必要に応じて、標準の@Onewayアノテーションを使用し、その操作が入力パラメータだけを取り、値を返さないことを指定します。「JWSメソッドをパブリック操作として公開することの指定(@WebMethodおよび@OneWayアノテーション)」を参照してください。
7	@WebParamアノテーションを追加し、公開される操作の入力パラメータの名前をカスタマイズする(オプション)	「操作のパラメータとWSDL要素のマッピングのカスタマイズ(@WebParamアノテーション)」を参照してください。
8	@WebResultアノテーションを追加し、公開される操作の戻り値の名前と動作をカスタマイズする(オプション)	「操作の戻り値とWSDL要素のマッピングのカスタマイズ(@WebResultアノテーション)」を参照してください。
9	独自のビジネス・コードを追加します。	Webサービスが希望どおりに動作するように、独自のビジネス・コードをメソッドに追加します。

JWSファイルの例

次のサンプルJWSファイルでは、簡単なWebサービスの実装方法を示します。

package examples.webservices.simple;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Standard JWS annotation that specifies that the porType name of the Web
// Service is "SimplePortType", the service name is "SimpleService", and the
// targetNamespace used in the generated WSDL is "http://example.org"
@WebService(name="SimplePortType", serviceName="SimpleService",
            targetNamespace="http://example.org")
// Standard JWS annotation that specifies the mapping of the service onto the
// SOAP message protocol.  In particular, it specifies that the SOAP messages
// are document-literal-wrapped.
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
/**
 * This JWS file forms the basis of simple Java-class implemented WebLogic
 * Web Service with a single operation: sayHello
 *
 */
public class SimpleImpl {
  // Standard JWS annotation that specifies that the method should be exposed
  // as a public operation.  Because the annotation does not include the
  // member-value "operationName", the public name of the operation is the
 // same as the method name: sayHello.
  @WebMethod()
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

JWSファイルがWebサービスを実装することの指定(@WebServiceアノテーション)

次のコードの抜粋のように、標準の@WebServiceアノテーションを使用して、JWSファイルがWebサービスを実装することをクラス・レベルで指定します。

@WebService(name="SimplePortType", serviceName="SimpleService",
            targetNamespace="http://example.org")

この例では、Webサービスの名前はSimplePortTypeであり、jwsc Antタスクによって生成されるWSDLファイルのwsdl:portType要素に後でマップされます。サービス名はSimpleServiceであり、生成されるWSDLファイルのwsdl:service要素にマップされます。生成されるWSDLで使用されるターゲット・ネームスペースはhttp://example.orgです。

@WebServiceアノテーションの以下の追加の属性を指定することもできます。

• endpointInterface - 既存のサービス・エンドポイント・インタフェース・ファイルの完全修飾名。このアノテーションによって、実装からインタフェース定義を切り離すことができます。この属性を指定した場合、jwsc Antタスクはそのインタフェースを生成しません。そのインタフェースは作成されていて、CLASSPATHに入っていると想定します。

• portname - wsdl:port内で使用される名前。

@WebServiceアノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

WebサービスとSOAPメッセージ・プロトコルのマッピングの指定(@SOAPBindingアノテーション)

ここでは、WebサービスをSOAPメッセージ・プロトコルで使用できるようにします。そのためには、JWSファイル内にクラス・レベルで標準の@SOAPBindingアノテーションを含めて、WebサービスのSOAPバインディング(document-encodedまたはdocument-literal-wrappedなど)を指定します(次のコードの抜粋を参照)。

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

この例で、Webサービスはdocument-wrapped-styleエンコーディングとリテラル・メッセージ書式を使用しており、@SOAPBindingアノテーションを使用しない場合でも、これらはデフォルトの書式となります。一般に、最も相互運用性の高いタイプのWebサービスは、document-literal-wrappedのWebサービスです。

(style=SOAPBinding.Style.DOCUMENT属性と一緒に) parameterStyle属性を使用して、Webサービス操作のパラメータが、SOAPメッセージ本文全体を表すかどうか、操作と同じ名前の最上位要素内にラップされる要素かどうかを指定します。

次の表では、標準およびWebLogic固有の@SOAPBindingアノテーションの3つの属性の指定できる値とデフォルト値を示します。

表4-2 @SOAPBindingアノテーションの属性

属性	指定できる値	デフォルト値
style	SOAPBinding.Style.RPC SOAPBinding.Style.DOCUMENT	SOAPBinding.Style.DOCUMENT
use	SOAPBinding.Use.LITERAL	SOAPBinding.Use.LITERAL
parameterStyle	SOAPBinding.ParameterStyle.BARE SOAPBinding.ParameterStyle.WRAPPED	SOAPBinding.ParameterStyle.WRAPPED

JWSメソッドをパブリック操作として公開することの指定(@WebMethodおよび@OneWayアノテーション)

次のコードの抜粋で示すように、標準の@WebMethodアノテーションを使用して、JWSファイルのメソッドをWebサービスのパブリック操作として公開することを指定します。

public class SimpleImpl {
  @WebMethod(operationName="sayHelloOperation")
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
...

この例では、SimpleImpl JWSファイルのsayHello()メソッドが、Webサービスのパブリック操作として公開されます。ただし、operationName属性では、WSDLファイル内の操作のパブリック名はsayHelloOperationになることを指定しています。operationName属性を指定しない場合は、メソッドの名前が操作のパブリック名になります。

action属性を使用して操作のアクションを指定することもできます。SOAPをバインディングとして使用する場合、action属性の値によって、SOAPメッセージ内のSOAPActionヘッダーの値が決まります。

Webサービス操作としてメソッドを除外するには、@WebMethod(exclude="true")を指定します。

注意: サービス・エンドポイント・インタフェース(SEI)は、JAX-WSのためにパブリック・メソッドを定義します。SEIが存在しない場合、@WebMethod(exclude="true")で明示的にタグ付けされていなければ、すべてのパブリック・メソッドがWebサービス操作として公開されます。

標準の@Onewayアノテーションを使用して、操作が呼出し側アプリケーションに値を返さないことを指定できます。次の例を参照してください。

 public class OneWayImpl {
  @WebMethod()
  @Oneway()
  public void ping() {
    System.out.println("ping operation");
  }
...

操作が一方向であることを指定する場合、実装するメソッドはvoidを返す必要があります。パラメータとしてホルダー・クラスを使用したり、チェック済み例外をスローしたりすることはできません。

@WebMethodアノテーションの属性はいずれも必須ではありません。@WebMethodおよび@Onewayアノテーションに関する追加情報や、各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

操作のパラメータとWSDL要素のマッピングのカスタマイズ(@WebParamアノテーション)

次のコードの抜粋で示すように、標準の@WebParamアノテーションを使用して、Webサービス操作の入力パラメータと生成されるWSDLファイルの要素間のマッピングのカスタマイズや、パラメータ動作の指定を行います。

 public class SimpleImpl {
  @WebMethod()
  @WebResult(name="IntegerOutput",
             targetNamespace="http://example.org/docLiteralBare")
  public int echoInt(
      @WebParam(name="IntegerInput",
                targetNamespace="http://example.org/docLiteralBare")
      int input)
  {
      System.out.println("echoInt '" + input + "' to you too!");
      return input;
  }
...

この例では、生成されるWSDLファイル内のechoInt操作のパラメータ名はIntegerInputになります。JWSファイルに@WebParamアノテーションがない場合、生成されるWSDLファイル内のパラメータ名は、メソッドのパラメータ名inputと同じになります。targetNamespace属性は、パラメータのXMLネームスペースがhttp://example.org/docLiteralBareであることを指定します。この属性は、パラメータとXML要素がマップされる、ドキュメント・スタイルのSOAPバインディングを使用する場合にのみ有効です。

@WebParamアノテーションの以下の追加の属性を指定することもできます。

• mode - パラメータの入出力の方向(WebParam.Mode.IN、WebParam.Mode.OUT、またはWebParam.Mode.INOUT)。OUTおよびINOUTモードは、RPC形式の操作、またはヘッダーにマップされるパラメータでのみサポートされます。

• header - trueに設定した場合、パラメータの値はデフォルトの本文からではなくSOAPヘッダーから取得されることを指定する、ブール型の属性。

@WebParamアノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

操作の戻り値とWSDL要素のマッピングのカスタマイズ(@WebResultアノテーション)

次のコードの抜粋で示すように、標準の@WebResultアノテーションを使用して、Webサービス操作の戻り値と生成されるWSDLファイル内の対応する要素との間のマッピングをカスタマイズします。

public class Simple {
  @WebMethod()
  @WebResult(name="IntegerOutput",
             targetNamespace="http://example.org/docLiteralBare")
  public int echoInt(
      @WebParam(name="IntegerInput",
                targetNamespace="http://example.org/docLiteralBare")
      int input)
  {
      System.out.println("echoInt '" + input + "' to you too!");
      return input;
  }
...

この例では、生成されるWSDLファイル内のechoInt操作の戻り値の名前はIntegerOutputになります。JWSファイルに@WebResultアノテーションがない場合、生成されるWSDLファイル内の戻り値の名前は、ハード・コード化された名前returnになります。targetNamespace属性は、戻り値のXMLネームスペースがhttp://example.org/docLiteralBareであることを指定します。この属性は、戻り値とXML要素がマップされる、ドキュメント・スタイルのSOAPバインディングを使用する場合にのみ有効です。

@WebResultアノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181)仕様(http://www.jcp.org/en/jsr/detail?id=181)を参照してください。

エンドポイントに使用するバインディングの指定(@BindingTypeアノテーション)

JAX-WS @BindingTypeアノテーションを使用すると、Webサービス・エンドポイント実装クラスに使用するバインディングをカスタマイズすることができます。次のコードの抜粋を参照してください。

import javax.xml.ws.BindingType;
import javax.xml.ws.soap.SOAPBinding;
 public class Simple {
  @WebService()
  @BindingType(value=SOAPBinding.SOAP12HTTP_BINDING)
  public int echoInt(
      @WebParam(name="IntegerInput",
                targetNamespace="http://example.org/docLiteralBare")
      int input)
  {
      System.out.println("echoInt '" + input + "' to you too!");
      return input;
  }
...

この例のデプロイメントされたエンドポイントでは、SOAP1.2 over HTTPバインディングが使用されます。何も指定しない場合、バインディングのデフォルトはSOAP 1.1 over HTTPになります。

@BindingTypeアノテーションの以下の追加属性を指定することもできます。

• features - 指定したバインディングにおいて有効化/無効化する機能の配列。指定しない場合、機能は独自規則に基づいて有効化されます。

@BindingTypeアノテーションの詳細は、JAX-WS 2.1アノテーション(http://docs.oracle.com/javaee/5/api/javax/xml/ws/BindingType.html)を参照してください。

Webサービスの実行時情報へのアクセス

クライアント・アプリケーションが、JWSファイルで実装されたWebLogic Webサービスを呼び出すと、WebLogic Serverは、Webサービスやクライアントが、サービスに関する実行時情報のアクセス、および場合によっては変更に使用できるコンテキストを自動的に作成します。

実行時情報には、以下のいずれかの方法でアクセスできます。

• javax.xml.ws.BindingProvider(http://download.oracle.com/javaee/5/api/javax/xml/ws/BindingProvider.html)- クライアント・アプリケーションから、プロトコル・バインディングのリクエストおよびレスポンス・コンテキストへアクセスします。「プロトコル・バインディング・コンテキストへのアクセス」を参照してください。

• javax.xml.ws.WebServiceContext(http://download.oracle.com/javaee/5/api/javax/xml/ws/WebServiceContext.html)- Webサービスから、処理されているリクエストに関連する実行時メッセージ・コンテキストやセキュリティ情報にアクセスします。WebServiceContextは通常、@Resourceアノテーションを使用してエンドポイントにインジェクトされます。「Webサービス・コンテキストへのアクセス」を参照してください。

• javax.xml.ws.handler.MessageContext(http://download.oracle.com/javaee/5/api/javax/xml/ws/handler/MessageContext.html)- WebサービスのWebServiceContextから直接、あるいはクライアント・アプリケーションやWebサービスのメッセージ・ハンドラから実行時プロパティ・セットへアクセスします。「MessageContextプロパティ値の使用」を参照してください。

以降の項では、BindingProvider、WebServiceContext、およびMessageContextを使用して実行時情報へアクセスする方法の詳細を説明します。

プロトコル・バインディング・コンテキストへのアクセス

注意: com.sun.xml.ws.developer.JAXWSPropertiesおよびcom.sun.xml.ws.client.BindingProviderProperties APIは、JDK 6.0の拡張としてサポートされています。これらのAPIはJDK 6.0キットの一部としては提供されないため、変更される可能性があります。

javax.xml.ws.BindingProviderインタフェースを使用すると、クライアント・アプリケーションから、プロトコル・バインディングのリクエストおよびレスポンス・コンテキストへアクセスすることができます。詳細については、http://download.oracle.com/javaee/5/api/javax/xml/ws/BindingProvider.htmlを参照してください。Webサービス・クライアント・ファイルの開発の詳細は、「Webサービスの呼出し」を参照してください。

次に、コンテキストを使用してHTTPリクエスト・ヘッダー情報へアクセスする簡単なWebサービス・クライアント・アプリケーションの例を示します。太字のコードについては、例の後のプログラミングのガイドラインで説明しています。

package examples.webservices.hello_world.client;

import javax.xml.namespace.QName;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Map;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.MessageContext;
import com.sun.xml.ws.developer.JAXWSProperties;
import com.sun.xml.ws.client.BindingProviderProperties;

/**
 * This is a simple standalone client application that invokes the
 * the <code>sayHelloWorld</code> operation of the Simple Web service.
 */

public class Main {
  public static void main(String[] args) {
    HelloWorldService service;
    try { 
       service = new HelloWorldService(new URL(args[0] + "?WSDL"), 
           new QName("http://hello_world.webservices.examples/", 
           "HelloWorldService") );
    } catch (MalformedURLException murl) { throw new RuntimeException(murl); }
      HelloWorldPortType port = service.getHelloWorldPortTypePort();
      String result = null;
      result = port.sayHelloWorld("Hi there!");
      System.out.println( "Got result: " + result );
      Map requestContext = ((BindingProvider)port).getRequestContext();
      requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
                       "http://examples.com/HelloWorldImpl/HelloWorldService");
      requestContext.put(JAXWSProperties.CONNECT_TIMEOUT, 300); 
      requestContext.put(BindingProviderProperties.REQUEST_TIMEOUT, 300); 
      Map responseContext = ((BindingProvider)port).getResponseContext();
      Integer responseCode = 
               (Integer)responseContext.get(MessageContext.HTTP_RESPONSE_CODE);
...
  }
}

この例の太字のコードで示すように、Webサービスの実行時コンテキストにアクセスするには、JWSファイルで次のガイドラインに従います。

• javax.xml.ws.BindingProvider APIに加え、使用する可能性のあるその他の関連APIをインポートします。

  import java.util.Map;
  import javax.xml.ws.BindingProvider;
  import javax.xml.ws.handler.MessageContext;
  import com.sun.xml.ws.developer.JAXWSProperties;
  import com.sun.xml.ws.client.BindingProviderProperties;
  import com.sun.xml.ws.client.BindingProviderProperties;
  

• BindingProviderクラスのメソッドを使用して、バインディング・プロトコル・コンテキスト情報へアクセスします。次の例は、プロトコル・バインディングのリクエストおよびレスポンス・コンテキストを取得してからリクエスト・コンテキスト用にクライアントで使用されるターゲットのサービス・エンドポイント・アドレスを設定し、リクエスト・コンテキストの接続や読取りのタイムアウト時間(ミリ秒単位)とHTTPレスポンス・ステータス・コードを設定する方法を示しています。

  Map requestContext = ((BindingProvider)port).getRequestContext();
  requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
                      "http://examples.com/HelloWorldImpl/HelloWorldService");
  requestContext.put(JAXWSProperties.CONNECT_TIMEOUT, 300); 
  requestContext.put(BindingProviderProperties.REQUEST_TIMEOUT, 300); 
  Map responseContext = ((BindingProvider)port).getResponseContext();
  Integer responseCode = 
           (Integer)responseContext.get(MessageContext.HTTP_RESPONSE_CODE);
  

次の表は、Webサービスに関する実行時情報にアクセスするためにJWSファイルで使用できるjavax.xml.ws.BindingProviderのメソッドの要約を示します。

表4-3 BindingProviderのメソッド

メソッド	戻り値	説明
getBinding()	バインディング	バインディング・プロバイダのバインディングを返します。
getRequestContext()	java.Util.Map	リクエスト・メッセージのコンテキストおよびメッセージの初期化に使用されるコンテキストを返します。
getResponseContext()	java.Util.Map	レスポンス・コンテキストを返します。

リクエストおよびレスポンス・コンテキストを取得したら、次の表で定義しているBindingProviderプロパティ値と、「MessageContextプロパティ値の使用」で定義しているMessageContextプロパティ値にアクセスできます。

表4-4 BindingProviderのプロパティ

プロパティ	タイプ	説明
ENDPOINT_ADDRESS_PROPERTY	java.lang.String	ターゲットのサービス・エンドポイント・アドレス。
PASSWORD_PROPERTY	java.lang.String	認証用パスワード。
SESSION_MAINTAIN_PROPERTY	java.lang.Boolean	サービス・クライアントがサービス・エンドポイントとのセッションに参加するかどうかを示すフラグ。デフォルト値のfalseは、サービス・クライアントが参加しないことを示します。
SOAPACTION_URI_PROPERTY	java.lang.String	SOAPAction URI.を指定するSOAPActionのプロパティ。このプロパティは、SOAPACTION_USE_PROPERTYがtrueに設定されている場合にのみ有効です。
SOAPACTION_USE_PROPERTY	java.lang.Boolean	SOAPActionを使用するかどうかを指定するSOAPActionのプロパティ。
USERNAME_PROPERTY	java.lang.String	認証用ユーザー名。

また、前の例の以下の点に注目してください。

• JAXWSProperties.CONNECT_TIMEOUTプロパティを使用して接続タイムアウトを定義しています。設定可能なJAXWSPropertiesの完全なリストは、com.sun.xml.ws.developer.JAXWSPropertiesのJavadoc (http://jax-ws.java.net/nonav/jax-ws-20-fcs/arch/com/sun/xml/ws/developer/JAXWSProperties.html#CONNECT_TIMEOUT)を参照してください。

• BindingProviderProperties.REQUEST_TIMEOUTプロパティを使用してリクエスト・タイムアウトを定義しています。設定可能なBindingProviderPropertiesの完全なリストは、com.sun.xml.ws.client.BindingProviderPropertiesのJavadoc (http://jax-ws.java.net/nonav/jax-ws-20-fcs/arch/com/sun/xml/ws/client/BindingProviderProperties.html#REQUEST_TIMEOUT)を参照してください。

Webサービス・コンテキストへのアクセス

javax.xml.ws.WebServiceContextインタフェースを使用すると、Webサービスから、処理されているリクエストに関連する実行時メッセージ・コンテキストやセキュリティ情報にアクセスできます。WebServiceContextは通常、@Resourceアノテーションを使用してエンドポイントにインジェクトされます。詳細は、http://download.oracle.com/javaee/5/api/javax/xml/ws/WebServiceContext.htmlを参照してください。

次に、コンテキストを使用してHTTPリクエスト・ヘッダー情報へアクセスする簡単なJWSファイルの例を示します。太字のコードについては、例の後のプログラミングのガイドラインで説明しています。

package examples.webservices.jws_context;
import javax.jws.WebMethod;
import javax.jws.WebService;
import java.util.Map;
import javax.xml.ws.WebServiceContext;
import javax.annotation.Resource;
import javax.xml.ws.handler.MessageContext;
@WebService(name="JwsContextPortType", serviceName="JwsContextService",
            targetNamespace="http://example.org")
/**
 * Simple web service to show how to use the @Context annotation.
 */
public class JwsContextImpl {
  @Resource
  private WebServiceContext ctx; 
  @WebMethod()
  public String msgContext(String msg) {
    MessageContext context=ctx.getMessageContext();
    Map requestHeaders = (Map)context.get(MessageContext.HTTP_REQUEST_HEADERS);
  }
}

この例の太字のコードで示すように、Webサービスの実行時コンテキストにアクセスするには、JWSファイルで次のガイドラインに従います。

• @javax.annotation.Resource JWSアノテーションをインポートします。

  import javax.annotation.Resource;
  

• javax.xml.ws.WebServiceContext APIに加え、使用する可能性のあるその他の関連APIをインポートします。

  import java.util.Map;
  import javax.xml.ws.WebServiceContext;
  import javax.xml.ws.handler.MessageContext;
  

• データ型javax.xml.ws.WebServiceContextのプライベート変数に、フィールド・レベルの@Resource JWSアノテーションを指定します。

  @Resource
  private WebServiceContext ctx; 
  

• WebServiceContextクラスのメソッドを使用して、Webサービスの実行時情報にアクセスします。次の例は、現在のサービス・リクエストのメッセージ・コンテキストを取得してから、HTTPリクエスト・ヘッダーにアクセスする方法を示しています。

  MessageContext context=ctx.getMessageContext();
  Map requestHeaders = (Map)context.get(MessageContext.HTTP_REQUEST_HEADERS)
  

  MessageContextプロパティ値の詳細は、「MessageContextプロパティ値の使用」を参照してください。

次の表は、Webサービスに関する実行時情報にアクセスするためにJWSファイルで使用できるjavax.xml.ws.WebServiceContextのメソッドの要約を示します。詳細は、http://download.oracle.com/javaee/5/api/javax/xml/ws/WebServiceContext.htmlを参照してください。

表4-5 WebServiceContextのメソッド

メソッド	戻り値	説明
getMessageContext()	MessageContext	現在のサービス・リクエストのMessageContextを返します。MessageContextプロパティ値の使用で定義しているように、HTTP_REQUEST_HEADERSやMESSAGE_ATTACHMENTSなど、アプリケーション・スコープのプロパティのみアクセス可能です。
getUserPrincipal()	java.security.Principal	現在のサービス・リクエストの送信者を識別するプリンシパルを返します。送信者が認証されていない場合、nullを返します。
isUserInRole(java.lang.String role)	boolean	指定された論理的なロールに認証ユーザーが含まれているかどうかを示すブール値を返します。ユーザーが認証されていない場合、falseを返します。

MessageContextプロパティ値の使用

次の表では、WebサービスのWebServiceContextから直接、あるいはクライアント・アプリケーションやWebサービスのメッセージ・ハンドラからアクセス可能なjavax.xml.ws.handler.MessageContextプロパティ値を示しています。詳細は、javax.xml.ws.handler.MessageContext Javadoc(http://download.oracle.com/javaee/5/api/javax/xml/ws/handler/MessageContext.html)を参照してください。

表4-6 MessageContextのプロパティ

プロパティ	タイプ	説明
HTTP_REQUEST_HEADERS	java.util.Map	リクエスト・メッセージのHTTPリクエスト・ヘッダーのマップ。
HTTP_REQUEST_METHOD	java.lang.String	GET、POST、PUTなどのHTTPリクエスト・メソッド。
HTTP_RESPONSE_CODE	java.lang.Integer	最終呼出しのHTTPレスポンス・ステータス・コード。
HTTP_RESPONSE_HEADERS	java.util.Map	HTTPレスポンス・ヘッダー。
INBOUND_MESSAGE_ATTACHMENTS	java.util.Map	着信メッセージの添付のマップ。
MESSAGE_OUTBOUND_PROPERTY	java.lang.Boolean	メッセージの方向。このプロパティは、発信メッセージの場合はtrue、着信メッセージの場合はfalseです。
OUTBOUND_MESSAGE_ATTACHMENTS	java.util.Map	発信メッセージの添付のマップ。
PATH_INFO	java.lang.String	リクエスト・パス情報。
QUERY_STRING	java.lang.String	リクエストの問合せ文字列。
REFERENCE_PARAMETERS	java.awt.List	WS-Addressing参照パラメータ。リストには、wsa:IsReferenceParameter="true"属性がマークされているすべてのSOAPヘッダーを含める必要があります。
SERVLET_CONTEXT	javax.servlet.ServletContext	リクエストに関連するサーブレット・コンテキスト・オブジェクト。
SERVLET_REQUEST	javax.servlet.http.HttpServletRequest	リクエストに関連するサーブレット・リクエスト・オブジェクト。
SERVLET_RESPONSE	javax.servlet.http.HttpServletResponse	リクエストに関連するサーブレット・レスポンス・オブジェクト。
WSDL_DESCRIPTION	org.xml.sax.InputSource	WSDLドキュメントの入力ソース(解決可能なURI)。
WSDL_INTERFACE	javax.xml.namespace.QName	ポート・タイプまたはWSDLインタフェースの名前。
WSDL_OPERATION	javax.xml.namespace.QName	現在のメッセージが所属するWSDL操作の名前。
WSDL_PORT	javax.xml.namespace.QName	メッセージを受け取ったWSDLポートの名前。
WSDL_SERVICE	javax.xml.namespace.QName	呼出し対象サービスの名前。

ステートレス・セッションEJBを実装すべき場合

jwsc Antタスクでは、JWSファイルを処理するときは常に、Webサービスの基底の実装としてプレーンJavaオブジェクトが選択されます。

しかし、Webサービスの基底の実装をステートレス・セッションEJBにして、EJBが提供するすべての機能(インスタンス・プール、トランザクション、セキュリティ、コンテナ管理による永続性、コンテナ管理による関連、データ・キャッシュなど)を使用することが必要な場合もあります。Webサービスの実装をEJBにする場合は、次のセクションのプログラミング・ガイドラインに従ってください。

EJB 3.0では、EJBを実装する場合に必要なEJBリモートおよびホーム・インタフェース・クラスおよびデプロイメント記述子ファイルを、手動で作成するのではなく、自動的に生成することができるメタデータ・アノテーションが導入されました。EJB 3.0の詳細は、『Oracle WebLogic Server WebLogic Enterprise JavaBeansバージョン3.0のプログラミング』を参照してください。

JWSファイルにEJBを実装するには、次の手順に従います。

• EJB 3.0アノテーションをインポートします。これらのアノテーションはすべてjavax.ejbパッケージにあります。少なくとも、@Statelessアノテーションはインポートする必要があります。JWSファイルにはEJBの形式および動作を指定する追加のEJBアノテーションを指定することもできます。詳細は、javax.ejb Javadoc (http://download.oracle.com/javaee/5/api/javax/ejb/package-summary.html)を参照してください。

  例:

  import javax.ejb.Stateless;
  

• 少なくとも、クラス・レベルで@Statelessアノテーションを使用し、EJBを識別します。

  @Stateless
  public class SimpleEjbImpl {
  

以下の例では、ステートレス・セッションEJBを実装する簡単なJWSファイルを示します。関連するコードは太字で示されています。

package examples.webservices.jaxws;

import weblogic.transaction.TransactionHelper;
import javax.ejb.Stateless;
import javax.ejb.SessionContext;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.annotation.Resource;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.transaction.SystemException;
import javax.transaction.Status;
import javax.transaction.Transaction;
import javax.xml.ws.WebServiceContext;

/**
* A transaction-awared stateless EJB-implemented JWS
*/

// Standard JWS annotation that specifies that the portName,serviceName and
// target Namespace of the Web Service.
@WebService(
      name = "Simple",
      portName = "SimpleEJBPort",
      serviceName = "SimpleEjbService",
      targetNamespace = "http://wls/samples")

//Standard EJB annotation
@Stateless
public class SimpleEjbImpl {

   @Resource
   private WebServiceContext context;
   private String constructed = null;

   // The WebMethod annotation exposes the subsequent method as a public
   // operation on the Web Service.
   @WebMethod()
   @TransactionAttribute(TransactionAttributeType.REQUIRED)
   public String sayHello(String s) throws SystemException {
      Transaction transaction =     
         TransactionHelper.getTransactionHelper().getTransaction();
      int status = transaction.getStatus();
      if (Status.STATUS_ACTIVE != status)
           throw new IllegalStateException("transaction did not start, 
           status is: " + status + ", check ejb annotation processing");

   return constructed + ":" + s;
}

ユーザー定義のJavaデータ型のプログラミング

Webサービス操作として公開されるJWSファイルのメソッドでは、パラメータや戻り値として必ずしも組込みのデータ型(Stringやintegerなど)を使用する必要はなく、独自に作成するJavaデータ型を使用することができます。ユーザー定義のデータ型の例としては、Stringの銘柄記号とintegerの売買株式数という2つのフィールドを持つTradeResultがあります。

JWSファイルで、1つまたは複数のメソッドのパラメータまたは戻り値としてユーザー定義のデータ型を使用する場合は、データ型のJavaコードを独自に作成して、JWSファイルにそのクラスをインポートし、適切に使用する必要があります。必要なデータ・バインディング・アーティファクトはすべて、jwsc Antタスクが後で作成します。

ユーザー定義のデータ型のJavaコードを記述するときは、以下の基本的な要件に従います。

• デフォルト・コンストラクタを定義します。これは、パラメータを取らないコンストラクタです。

• 公開するメンバー変数ごとにgetXXX()メソッドとsetXXX()メソッドの両方を定義します。

• 公開される各メンバー変数のデータ型は、組込みデータ型のいずれか、または組込みデータ型で構成されるユーザー定義のデータ型にします。

注意: カスタム・マッピングを提供するにはJAXBを使用することができます。詳細は、「JAXBアノテーションを使用したJava-to-XMLスキーマ・マッピングのカスタマイズ」を参照してください。

jwsc Antタスクでは、最も一般的なXMLおよびJavaデータ型のデータ・バインディング・アーティファクトを生成できます。サポートされるユーザー定義のデータ型のリストは、「サポートされるユーザー定義のデータ型」を参照してください。サポートされる組込みデータ型の完全なリストは、「サポートされる組込みデータ型」参照してください。

次の例では、BasicStructという簡単なユーザー定義のJavaデータ型を示します。

package examples.webservices.complex;
/**
 * Defines a simple JavaBean called BasicStruct that has integer, String,
 * and String[] properties
 */
public class BasicStruct {
  // Properties
  private int intValue;
  private String stringValue;
  private String[] stringArray;
  // Getter and setter methods
  public int getIntValue() {
    return intValue;
  }
  public void setIntValue(int intValue) {
    this.intValue = intValue;
  }
  public String getStringValue() {
    return stringValue;
  }
  public void setStringValue(String stringValue) {
    this.stringValue = stringValue;
  }
  public String[] getStringArray() {
    return stringArray;
  }
  public void setStringArray(String[] stringArray) {
    this.stringArray = stringArray;
  }
}

以下のJWSファイルの抜粋では、BasicStructクラスをインポートして、1つのメソッドのパラメータおよび戻り値として使用する方法を示しています。完全なJWSファイルについては、「サンプルComplexImpl.java JWSファイル」を参照してください。

package examples.webservices.complex;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the WebLogic-specific JWS annotation interface
// Import the BasicStruct JavaBean
import examples.webservices.complex.BasicStruct;
@WebService(serviceName="ComplexService", name="ComplexPortType",
            targetNamespace="http://example.org")
...
public class ComplexImpl {
  @WebMethod(operationName="echoComplexType")
  public BasicStruct echoStruct(BasicStruct struct)
  {
    return struct;
  }
}

JWSファイルからの別のWebサービスの呼出し

JWSファイル内から別のWebサービス(WebLogic ServerにデプロイされているWebサービス、または.NETなどの他のアプリケーション・サーバーにデプロイされているWebサービス)を呼び出すことができます。その手順は、「Java SEアプリケーションからのWebサービスの呼出し」で説明した手順と似ています(ただしこの場合は、clientgen Antタスクを実行してクライアント・スタブを生成するのではなく、呼出し側のWebサービスを構築するjwsc Antタスクに<clientgen>子要素を含めてクライアント・スタブを生成します)。その後は、Java SEクライアント・アプリケーションの場合と同じように、JWSファイル内で標準のJAX-WS APIを使用します。

詳細な手順については、「WebLogic WebサービスからのWebサービスの呼出し」を参照してください。

SOAP 1.2の使用

WebLogic Webサービスでは、Webサービスとそのクライアントの間でデータや呼出しを転送する際に、メッセージ・フォーマットとしてデフォルトでバージョン1.1のSOAP (Simple Object Access Protocol)が使用されます。WebLogic Webサービスでは、SOAP 1.1と新しいSOAP 1.2の両バージョンがサポートされており、どちらのバージョンでも使用できます。

Webサービスでバージョン1.2のSOAPを使用することを指定するには、JWSファイルでクラス・レベルの@javax.xml.ws.BindingTypアノテーションを使用し、次の例に示すようにその唯一の属性の値をSOAPBinding.SOAP12HTTP_BINDINGに設定します(該当部分は太字で示してあります)。

package examples.webservices.soap12;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.BindingType;
import javax.xml.ws.SOAPBinding;
@WebService(name="SOAP12PortType",
            serviceName="SOAP12Service",
            targetNamespace="http://example.org")
@BindingType(value = SOAPBinding.SOAP12HTTP_BINDING)
/**
 * This JWS file forms the basis of simple Java-class implemented WebLogic
 * Web Service with a single operation: sayHello.  The class uses SOAP 1.2
 * as its binding.
 *
 */
public class SOAP12Impl {
  @WebMethod()
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

WebサービスでSOAP 1.2を使用する上で、Webサービスを呼び出すクライアント・アプリケーションを変更する場合も含め、このアノテーションを設定する以外の設定は必要ありません。WebLogic Webサービス・ランタイムによってすべて自動的に処理されます。

XMLスキーマの検証

デフォルトでは、SOAPメッセージはXMLスキーマに対して検証されません。後続のセクションで説明するように、サーバーまたはクライアントでドキュメント・リテラルWebサービスに対してXMLスキーマ検証を有効化することができます。SOAPメッセージが無効の場合は、SOAPフォルトが返されます。

注意: この機能により、Webサービス・リクエストに対してわずかな処理が追加されます。 デフォルトでは、SOAPフォルトの詳細にはスタック・トレースが含まれます。スタック・トレースの無効化については、『Oracle WebLogic Server JAX-WS Webサービスの高度な機能のプログラミング』のスタック・トレースの無効化に関する項を参照してください。

サーバーでのスキーマ検証の有効化

注意: com.sun.xml.ws.developer.SchemaValidation APIは、JDK 6.0の拡張としてサポートされています。このAPIはJDK 6.0キットの一部としては提供されないため、変更される可能性があります。

サーバーでスキーマ検証を有効化するには、エンドポイント実装で@SchemaValidationアノテーションを追加します。例:

import com.sun.xml.ws.developer.SchemaValidation;
import javax.jws.WebService;
@SchemaValidation
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
public class HelloWorldImpl {
  public String sayHelloWorld(String message) {
    System.out.println("sayHelloWorld:" + message);
    return "Here is the message: '" + message + "'";
  }
}

アプリケーション内のエラーを管理する場合、独自の検証エラー・ハンドラ・クラスを引数としてアノテーションに渡すことができます。例:

@SchemaValidation(handler=ErrorHandler.class)

クライアントでのスキーマ検証の有効化

注意: com.sun.xml.ws.developer.SchemaValidation APIは、JDK 6.0の拡張としてサポートされています。このAPIはJDK 6.0キットの一部としては提供されないため、変更される可能性があります。

クライアントでスキーマ検証を有効化するには、SchemaValidationFeatureオブジェクトを作成し、PortTypeスタブ実装の作成時に引数として渡します。

package examples.webservices.hello_world.client;
import com.sun.xml.ws.developer.SchemaValidationFeature;
import javax.xml.namespace.QName;
import java.net.MalformedURLException;
import java.net.URL;
public class Main {
  public static void main(String[] args) {
    HelloWorldService service;
    try {
      service = new HelloWorldService(new URL(args[0] + "?WSDL"), 
                new QName("http://example.org", "HelloWorldService") );
    } catch (MalformedURLException murl) { throw new RuntimeException(murl); }
      SchemaValidationFeature feature = 
           new SchemaValidationFeature();
       HelloWorldPortType port = service.getHelloWorldPortTypePort(feature);
      String result = null;
      result = port.sayHelloWorld("Hi there!");
      System.out.println( "Got result: " + result );
  }
}

アプリケーション内のエラーを管理する場合、独自の検証エラー・ハンドラを引数としてSchemaValidationFeatureオブジェクトに渡すことができます。例:

      SchemaValidationFeature feature = 
           new SchemaValidationFeature(MyErrorHandler.class);
       HelloWorldPortType port = service.getHelloWorldPortTypePort(feature);

JWSプログラミングのベスト・プラクティス

以下のリストでは、JWSファイルをプログラミングする場合のベスト・プラクティスを示します。

• document-literal-bareのWebサービスを作成する場合は、@WebParam JWSアノテーションを使用して、特定のWebサービスのすべての操作のすべての入力パラメータに一意の名前を付けるようにします。document-literal-bareのWebサービスの性質上、@WebParamアノテーションを使用して入力パラメータの名前を明示的に指定しない場合、WebLogic Serverが入力パラメータの名前を作成するため、Webサービス内でパラメータの名前が重複するおそれがあります。

• 一般に、最も相互運用性の高いタイプのWebサービスは、document-literal-wrappedのWebサービスです。

• ハード・コード化された名前returnに常に依存するのではなく、@WebResult JWSアノテーションを使用して、操作の戻り値の名前を明示的に設定します。JWSファイルで@WebResultアノテーションを使用しない場合、returnが戻り値のデフォルト名になります。