JAX-RPC を使用した WebLogic Web サービスの開始

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

以下の節では、Web サービスを実装する JWS ファイルのプログラミングについて説明します。

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

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

Oracle では、上記のオプション 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) で定義される標準的な JWS アノテーションに加え、作成中の Web サービスの種類 (JAX-WS または JAX-RPC) に基づいたその他のアノテーション セットの使用が可能です。JAX-WS Web サービスおよび JAX-RPC Web サービスに対してサポートされている JWS アノテーションの完全なリストについては、『WebLogic Web サービス リファレンス』の「Web Service Annotation Support」を参照してください。

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

JWS ファイルの Java 要件

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

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

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

各 JWS アノテーションの詳細については、『WebLogic Web サービス リファレンス』の「JWS アノテーション リファレンス」を参照してください。他の JWS アノテーションを使用して、より高度な機能 (Web サービスの信頼性のあるメッセージング、会話、SOAP メッセージ ハンドラなど) をプログラミングする方法については、『JAX-RPC を使用した WebLogic Web サービスの高度な機能のプログラミング』を参照してください。

JWS ファイルの例

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

package examples.webservices.simple;

// 標準の JWS アノテーション インタフェースをインポートする

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

// WebLogic 固有の JWS アノテーション インタフェースをインポートする

import weblogic.jws.WLHttpTransport;

// Web サービスの portType 名を「SimplePortType」、サービス名を「SimpleService」、
// 生成される WSDL で使用される targetNamespace を「http://example.org」と指定する、
// 標準の JWS アノテーション

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

// サービスと SOAP メッセージ プロトコルのマッピングを指定する、
// 標準の JWS アノテーション。特に、SOAP メッセージが 
// document-literal-wrapped 型であることを指定する

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

// Web サービスの URI を構成するのに使用されるコンテキスト パスとサービス URI が
// 「simple/SimpleService」であることを指定する、
// WebLogic 固有の JWS アノテーション

@WLHttpTransport(contextPath="simple", serviceUri="SimpleService",
                 portName="SimpleServicePort")

/**
 * この JWS ファイルは、1 つのオペレーション sayHello を含む簡単な
 * Java クラス実装の WebLogic Web サービスの基本となる
 *
 */

public class SimpleImpl {

  // メソッドがパブリック オペレーションとしてエクスポーズされることを指定する、
  // 標準の JWS アノテーション。アノテーションにはメンバー値の
  // 「operationName」が含まれていないので、オペレーションのパブリック名は
  // メソッド名 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 アノテーションの以下の追加の属性を指定することもできます。

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

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

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

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

この例で、Web サービスは document-wrapped-style エンコーディングとリテラル メッセージ フォーマットを使用しています。@SOAPBinding アノテーションを使用しない場合でも、これらはデフォルトのフォーマットとなります。

WebLogic 固有の @weblogic.jws.soap.SOAPBinding アノテーションを使用して、メソッド レベルの SOAP バインディングを指定することもできます。属性は、標準の @javax.jws.soap.SOAPBinding アノテーションと同じです。

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

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

Web サービスのコンテキスト パスとサービス URI の指定 (@WLHttpTransport アノテーション)

WebLogic 固有の @WLHttpTransport アノテーションを使用して、HTTP 転送で Web サービスを呼び出すために使用する URL のコンテキスト パスとサービス URI の部分、および生成される WSDL 内のポート名を指定します。次のコードの抜粋を参照してください。

@WLHttpTransport(contextPath="simple", serviceUri="SimpleService",
                 portName="SimpleServicePort")

この例では、jwsc Ant タスクによって生成される WSDL ファイル (具体的には <port> 要素の name 属性) 内のポート名は SimpleServicePort です。HTTP を介して Web サービスを呼び出すために使用する URL には、次の例のように、simple というコンテキスト パスと SimpleService というサービス URI が含まれます。

http://host:port/simple/SimpleService

このアノテーションやその他の WebLogic 固有の JWS アノテーションに関するリファレンス ドキュメントについては、『WebLogic Web サービス リファレンス』の「JWS アノテーション リファレンス」を参照してください。

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 ヘッダの値が決まります。

標準の @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) 仕様を参照してください。

JWS ファイル内のどのパブリック メソッドにも @WebMethod アノテーションを付けていない場合、デフォルトではすべてのパブリック メソッドが Web サービス オペレーションとしてエクスポーズされます。

オペレーションのパラメータと 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 アノテーションの以下の追加の属性を指定することもできます。

@WebParam アノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 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) 仕様を参照してください。

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

以下の節では、Web サービスの実行時情報へのアクセス方法について説明します。

