![]() ![]() ![]() ![]() |
以下の節では、Web サービスを実装する JWS ファイルのプログラミングについて説明します。
警告 : | JAX-RPC 1.1 および JAX-WS 2.0 は双方ともこのリリースの WebLogic Server でサポートされていますが、このマニュアルでは、ほぼ JAX-RPC 形式の Web サービスの作成方法のみに絞って説明しています。なぜならこのリリースでは、すべての WS-* 仕様 (WS-Security、WS-ReliableMessaging など) および付加価値の高い WebLogic の機能 (非同期の要求と応答、コールバックなど) が、JAX-RPC 形式の Web サービスでのみ有効であるからです。したがって、別段の記述がなければ、すべての説明および例は、JAX-RPC Web サービスについてのものであると見なされます。 |
注意 : | JAX-WS Web サービス作成の詳細については、「JAX-WS 2.0 Web サービスの実装」を参照してください。 |
WebLogic Web サービスをプログラミングする方法の 1 つは、標準の JSR-921 の EJB または Java クラスを最初からコーディングして、関連するアーティファクト (デプロイメント記述子ファイル、WSDL ファイル、ユーザ定義のデータ型のデータ バインディング アーティファクトなど) を手動で生成することです。そのプロセスは煩雑で単調になる可能性があります。JDK 5.0 の新機能であるメタデータ アノテーション機能とプログラミング モデルを利用することをお勧めします。このプログラミング モデルでは、アノテーション付きの Java ファイルを作成し、Ant タスクを使用してそのファイルを Java ソース コードにコンパイルし、関連するアーティファクトをすべて生成します。
アノテーション付きの Java Web サービス (JWS) ファイルは、Web サービスの中核部分です。このファイルには Web サービスの動作を決定する Java コードが含まれています。JWS ファイルは、JDK 5.0 メタデータ アノテーションを使用して Web サービスの形式や特性を指定した、通常の Java クラス ファイルです。JWS ファイルで使用できる JWS アノテーションには、Web Services Metadata for the Java Platform 仕様 (JSR-181) で定義された標準のアノテーションと、WebLogic 固有のアノテーションがあります。
このトピックは、「Java から開始する WebLogic Web サービスの反復的な開発 : 主な手順」および「WSDL ファイルから開始する WebLogic Web サービスの反復的な開発 : 主な手順」で説明されている、Web サービスを作成するための反復的な開発手順の一部です。JWS ファイルを作成してあり、そこに JWS アノテーションを追加する予定であることを前提としています。
JWS ファイルをプログラミングする場合は、JSR-181 仕様 (Web Services Metadata for the Java Platform) で指定された一連の要件に従う必要があります。特に、Web サービスを実装する Java クラスは、次の要件に従う必要があります。
finalize()
メソッドは定義できない。@WebService
JWS アノテーションを指定して、その JWS ファイルが Web サービスを実装することを指定する必要がある。@WebService.endpointInterface
アノテーションを使用して、サービス エンドポイント インタフェースを参照できる。この場合は、サービス エンドポイント インタフェースが存在することを前提としています。JWS ファイルでは @WebService.endpointInterface
および @WebService.serviceName
以外の JWS アノテーションを指定することはできません。java.lang.Object
から継承されたもの以外のすべてのパブリック メソッドが、Web サービス オペレーションとして公開される。この動作は、@WebMethod
アノテーションを使用して、公開するパブリック メソッドを明示的に指定することによって、オーバーライドできます。@WebMethod
アノテーションが存在する場合は、それが適用されるメソッドのみが公開されます。
以下の節では、JWS ファイルで標準 (JSR-181) のアノテーションと WebLogic 固有のアノテーションを使用して、基本的な Web サービスの機能をプログラミングする方法について説明します。アノテーションは、JWS ファイル内のさまざまなレベル、さまざまな対象で使用されます。一部のアノテーションはクラス レベルで使用され、そのアノテーションが JWS ファイル全体に適用されることを示します。それ以外のアノテーションには、メソッド レベルで使用するものや、パラメータ レベルで使用するものがあります。ここでは、以下の基本的な JWS アノテーションについて説明します。
他の JWS アノテーションを使用して、より高度な機能 (Web サービスの信頼性のあるメッセージング、会話、SOAP メッセージ ハンドラなど) をプログラミングする方法については、『WebLogic Web サービス プログラマーズ ガイド (応用編)』を参照してください。
WebLogic 固有の JWS アノテーションに関するリファレンス ドキュメントについては、「JWS アノテーション リファレンス」を参照してください。
以下の手順では、Web サービスを実装する JWS ファイルをプログラミングする場合の一般的で基本的な手順を説明します。コード サンプルについては、「JWS ファイルの例」を参照してください。
javax.jws
または javax.jws.soap
パッケージにあります。次に例を示します。import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
weblogic.jws
パッケージにあります。次に例を示します。 import weblogic.jws.WLHttpTransport;
@WebService
JWS アノテーションをクラス レベルで追加して、Java クラスが Web サービスを公開することを指定します。
「JWS ファイルが Web サービスを実装することの指定」を参照してください。
@SOAPBinding
JWS アノテーションをクラス レベルで追加して、Web サービスと SOAP メッセージ プロトコルの間のマッピングを指定します。特に、このアノテーションを使用して、Web サービスがドキュメントリテラルか、RPC エンコードかなどを指定します。
この JWS アノテーションは必須ではありませんが、JWS ファイルで明示的に指定し、クライアント アプリケーションが Web サービスの呼び出しに使用する SOAP バインディングのタイプを明確にすることをお勧めします。
「Web サービスと SOAP メッセージ プロトコルのマッピングの指定」を参照してください。
@WLHttpTransport
JWS アノテーションをクラス レベルで追加して、Web サービスを呼び出す URL で使用されるコンテキスト パスとサービス URI を指定します。
この JWS アノテーションは必須ではありませんが、JWS ファイルで明示的に指定し、クライアント アプリケーションが Web サービスの呼び出しに使用する URL を明確にすることをお勧めします。
「Web サービスのコンテキスト パスとサービス URI の指定」を参照してください。
@WebMethod
アノテーションを追加します。必要に応じて、標準の @Oneway
アノテーションを使用し、そのオペレーションが入力パラメータだけを取り、値を返さないことを指定します。
「JWS メソッドをパブリック オペレーションとして公開することの指定」を参照してください。
@WebParam
アノテーションを追加して、公開されるオペレーションの入力パラメータの名前をカスタマイズします。
「オペレーションのパラメータと WSDL の部分のマッピングのカスタマイズ」を参照してください。
@WebResult
アノテーションを追加して、公開されるオペレーションの戻り値の名前と動作をカスタマイズします。
「オペレーションの戻り値と WSDL の部分のマッピングのカスタマイズ」を参照してください。
以下のサンプル 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 + "'";
}
}
次のコードの抜粋のように、標準の @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 仕様を参照してください。
ここでは、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 つの属性の指定できる値とデフォルト値を示します。
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 アノテーションに関するリファレンス ドキュメントについては、「JWS アノテーション リファレンス」を参照してください。
標準の @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」を参照してください。
JWS ファイル内のどのパブリック メソッドにも @WebMethod
アノテーションを付けていない場合、デフォルトではすべてのパブリック メソッドが Web サービス オペレーションとしてエクスポーズされます。
標準の @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 仕様を参照してください。
標準の @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 仕様を参照してください。
クライアント アプリケーションが、JWS ファイルで実装された WebLogic Web サービスを呼び出すと、WebLogic Server は、Web サービスが、サービスに関する実行時情報のアクセス、および場合によっては変更に使用できるコンテキストを自動的に作成します。この情報の多くは、現在の会話が終了したか、会話のプロパティの現在の値、実行時の会話のプロパティの変更など、会話に関連しています。会話とその実装方法については、「会話形式の Web サービスの作成」を参照してください。コンテキストを介してアクセス可能な情報には、Web サービスの呼び出しに使用されたプロトコル (HTTP/S または JMS)、SOAP メッセージ要求内にあった SOAP ヘッダなど、より一般的なものもあります。
以下の節で説明するように、JWS ファイルでアノテーションと WebLogic Web サービス API を使用して、実行時のコンテキスト情報にアクセスできます。
以下の例では、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 ファイルで以下のガイドラインに従います。
@weblogic.jws.Context
JWS アノテーションをインポートする。import weblogic.jws.Context;
weblogic.wsee.jws.JwsContext
API と、使用する他の関連 API (例では weblogic.wsee.jws.Protocol
API も使用) をインポートする。import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.Protocol;
コンテキスト関連の API に関するリファレンス ドキュメントについては、weblogic.wsee.* の Javadoc を参照してください。
weblogic.wsee.jws.JwsContext
のプライベート変数に、フィールド レベルの @Context
JWS アノテーションを指定する。@Context
private JwsContext ctx;
Web サービスが最初に呼び出されるときに、WebLogic Server はアノテーションの付いた変数 (この場合は ctx
) に JwsContext
の実行時実装を自動的に割り当てます。そのため、コード内で明示的に初期化しないでも、この変数を後で使用できます。
JwsContext
クラスのメソッドを使用して、Web サービスに関する実行時情報を取得したり、場合によっては変更したりする。以下の例では、Web サービスの呼び出しに使用されたプロトコルを取得する方法を示します。Protocol protocol = ctx.getProtocol();
使用できるメソッドの詳細なリストについては、「JwsContext のメソッド」を参照してください。
次の表では、Web サービスに関する実行時情報にアクセスするために JWS ファイルで使用できる JwsContext
のメソッドについて簡単に説明します。JwsContext
や、他のコンテキスト関連の API (Protocol
および ServiceHandle
) に関する詳細なリファレンス情報については、weblogic.wsee.* の Javadoc を参照してください。
jwsc
Ant タスクでは、JWS ファイルを処理するときは常に、Web サービスの基底の実装としてプレーン Java オブジェクトが選択されます。
しかし、Web サービスの基底の実装をステートレス セッション EJB にして、EJB が提供するすべての機能 (インスタンス プール、トランザクション、セキュリティ、コンテナ管理による永続性、コンテナ管理による関係、データ キャッシュなど) を活用したい場合もあります。Web サービスの実装を EJB にする場合は、次の節のプログラミング ガイドラインに従ってください。
一般的なガイドラインは、JWS ファイルで常に EJBGen アノテーションを使用して、EJB を実装する場合に必要な EJB リモートおよびホーム インタフェース クラスおよびデプロイメント記述子ファイルを、手動で作成するのではなく、自動的に生成することです。EJBGen アノテーションは JWS アノテーションと同じように動作します。JDK 5.0 メタデータ構文に従い、プログラミング タスクを大幅に簡素化します。
EJBGen の詳細については、『WebLogic エンタープライズ JavaBeans (EJB) プログラマーズ ガイド』の「EJBGen リファレンス」を参照してください。
JWS ファイルでステートレス セッション EJB を明示的に実装する場合は、以下のガイドラインに従います。例については「EJB を実装する JWS ファイルの例」を参照してください。該当する部分は太字で示されています。
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
weblogic.ejbgen
パッケージにあります。少なくとも、@Session
アノテーションをインポートする必要があります。EJB の形式や動作を指定するために JWS ファイルで追加の EJBGen アノテーションを使用する場合は、EJBGen のリファレンス ガイドでインポートすべきアノテーションの名前を確認してください。import weblogic.ejbgen.Session;
@Session
アノテーションをクラス レベルで使用して、EJB の名前を指定する。@Session(ejbName="TransactionEJB")
JWS ファイルで使用する場合、必須の EJBGen アノテーションは @Session
のみです。必要な場合は、他の EJBGen アノテーションを使用して、EJB の追加機能を指定します。
SessionBean
を実装する。public class TransactionImpl implements SessionBean {...
ejbCreate()
、ejbActivate()
なども含める必要がある。ただし、通常は、EJB のデフォルトの動作を変更するのでない限り、これらのメソッドにコードを追加する必要はありません。public void ejbCreate() {}
public void ejbActivate() {}
public void ejbRemove() {}
public void ejbPassivate() {}
public void setSessionContext(SessionContext sc) {}
JWS ファイルでこれらのガイドラインにすべて従うと、jwsc
Ant タスクは Web サービスを EJB にコンパイルして、エンタープライズ アプリケーションの内部の EJB JAR ファイルにパッケージ化します。
以下の例では、ステートレス セッション 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) {}
}
Web サービス オペレーションとして公開される JWS ファイルのメソッドでは、パラメータや戻り値として必ずしも組み込みのデータ型 (String や integer など) を取る必要はなく、独自に作成する Java データ型を使用することができます。ユーザ定義のデータ型の例としては、String
の銘柄記号と integer の売買株式数という 2 つのフィールドを持つ TradeResult
が挙げられます。
JWS ファイルで、1 つまたは複数のメソッドのパラメータまたは戻り値としてユーザ定義のデータ型を使用する場合は、データ型の Java コードを独自に作成して、JWS ファイルにそのクラスをインポートし、適切に使用する必要があります。jwsc
Ant タスクは、Java ユーザ定義データ型の対応する XML スキーマ表現、JAX-RPC の型マッピング ファイルなど、必要なデータ バインディング アーティファクトをすべて作成します。
ユーザ定義のデータ型の Java コードを記述するときは、以下の基本的な要件に従います。
これらの要件は JAX-RPC 1.1 で指定されています。詳細情報と要件の完全なリストについては、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 1.1 仕様を参照してください。
次の抜粋では、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
の独自の実装を使用することも、BEA の実装を使用することもできます。BEA の実装には、JWS ファイルから静的メソッド weblogic.wsee.util.WLSOAPFactory.createSOAPFactory()
を呼び出してアクセスできます。このメソッドは javax.xml.soap.SOAPFactory
オブジェクトを返します。実行時には、-Djavax.xml.soap.SOAPFactory
フラグを使用して、BEA の 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 サービスの基本となる
*
* @author Copyright (c) 2005 by BEA Systems.All rights reserved.
*/
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
のデフォルトの実装を使用しています。
警告 : | SOAPFaultException を使用せずに独自の例外を作成および送出し、例外クラスの複数のプロパティのデータ型が同じである場合、JAX-RPC 仕様では必要とされていませんが、これらのプロパティのセッター メソッドも作成する必要があります。これは、WebLogic Web サービスが SOAP メッセージで例外を受け取り、XML を Java 例外クラスに変換するときに、対応するセッター メソッドがなければ、どの XML 要素をどのクラス プロパティにマップするのかを知る方法がないからです。 |
JWS ファイル内から別の Web サービス (WebLogic Server にデプロイされている Web サービス、または .NET などの他のアプリケーション サーバにデプロイされている Web サービス) を呼び出すことができます。その手順は、「スタンドアロンの JAX-RPC Java クライアントからの Web サービスの呼び出し」で説明した手順と似ています。ただしこの場合は、clientgen
Ant タスクを実行してクライアント スタブを生成するのではなく、呼び出し側の Web サービスを構築する jwsc
Ant タスクに子要素 <clientgen>
を含めてクライアント スタブを生成します。その後は、スタンドアロン クライアント アプリケーションの場合と同じように、JWS ファイル内で標準の JAX-RPC API を使用します。
詳細な手順については、「別の Web サービスからの Web サービスの呼び出し」を参照してください。
以下の節では、JWS ファイル内で特定の JWS アノテーションを指定するか、WebLogic Web サービス API を使用してプログラミングできるその他の機能について説明します。
MTOM/XOP では、SOAP メッセージ内の xs:base64Binary
型の XML データの送信を最適化する方法が説明されています。転送プロトコルが HTTP の場合、MIME 添付ファイルを使用して、送信側と受信側の両方に対して同時に SOAP メッセージ内の XML データへの直接アクセスを許可する間にデータを伝達します。このとき、xs:base64Binary
データのマーシャリングに MIME アーティファクトが使用されていたことを意識する必要はありません。
MTOM/XOP のサポートは、JWS アノテーションの使用を通じて、JAX-WS 2.0 では標準となっています。詳細については、「JAX-WS section in the Sun Developer Network」を参照してください。このリリースの WebLogic Server では、JAX-RPC 形式の Web サービスでも MTOM/XOP がサポートされています。
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 を使用して、実行時にファイルを添付することもできます。詳細については、「WS-Policy ファイルと Web サービスとの関連付け」を参照してください。この節では、JWS アノテーションの使用方法について説明します。
警告 : | このリリースの WebLogic Server では、MTOM/XOP 使用時にサポートされる Java データ型は byte[] のみです。その他のバイナリ データ型 (image など) はサポートされていません。 |
警告 : | また、このリリースの WebLogic Server では、メッセージレベルのセキュリティとの MTOM の使用はサポートしていません。実際面では、これはつまり、同一の JAX-RPC Web サービス内で、Encrypt.xml 、Sign.xml 、Wssc-dk.xml 、または Wssc-sct.xml WS-Policy ファイルと一緒に Mtom.xml WS-Policy ファイルを指定できないということです。 |
MTOM/XOP を使用してバイナリ データを送信するには、次の手順に従います。
@weblogic.jws.Policy
アノテーションを使用し、あらかじめパッケージ化された Mtom.xml
ファイルを、Web サービスに適用することを指定します。package examples.webservices.mtom;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;import weblogic.jws.Policy;
@WebService(name="MtomPortType",
serviceName="MtomService",
targetNamespace="http://example.org")
@WLHttpTransport(contextPath="mtom",
serviceUri="MtomService",
portName="MtomServicePort")
@Policy(uri="policy:Mtom.xml", attachToWsdl=true)
public class MtomImpl {
@WebMethod
public String echoBinaryAsString(byte[] bytes) {
return new String(bytes);
}
byte[]
データ型を戻り値または入力パラメータとして使用します。一例としては、上述の echoBinaryAsString
オペレーションの実装を参照してください。このオペレーションでは、単純に byte
の配列を入力として取り、それを String
として返しています。clientgen
Ant タスクがクライアントサイド アーティファクトを生成する WSDL で、MTOM/XOP のサポートが指定されている場合に、有効になります。クライアント アプリケーション自体では、関連データ型として byte[]
を使用し、単に通常のようにオペレーションを呼び出します。
MTOM/XOP 機能自体、および WebLogic JAX-RPC Web サービスでサポートされる仕様のバージョンの詳細については、SOAP Message Transmission Optimization Mechanism 仕様を参照してください。
@weblogic.jws.StreamAttachments
JWS アノテーションを使用すると、添付ファイルを含む着信 SOAP メッセージを読み込む際に、メッセージ全体をメモリに読み込むデフォルト動作の代わりに、Web サービスでストリーミング API を使用することを指定できます。この機能を使用すると、非常に大きい SOAP メッセージを読み込む際の Web サービスのパフォーマンスを向上させることができます。
添付ファイルをストリーミングすることを指定した例については、weblogic.jws.StreamAttachments を参照してください。
WebLogic Web サービスでは、Web サービスとそのクライアントの間でデータや呼び出しを転送する際に、メッセージ フォーマットとしてデフォルトでバージョン 1.1 の SOAP (Simple Object Access Protocol) が使用されます。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 サービス オペレーションを呼び出す場合、オペレーション呼び出しはデフォルトではトランザクションのコンテキストの外で実行されます。トランザクション内でオペレーションを実行するには、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.jws.Transactional」を参照してください。
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";
}
}
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;
HttpTransportUtils
クラスのインポート。import weblogic.wsee.connection.transport.servlet.HttpTransportUtils;
ServiceLifecycle
を明示的に実装する必要がある。public class HttpTransportUtilsImpl implements ServiceLifecycle
ServletEndpointContext
の変数の作成。private ServletEndpointContext wsctx = null;
ServiceLifecycle
を実装するため、init
および destroy
ライフサイクル メソッドも実装する必要がある。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;
}
ServletEndpointContext
オブジェクトを使用して HttpServletRequest
および HttpServletResponse
オブジェクトを取得する。HttpServletRequest request =
HttpTransportUtils.getHttpServletRequest(wsctx.getMessageContext());
HttpServletResponse response =
HttpTransportUtils.getHttpServletResponse(wsctx.getMessageContext());
以下のリストでは、JWS ファイルをプログラミングする場合のベスト プラクティスを示します。
@WebParam
JWS アノテーションを使用して、特定の Web サービスのすべてのオペレーションのすべての入力パラメータにユニークな名前を付けるようにする。
document-literal-bare の Web サービスの性質上、@WebParam
アノテーションを使用して入力パラメータの名前を明示的に指定しない場合、WebLogic Server が入力パラメータの名前を作成するため、Web サービス内でパラメータの名前が重複するおそれがあります。
return
に常に依存するのではなく、@WebResult
JWS アノテーションを使用して、オペレーションの戻り値の名前を明示的に設定する。JWS ファイルで @WebResult
アノテーションを使用しない場合、return が戻り値のデフォルト名になります。@WLHttpTransport
アノテーションの portName
属性を常に指定することを推奨。この属性を指定しない場合、jwsc
Ant タスクは WSDL ファイルの生成時にポート名を生成しますが、この名前はユーザにとってわかりにくい場合があります。その結果、Web サービスを呼び出すためにクライアント アプリケーションで使用する getXXX()
メソッドの名前が適切に指定されなくなります。クライアント アプリケーションが Web サービスを呼び出すときにわかりやすいメソッドを使用できるようにするには、portName
属性を使用して、Web サービスの関連するポート名を指定します。
![]() ![]() ![]() |