WebLogic Web サービス プログラマーズ ガイド
|
 |
 |
|
以下の節では、Web サービスを実装する JWS ファイルのプログラミングについて説明します。
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 アノテーションについて説明します。
@WebService (標準)@SOAPBinding (標準)@WLHttpTransport (WebLogic 固有)@WebMethod (標準)@Oneway (標準)@WebParam (標準)@WebResult (標準)他の JWS アノテーションを使用して、より高度な機能 (Web サービスの信頼性のあるメッセージング、会話、SOAP メッセージ ハンドラなど) をプログラミングする方法については、「高度な JWS プログラミング : 非同期機能の実装」を参照してください。
標準および WebLogic 固有の JWS アノテーションに関するリファレンス ドキュメントについては、「JWS アノテーション リファレンス」を参照してください。
以下の手順では、Web サービスを実装する JWS ファイルをプログラミングする場合の一般的で基本的な手順を説明します。コード サンプルについては、「JWS ファイルの例」を参照してください。
javax.jws または javax.jws.soap パッケージにあります。次に例を示します。import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import weblogic.jws.WLHttpTransport;
「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 メソッドをパブリック オペレーションとして公開することの指定」を参照してください。
「オペレーションのパラメータと WSDL の部分のマッピングのカスタマイズ」を参照してください。
「オペレーションの戻り値と 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 アノテーションの以下の追加の属性を指定することもできます。
endpointInterface - 既存のサービス エンドポイント インタフェース ファイルの完全修飾名。この属性を指定した場合、jwsc Ant タスクはそのインタフェースを生成しません。そのインタフェースは既に作成されていて、CLASSPATH に入っていると想定します。@WebService アノテーションの属性はどれも必須ではありません。各属性のデフォルト値については、「Web Services Metadata for the Java Platform」を参照してください。
ここでは、Web サービスを SOAP 1.1 メッセージ プロトコルで使用できるようにします。そのためには、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 アノテーションを使用しない場合でも、これらはデフォルトのフォーマットとなります。
(style=SOAPBinding.Style.DOCUMENT 属性と一緒に) parameterStyle 属性を使用して、Web サービス オペレーションのパラメータが、SOAP メッセージ本文全体を表しているか、または、オペレーションと同じ名前の最上位要素内にラップされている要素であるかを指定します。
次の表では、@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」を参照してください。
標準の @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 モードは、Holder 型の JAX-RPC 定義に準拠するパラメータ型に対してのみ指定できます。OUT および INOUT モードは、RPC 形式のオペレーション、またはヘッダにマップされるパラメータでのみサポートされます。header - true に設定した場合、パラメータの値はデフォルトの本文からではなく SOAP ヘッダから取得されることを指定する、ブール型の属性。@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 を参照してください。
JWS ファイルを実装する場合、通常は、Web サービスの基底の実装について知る必要はありません。代わりに、後で JWS ファイルをコンパイルする jwsc Ant タスクが、最適な実装を判断します。jwsc Ant タスクは、Web アプリケーションにパッケージ化される標準の Java クラスとして Web サービスを実装します。または、JWS ファイルで特定の機能 (会話や信頼性のあるメッセージングなど) を実装している場合は、Java クラスの前にステートレス セッション EJB「ラッパー」を追加します。後者の場合、Web サービスのビジネス ロジックは Java クラスのままですが、特定の機能の実装に必要な追加のフレームワークは EJB ラッパーが処理します。jwsc Ant タスクはこのような Web サービスを EJB JAR ファイルにパッケージ化します。
ただし、場合によっては、JWS ファイルにステートレス セッション EJB を明示的に実装する必要があります。これは、Java クラスの前に EJB ラッパーを置くよりも、その Web サービス自体を EJB で実装する必要があるためです。JWS ファイルで以下の JWS アノテーションを使用する場合は、EJB を明示的に実装する必要があります。
@weblogic.jws.Transactional@weblogic.jws.security.SecurityRoles (WebLogic Server のバージョン 9.1 以降では非推奨)@weblogic.jws.security.SecurityIdentity (WebLogic Server のバージョン 9.1 以降では非推奨)EJB を明示的に実装していない JWS ファイルで上記のアノテーションのいずれかを使用した場合、jwsc Ant タスクはエラーにより失敗します。
一般的なガイドラインは、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")
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 ファイルにパッケージ化します。
以下の例では、@Transactional アノテーションを含む簡単な JWS ファイルを示します。そのため、JWS ファイルではステートレス セッション EJB を明示的に実装する必要もあります。関連するコードは太字で示されています。
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 コードを記述するときは、以下の基本的な要件に従います。
getXXX() メソッドと setXXX() メソッドの両方を定義する。これらの要件は 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 の実装には、静的メソッド weblogic.wsee.util.createSOAPFactory() を呼び出してアクセスできます。このメソッドは javax.xml.soap.SOAPFactory オブジェクトを返します。
以下の 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);
}
警告 : SOAPFaultException を使用せずに独自の例外を作成および送出し、例外クラスの複数のプロパティのデータ型が同じである場合、JAX-RPC 仕様では必要とされていませんが、これらのプロパティのセッター メソッドも作成する必要があります。これは、WebLogic Web サービスが SOAP メッセージで例外を受け取り、XML を Java 例外クラスに変換するときに、対応するセッター メソッドがなければ、どの XML 要素をどのクラス プロパティにマップするのかを知る方法がないからです。
JWS ファイル内から別の Web サービス (WebLogic Server にデプロイされている Web サービス、または .NET などの他のアプリケーション サーバにデプロイされている Web サービス) を呼び出すことができます。その手順は、「スタンドアロンの JAX-RPC Java クライアントからの Web サービスの呼び出し」で説明されている手順 (clientgen Ant タスクを実行してクライアント スタブを生成し、クライアント アプリケーションで標準の JAX-RPC API を使用する) と似ています。ただし、この場合は、これらの API を、スタンドアロンの Java クライアント アプリケーションではなく、他の Web サービスを呼び出す Web サービスを実装した JWS ファイルで使用します。
詳細な手順については、「別の Web サービスからの Web サービスの呼び出し」を参照してください。
以下のリストでは、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 サービスの関連するポート名を指定します。
|
|
|