JwsContext を使用した実行時情報へのアクセス

クライアント アプリケーションが、JWS ファイルで実装された WebLogic Web サービスを呼び出すと、WebLogic Server は、Web サービスが、サービスに関する実行時情報のアクセス、および場合によっては変更に使用できるコンテキストを自動的に作成します。この情報の多くは、現在の会話が終了したか、会話のプロパティの現在の値、実行時の会話のプロパティの変更など、会話に関連しています。会話と会話の実装方法については、『JAX-RPC を使用した WebLogic Web サービスの高度な機能のプログラミング』の「会話形式の Web サービスの作成」を参照してください。コンテキストを介してアクセス可能な情報には、Web サービスの呼び出しに使用されたプロトコル (HTTP/S または JMS)、SOAP メッセージ要求内にあった SOAP ヘッダなど、より一般的なものもあります。

以下の節で説明するように、JWS ファイルでアノテーションと WebLogic Web サービス API を使用して、実行時のコンテキスト情報にアクセスできます。

Web サービス コンテキストへのアクセスに関するガイドライン

以下に、コンテキストを使用して、Web サービスの呼び出しに使用されていたプロトコルを特定する簡単なサンプル JWS ファイルを示します。太字のコードについては、例の後のプログラミングのガイドラインで説明しています。

package examples.webservices.jws_context;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Context;

import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.Protocol;

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

@WLHttpTransport(contextPath="contexts", serviceUri="JwsContext",
                 portName="JwsContextPort")

/**
 * @Context アノテーションの使い方を示す簡単な Web サービス
 */

public class JwsContextImpl {

  @Context
  private JwsContext ctx;

  @WebMethod()
  public String getProtocol() {

    Protocol protocol = ctx.getProtocol();

    System.out.println("protocol: " + protocol);
    return "This is the protocol: " + protocol;
  }

}

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

JwsContext のメソッド

次の表では、Web サービスに関する実行時情報にアクセスするために JWS ファイルで使用できる JwsContext のメソッドについて簡単に説明します。JwsContext や、他のコンテキスト関連の API (Protocol および ServiceHandle) に関する詳細なリファレンス情報については、weblogic.wsee.* の Javadoc を参照してください。

Stub インタフェースを使用した実行時情報へのアクセス

javax.xml.rpc.Stub インタフェースによって、Web サービス クライアント ファイル内で Stub インスタンスを動的にコンフィグレーションすることができます。たとえば、次に示すように port Stub インスタンスに対して対象サービス エンドポイントを動的に設定できます。

ComplexService service = new ComplexService_Impl (args[0] + "?WSDL" );
ComplexPortType port = service.getComplexServicePort();
((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, 
   "http://localhost:8010/MyContext/MyService");

Web サービス クライアントの開発に関する詳細については、「Web サービスの呼び出し」を参照してください。

次の表では、Web サービスに関する実行時情報にアクセスするために JWS ファイルで使用できる Stub インタフェースのメソッドについて簡単に説明します。

次の表に、Stub インスタンスからアクセス可能な javax.xml.rpc.Stub プロパティの値を示します。

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

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

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

JWS ファイルで EJB を実装する場合のプログラミングのガイドライン

一般的なガイドラインは、JWS ファイルで常に EJBGen アノテーションを使用して、EJB を実装する場合に必要な EJB リモートおよびホーム インタフェース クラスおよびデプロイメント記述子ファイルを、手動で作成するのではなく、自動的に生成することです。EJBGen アノテーションは JWS アノテーションと同じように動作します。JDK 5.0 メタデータ構文に従い、プログラミング タスクを大幅に簡素化します。

EJBGen の詳細については、『WebLogic エンタープライズ JavaBeans (EJB) プログラマーズ ガイド』の「EJBGen リファレンス」を参照してください。

JWS ファイルでステートレス セッション EJB を明示的に実装する場合は、以下のガイドラインに従います。例については「EJB を実装する JWS ファイルの例」を参照してください。該当する部分は太字で示されています。

JWS ファイルでこれらのガイドラインにすべて従うと、jwsc Ant タスクは Web サービスを EJB にコンパイルして、エンタープライズ アプリケーションの内部の EJB JAR ファイルにパッケージ化します。

EJB を実装する JWS ファイルの例

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

package examples.webservices.transactional;

import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Transactional;

import weblogic.ejbgen.Session;

@Session(ejbName="TransactionEJB")

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

@WLHttpTransport(contextPath="transactions", serviceUri="TransactionService",
                 portName="TransactionPort")

/**
 * この JWS ファイルは、1 つのオペレーション sayHello を含む
 * 簡単な EJB 実装の WebLogic Web サービスの基本となる。
 * オペレーションはトランザクションの一部として実行される
 *
 */

public class TransactionImpl implements SessionBean {

  @WebMethod()
  @Transactional(value=true)

  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }

  // 標準の EJB メソッド。通常、メソッドをオーバーライドする必要はない

  public void ejbCreate() {}
  public void ejbActivate() {}
  public void ejbRemove() {}
  public void ejbPassivate() {}
  public void setSessionContext(SessionContext sc) {}
}

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

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

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

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

これらの要件は JAX-RPC で指定されています。要件の詳細と完全なリストについては、JAX-RPC 仕様を参照してください。

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

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

package examples.webservices.complex;

/**
 * integer、String、および String[] 型のプロパティを持つ、
 * BasicStruct という簡単な JavaBean を定義する
 */

public class BasicStruct {

  // プロパティ

  private int intValue;
  private String stringValue;
  private String[] stringArray;

  // ゲッターおよびセッター メソッド

  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;

// 標準の JWS アノテーション インタフェースをインポートする

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

// WebLogic 固有の JWS アノテーション インタフェースをインポートする

import weblogic.jws.WLHttpTransport;

// 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 ファイルのメソッド内にエラー処理の Java コードを記述する場合は、独自のユーザ定義の例外を送出することも、javax.xml.rpc.soap.SOAPFaultException 例外を送出することもできます。SOAPFaultException を送出する場合、WebLogic Server は例外を SOAP エラーにマップして、オペレーションを呼び出すクライアント アプリケーションに送信します。

JWS ファイルが SOAPFaultException 以外の Java 例外を送出した場合、WebLogic Server はその例外をできる限り SOAP エラーにマップしようとします。ただし、クライアント アプリケーションが受け取る例外を制御して、最適な例外情報を送るには、SOAPFaultException または SOAPFaultException を拡張した例外を明示的に送出する必要があります。ユーザ定義の例外の作成と送出の詳細については、JAX-RPC 仕様を参照してください。

次の抜粋では、SOAPFaultException クラスを記述しています。

public class SOAPFaultException extends java.lang.RuntimeException {
    public SOAPFaultException (QName faultcode,
                               String faultstring,
                               String faultactor,
                               javax.xml.soap.Detail detail ) {...}
    public Qname getFaultCode() {...}
    public String getFaultString() {...}
    public String getFaultActor() {...}
    public javax.xml.soap.Detail getDetail() {...}
}

SOAP with Attachments API for Java 1.1 (SAAJ) の javax.xml.soap.SOAPFactory.createDetail() メソッドを使用して、Detail オブジェクトを作成します。このオブジェクトは、エラーに関するアプリケーション固有の詳細情報を提供する DetailEntry オブジェクトのコンテナになります。

SOAPFactory の独自の実装を使用することも、Oracle の実装を使用することもできます。Oracle の実装には、JWS ファイルから静的メソッド weblogic.wsee.util.WLSOAPFactory.createSOAPFactory() を呼び出してアクセスできます。このメソッドは javax.xml.soap.SOAPFactory オブジェクトを返します。実行時には、-Djavax.xml.soap.SOAPFactory フラグを使用して、Oracle の SOAPFactory 実装を指定します。次に例を示します。

-Djavax.xml.soap.SOAPFactory=weblogic.xml.saaj.SOAPFactoryImpl

以下の JWS ファイルは、Web サービスのオペレーションを実装するメソッド内から SOAPFaultException を作成して送出する例を示しています。太字の部分は例外コードを表しています。

package examples.webservices.soap_exceptions;

import javax.xml.namespace.QName;
import javax.xml.soap.Detail;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPFactory;
import javax.xml.rpc.soap.SOAPFaultException;

// @WebService アノテーションをインポートする

import javax.jws.WebService;

// WLHttpTransport をインポートする

import weblogic.jws.WLHttpTransport;

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

@WLHttpTransport(contextPath="exceptions",
                 serviceUri="SoapExceptionsService",
                 portName="SoapExceptionsServicePort")
/**
 * この JWS ファイルは 1 つのオペレーション sayHelloWorld を含む簡単な
 * Java クラス実装の WebLogic Web サービスの基本となる
 *
 */

public class SoapExceptionsImpl {

  public SoapExceptionsImpl() {

  }

  public void tirarSOAPException() {

    Detail detail = null;

    try {

      SOAPFactory soapFactory = SOAPFactory.newInstance();
      detail = soapFactory.createDetail();

    } catch (SOAPException e) {
        // 何らかの処理を行う
    }

    QName faultCode = null;
    String faultString = "the fault string";
    String faultActor = "the fault actor";
    throw new SOAPFaultException(faultCode, faultString, faultActor, detail);
  }
}

この例では、SOAPFactory のデフォルトの実装を使用しています。

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

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

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

JWS アノテーションおよび API によるその他の機能のプログラミング

以下の節では、JWS ファイル内で特定の JWS アノテーションを指定するか、WebLogic Web サービス API を使用してプログラミングできるその他の機能について説明します。

MTOM/XOP を使用したバイナリ データの送信

SOAP Message Transmission Optimization Mechanism/XML-binary Optimized Packaging (MTOM/XOP) では、SOAP メッセージ内の xs:base64Binary 型の XML データの送信を最適化する方法が説明されています。転送プロトコルが HTTP の場合、MIME 添付ファイルを使用して、送信側と受信側の両方に対して同時に SOAP メッセージ内の XML データへの直接アクセスを許可する間にデータを伝達します。このとき、xs:base64Binary データのマーシャリングに MIME アーティファクトが使用されていたことを意識する必要はありません。バイナリ データの最適化プロセスでは、バイナリ データのエンコード、SOAP エンベロープからの削除、圧縮および MIME パッケージへの添付、SOAP エンベロープでのそのパッケージへのリファレンスの追加を行います。

MTOM 仕様では、MTOM が有効化されている場合に、base64binary データ送信時に Web サービスのランタイムで XOP バイナリ最適化を使用することは必須ではありません。むしろ、この仕様では、ランタイムがこれを選択して行うようになっています。これは場合によっては、直接 SOAP メッセージ内に base64binary データを送信するほうが、より効率的であるとランタイムで判断されることがあるためです。一例としては、転送されるデータ量が少なく、単にデータをそのままインライン処理するよりも多くのリソースが、会話および転送のオーバーヘッドにより消費されてしまう場合が挙げられます。しかしながら、JAX-RPC サービスの MTOM 用 WebLogic Web サービスの実装では、MTOM が有効化されている場合には、常に MTOM/XOP が使用されます。

WebLogic JAX-RPC Web サービスでの MTOM/XOP のサポートは、あらかじめパッケージ化された WS-Policy ファイル Mtom.xml を使用して実装されます。WS-Policy ファイルは、WS-Policy 仕様に準拠しています。この仕様では、Web サービスのポリシー (この場合は、バイナリ データ送信のための MTOM/XOP の使用) を記述および通信する汎用モデルおよび XML 構文を提供しています。Web サービス WSDL の types セクションへの、あらかじめパッケージ化された Mtom.xml WS-Policy ファイルのインストールは、次のようになります (参考のためにのみ掲載しています。このファイルを変更することはできません)。

<wsp:Policy wsu:Id="myService_policy">
    <wsp:ExactlyOne>
        <wsp:All>
            <wsoma:OptimizedMimeSerialization 
                   xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization" /> 
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

コンパイルされた JWS ファイルを WebLogic Server にデプロイする際には、MTOM WS-Policy ファイルを参照する次の抜粋コードが、動的 WSDL 内に自動的に含まれます。この抜粋コードでは、Web サービスが MTOM/XOP を使用することを示しています。

<wsdl:binding name="BasicHttpBinding_IMtomTest" 
                      type="i0:IMtomTest">
    <wsp:PolicyReference URI="#myService_policy" /> 
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

JWS ファイルで @Policy メタデータ アノテーションを指定することによって、開発時に Web サービスと Mtom.xml WS-Policy ファイルを関連付けることができます。動的 WSDL に、必須である Mtom.xml ファイルへの参照が確実に含まれるよう、必ず attachToWsdl=true 属性も指定します。下記の例を参照してください。

デプロイメント時に Web サービスと Mtom.xml WS-Policy ファイルを関連付けるには、デプロイメント直前に types セクションにポリシーを追加し、WSDL を修正します。

Administration Console を使用して、実行時にファイルを添付することもできます。詳細については、Administration Console オンライン ヘルプの「WS-Policy ファイルと Web サービスとの関連付け」を参照してください。この節では、JWS アノテーションの使用方法について説明します。

MTOM/XOP を使用してバイナリ データを送信するには、次の手順に従います。

MTOM/XOP 機能自体、および WebLogic JAX-RPC Web サービスでサポートされる仕様のバージョンの詳細については、SOAP Message Transmission Optimization Mechanism 仕様を参照してください。

SOAP 添付ファイルのストリーミング

@weblogic.jws.StreamAttachments JWS アノテーションを使用すると、添付ファイルを含む着信 SOAP メッセージを読み込む際に、メッセージ全体をメモリに読み込むデフォルト動作の代わりに、Web サービスでストリーミング API を使用することを指定できます。この機能を使用すると、非常に大きい SOAP メッセージを読み込む際の Web サービスのパフォーマンスを向上させることができます。

添付ファイルをストリーミングすることを指定した例については、『WebLogic Web サービス リファレンス』の「weblogic.jws.StreamAttachments」を参照してください。

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 ファイルでクラス レベルの @weblogic.jws.Binding アノテーションを使用して、その唯一の属性の値を Binding.Type.SOAP12 に設定します。次に例を示します (該当部分は太字で示してあります)。

package examples.webservices.soap12;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Binding;

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

@WLHttpTransport(contextPath="soap12",
                 serviceUri="SOAP12Service",
                 portName="SOAP12ServicePort")

@Binding(Binding.Type.SOAP12)

/**
 * この JWS ファイルは、1 つのオペレーション sayHello を含む簡単な
 * Java クラス実装の WebLogic Web サービスの基本となる。このクラスでは、
 * バインディングとして SOAP 1.2 を使用する。
 *
 */

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 サービス ランタイムによってすべて自動的に処理されます。

このアノテーションの詳細については、『WebLogic Web サービス リファレンス』の「weblogic.jws.Binding」を参照してください。

トランザクション内で実行するオペレーションの指定

クライアント アプリケーションから WebLogic Web サービス オペレーションを呼び出す場合、オペレーション呼び出しはデフォルトではトランザクションのコンテキストの外で実行されます。トランザクション内でオペレーションを実行するには、JWS ファイルで @weblogic.jws.Transactional アノテーションを指定して、ブール型の value 属性の値を true に設定します。次に例を示します (該当部分は太字で示してあります)。

package examples.webservices.transactional;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Transactional;

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

@WLHttpTransport(contextPath="transactionsPojo",
                 serviceUri="TransactionPojoService",
                 portName="TransactionPojoPort")

/**
 * この JWS ファイルは、1 つのオペレーション sayHello を含む簡単な
 * WebLogic Web サービスの基本となる。
 * オペレーションはトランザクションの一部として実行される
 *
 */

public class TransactionPojoImpl {

  @WebMethod()
  @Transactional(value=true)
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

Web サービスのすべてのオペレーションをトランザクション内で実行する場合は、@Transactional アノテーションをクラス レベルで指定します。一部のオペレーションのみをトランザクション内で実行する場合は、このアノテーションをメソッド レベルで指定します。衝突が発生した場合は、メソッド レベルの値でクラス レベルの値がオーバーライドされます。

その他の属性の詳細については、『WebLogic Web サービス リファレンス』の「weblogic.jws.Transactional」を参照してください。

HttpServletRequest/Response オブジェクトの取得

Web サービスで転送プロトコルとして HTTP を使用する場合は、weblogic.wsee.connection.transport.servlet.HttpTransportUtils API を使用して、JAX-RPC ServletEndpointContext オブジェクトから javax.servlet.http.HttpServletRequest および javax.servlet.http.HttpServletResponse オブジェクトを取得できます。次に例を示します。該当するコードを太字で示し、例の後で解説を加えます。

package examples.webservices.http_transport_utils;

import javax.xml.rpc.server.ServiceLifecycle;
import javax.xml.rpc.server.ServletEndpointContext;
import javax.xml.rpc.ServiceException;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;

import weblogic.wsee.connection.transport.servlet.HttpTransportUtils;

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

@WLHttpTransport(contextPath="servlet", serviceUri="HttpTransportUtils",
                 portName="HttpTransportUtilsPort")

public class HttpTransportUtilsImpl implements ServiceLifecycle {

  private ServletEndpointContext wsctx = null;

  public void init(Object context) throws ServiceException {
    System.out.println("ServletEndpointContext inited...");
    wsctx = (ServletEndpointContext)context;
  }

  public void destroy() {
    System.out.println("ServletEndpointContext destroyed...");
    wsctx = null;
  }

  @WebMethod()
  public String getServletRequestAndResponse() {

    HttpServletRequest request =
       HttpTransportUtils.getHttpServletRequest(wsctx.getMessageContext());
    HttpServletResponse response =
       HttpTransportUtils.getHttpServletResponse(wsctx.getMessageContext());

    System.out.println("HttpTransportUtils API used successfully.");
    return "HttpTransportUtils API used successfully";

  }

}

上の例の中で重要な部分は以下のとおりです。

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

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