WebLogic Web サービス プログラマーズ ガイド
|
 |
 |
|
この章では、WebLogic Web サービスを実装する方法について説明します。
WebLogic Web サービスの実装とは、Web サービスを構成するバックエンド コンポーネントの Java コードを記述およびコンパイルし、必要に応じて SOAP メッセージ ハンドラと非組み込みデータ型の Java コードを作成することです。バックエンド コンポーネントには、ステートレス セッション EJB と Java クラスがあります。Web サービスは、これらのコンポーネントをさまざまに組み合わせて実装することができます。
単一の WebLogic Web サービスは、1 つまたは複数のオペレーションで構成されています。各オペレーションは、異なるバックエンド コンポーネントと SOAP メッセージ ハンドラのメソッドを使用して実装することができます。たとえば、オペレーションは、ステートレス セッション EJB の単一メソッドを使用して実装されている場合、または SOAP メッセージ ハンドラとステートレス セッション EJB を組み合わせて実装されている場合があります。
既存の WSDL ファイルから WebLogic Web サービスを実装する場合は、WebLogic Server に付属の wsdl2Service Ant タスクを利用して、目的の Web サービスを表現する Java インタフェース、また必要に応じて空の実装 Java クラス ファイルを自動的に生成します。次に、Java 実装クラスのビジネス ロジックのコードを記述して、Web サービスに必要な動作を実装します。
ここでは、「WebLogic Web サービスの設計」で説明した設計の問題を読み理解して Web サービスを設計していること、コード化する必要があるコンポーネントのタイプを基本的に理解していることを前提としています。
注意 :Web サービス オペレーションは、ステートレス セッション EJB または Java クラスで実装し、JMS コンシューマまたはプロデューサでは実装しないようにしてください。このマニュアルでは、Web サービスを EJB または Java クラスで実装することを前提としています。JMS 固有の情報については、「JMS で実装された WebLogic Web サービスの作成」を参照してください。
WebLogic Server の WL_HOME/samples/server/examples/src/examples/webservices ディレクトリには、WebLogic Web サービスの実装例があります。WL_HOME は、WebLogic Platform のメイン ディレクトリです。上記の例の構築と実行についての詳細な説明は、次の Web ページを参照してください。
WL_HOME/samples/server/examples/src/examples/webservices/package-summary.html
以下は、WebLogic Web サービスを実装する高度な手順です。このマニュアルの後半で、この手順について詳細に説明します。実装する Web サービスのタイプにより、必須の手順もあれば省略可能なものもあります。
「コンポーネントの Java コードの記述」を参照してください。
「SOAP メッセージをインターセプトする SOAP メッセージ ハンドラの作成」を参照してください。
「非組み込みデータ型を実装する」を参照してください。
WebLogic Web サービスを実装するときには、以下のいずれかのバックエンド コンポーネントの Java コードを記述します。
Java コードの記述については、「ステートレス セッション EJB を使用して Web サービスを実装する」を参照してください。例については、「EJB の Java インタフェースと実装クラス」を参照してください。
Java コードの記述については、「Java クラスを記述して Web サービスを実装する」を参照してください。例については、WL_HOME/samples/server/examples/src/examples/webservices/basic/javaclass ディレクトリを参照してください。WL_HOME は、WebLogic Platform のメイン ディレクトリです。
Web サービス オペレーションで非組み込みデータ型をパラメータまたは戻り値として使用する場合は、「非組み込みデータ型を実装する」を参照してください。
デフォルトの RPC 指向ではなくドキュメント指向のオペレーションを使用する Web サービスを実装する場合は、「ドキュメント指向の Web サービスを実装する」を参照してください。
既存の WSDL ファイルに基づいて WebLogic Web サービスを実装し、かつその Web サービスを Java クラスを使用して実装する場合には、WebLogic Server に付属の wsdl2Service Ant タスクを使用することで、土台として使用する Web サービス インタフェースおよびオプションの実装クラスを生成できます。この Ant タスクを使用する方法の詳細については、「WSDL ファイルに基づき部分的な実装を生成する」を参照してください。
SOAP 添付ファイルを使用する方法については、「SOAP 添付ファイルを使用する」を参照してください。
Web サービス実装からの例外の送出については、「SOAP 障害例外を送出する」を参照してください。
Web サービスのオペレーションで複数の値が返されるようにするには、「複数の戻り値を実装する」を参照してください。
Web サービスのステートレス セッション EJB の Java コードを記述することはスタンドアロン EJB を記述することと同じですが、次の例外があります。
web-services.xml デプロイメント記述子で、Web サービス オペレーションが一方向となるように指定することができる。それにより、Web サービスを呼び出すクライアント アプリケーションは応答を求めません。このタイプのオペレーションを実装する EJB メソッドの Java コードを記述するときは、このメソッドから void が返されるように指定する必要があります。web-services.xml ファイルで Web サービス オペレーションが一方向となるように指定する方法の詳細は、「operation」を参照してください。
「非組み込みデータ型を実装する」を参照してください。
ステートレス セッション EJB の記述例については、「EJB の Java インタフェースと実装クラス」を参照してください。詳細については、『WebLogic エンタープライズ JavaBeans プログラマーズ ガイド』を参照してください。
以下の規則に従い、Java クラスを使用して Web サービス オペレーションを実装することができます。
必要ではありませんが、Java クラスは JAX-RPC javax.xml.rpc.server.ServiceLifecycle インタフェースを拡張できます。このインタフェースは、Web サービス エンドポイントのライフ サイクルを定義します。しかし、WebLogic Server のこのバージョンは WebLogic Web サービスのバックエンド コンポーネントとしてサーブレットをサポートしないので、javax.xml.rpc.server.ServletEndpointContext インタフェースの実装は提供しません。このため、使用する Java クラスが ServiceLifecycle インタフェースの拡張である場合、その init() メソッドは ServletEndpointContext のインスタンスではなく null として渡されます。
Java クラスを使用して WebLogic Web サービス オペレーションを実装する例は、WL_HOME/samples/server/examples/src/examples/webservices/basic/javaclass ディレクトリにあります。WL_HOME は、WebLogic Server のメインのインストール ディレクトリです。
ステートレス セッション EJB と Java クラスは、パラメータや戻り値として必ずしも組み込みデータ型を受け取るとは限りません。自作の Java データ型を使用する場合もあります。非組み込みデータ型の例としては、TradeResult があり、これには 2 つのフィールドがあります。String 株式シンボルと売買される株数を表す整数です。組み込みデータ型のリストについては、「サポートされる組み込みデータ型」を参照してください。
バックエンド コンポーネントが、パラメータまたは戻り値として非組み込みデータ型を使用する場合は、そのデータ型の Java コードを作成して、次にそのデータを XML と Java 間で変換するシリアライゼーション クラスを生成または作成する必要があります。それには、以下の 2 通りの方法があります。
servicegen または autotype Ant タスクを使用して、EJB を参照し、シリアライゼーション クラスを自動的に生成させる方法。これらの Ant タスクは、データが XML フォーマットで表現されるように、対応する XML スキーマも作成し、該当するデータ型マッピング情報を使用して、web-services.xml デプロイメント記述子ファイルを更新します。「servicegen Ant タスクを指定するビルド ファイルの作成」および「autotype Ant タスクを実行する」で説明する Web サービスのアセンブル作業の一環としてこれらの Ant タスクを実行します。警告 :autotype と servicegen Ant タスクによって生成されたシリアライゼーション クラスと Java および XML 表現はラウンドトリップできません。詳細については、「生成されたデータ型コンポーネントの非ラウンドトリップ」を参照してください。
Java データ型の XML 表現およびシリアライゼーション クラスを手動で作成する場合は、変換コードもすべて自分で記述するので、Java クラスを自在にコード化することができます。
servicegen または autotype Ant タスクを使用してデータ型のコンポーネントを自動的に生成させる場合は、そのデータ型の Java クラスを記述するときに、以下の要件に従います。
getXXX() メソッドと setXXX() メソッドの両方を定義する。servicegen および autotype Ant タスクでは、ほとんどの一般的な XML および Java データ型のデータ型コンポーネントを生成できます。サポートされている非組み込みデータ型のリストは、「servicegen および autotype Ant タスクでサポートされる非組み込みデータ型」を参照してください。
WebLogic Web サービスは、ドキュメント指向 (SOAP メッセージがドキュメントを格納) か、または RPC 指向 (SOAP メッセージがパラメータと戻り値を格納) のいずれかです。デフォルトでは、WebLogic Web サービスは RPC 指向です。servicegen Ant タスクを使用して Web サービスをアセンブルする場合、ドキュメント指向として指定します。
この章の手順では、RPC 指向の Web サービスを作成することを前提としています。ドキュメント指向の Web サービスを作成する場合は、バックエンド コンポーネントを実装するときに次のガイドラインに従ってください。
この章では、バックエンド コンポーネントを記述して Web サービスを実装することを前提としています。ただし、既存の WSDL から実装を作成しなければならない場合もあります。たとえば、社内アーキテクチャ グループが共通サービス記述 (WSDL ファイル) を定義し、それらを異なる部門で実装する必要があるとします。この場合、wsdl2Service Ant タスクを使用して部分的な実装を生成できます。
wsdl2Service Ant タスクは既存の WSDL ファイルを入力として、次のものを生成します。
生成される Java インタフェース ファイルには、Java クラスのみで実装される WebLogic Web サービスのテンプレートが格納されます。このテンプレートには、WSDL ファイルのオペレーションに対応する完全なメソッド シグネチャが含まれています。「Java クラスを記述して Web サービスを実装する」のガイドラインに従って、希望どおりにメソッドが機能するように、このインタフェースを実装する Java クラスを記述します。実装クラスのスケルトンを生成するには、generateImpl="True" 属性を指定し、このクラスにビジネス ロジック Java コードを追加して、実装を完了します。
wsdl2Service Ant タスクは、(<service> 要素で指定された) WSDL ファイルの 1 つの Web サービスのみに対応する Java インタフェースを生成します。 serviceName 属性を使用すると、特定のサービスを指定できます。この属性を指定しない場合、wsdl2Service Ant タスクでは WSDL ファイルの最初の <service> 要素の Java インタフェースが生成されます。
警告 :wsdl2Service Ant タスクを使用して Web サービスの web-services.xml ファイルを生成するときは、作成された Java インタフェースを実装する Java クラスに対して、次の命名規約が使用されます。
packageName および serviceName は、wsdl2Service Ant タスクの同名の属性の値です。 Ant タスクは、web-services.xml ファイルの <java-class> 要素の class-name 属性に、この情報を書き込みます。
Java 実装クラスに別の名前を付ける場合は、その名前に合わせて、生成された web-services.xml ファイルを手動で更新する必要があります。
wsdl2Service Ant タスクを実行するには、次の手順に従います。
Windows NT では、ドメイン ディレクトリにある setEnv.cmd コマンドを実行します。WebLogic Server ドメインのデフォルトの位置は、BEA_HOME\user_projects\domains\domainName です。BEA_HOME は BEA Products の最上位のインストール ディレクトリで、domainName はドメインの名前です。
UNIX では、ドメイン ディレクトリにある setEnv.sh コマンドを実行します。WebLogic Server ドメインのデフォルトの位置は、BEA_HOME/user_projects/domains/domainName です。BEA_HOME は BEA Products の最上位のインストール ディレクトリで、domainName はドメインの名前です。
wsdl2Service Ant タスクの呼び出しの入った build.xml というファイルを作成します。詳細については、「wsdl2Service Ant タスクのサンプル build.xml ファイル」を参照してください。 prompt> ant
myService/implementation ディレクトリで生成されたインタフェースの Java クラス実装を作成します。詳細については、「Java クラスを記述して Web サービスを作成する」を参照してください。wsdl2Service Ant タスクのリファレンス情報については、「wsdl2Service」を参照してください。
以下に、簡単な build.xml ファイルの例を示します。
<project name="buildWebservice" default="generate-from-WSDL">
<target name="generate-from-WSDL">
<wsdl2service
wsdl="wsdls/myService.wsdl"
destDir="myService/implementation"
typeMappingFile="autotype/types.xml"
packageName="example.ws2j.service" />
</target>
</project>
例の中の wsdl2Service Ant タスクでは、WSDL ファイル wsdls/myService.wsdl の最初の <service> 要素の Java インタフェース ファイルが生成されます。非組み込みデータ型のデータ型マッピング情報は、autotype/types.xml ファイルから利用します。このファイルは、通常は事前に autotype Ant タスクを実行して生成されています。 Java インタフェース ファイルおよび web-services.xml ファイルは、myService/implementation ディレクトリに生成されます。
WSDL ファイルの最初の <service> 要素の name 属性の値が、SuperDooperService であると仮定します。この場合、wsdl2Service によって example.ws2j.service.SuperDooperService という名前の Java インタフェースが生成され、その Java 実装クラスの名前は example.ws2j.service.SuperDooperServiceImpl となります。
Web サービス オペレーションを実装するメソッドのパラメータまたは戻り値として使用されている Java データ型の中には、ネットワークでの転送時に、SOAP 添付ファイルとして (SOAP 本文の要素としてではなく) 自動的に転送されるものがあります。次の表は、それらに該当する Java データ型と SOAP 添付ファイルでのその MIME タイプです。
これらの Java データ型をパラメータまたは戻り値に使用する Java クラスまたは EJB のメソッドをコード化し、servicegen でその Web サービスをアセンブルする場合は、これらのパラメータまたは戻り値に該当するデータについては SOAP 添付ファイルを使用することが、生成された web-services.xml デプロイメント記述子ファイルによって自動的に指定されます。具体的には、<param> または <return-param> の location 属性が、attachment に設定されます。クライアント アプリケーションが Web サービスを呼び出したときは、パラメータまたは戻り値のどちらか、あるいはその両方がこの表にある Java データ型に該当するかどうかに基づき、WebLogic Web サービス実行時システムによって自動的に、SOAP リクエストの添付ファイルでパラメータ データが検索されるか、または SOAP 応答の添付ファイルに戻り値データが追加されます。
SOAP 添付ファイルに直接アクセスして操作する場合は、SOAP メッセージ ハンドラを作成して、SOAP with Attachments API for Java 1.1 (SAAJ) を使用する必要があります。詳細については、「SOAP メッセージをインターセプトする SOAP メッセージ ハンドラの作成」を参照してください。
Java データ型 java.lang.String は、前節の説明とは少し異なる機能を果たします。デフォルトでは、Web サービス オペレーションを実装するメソッドに java.lang.String を使用すると、servicegen Ant タスクおよび WebLogic Web サービス実行時システムにより、組み込みデータ型として扱われます。つまり、このデータは、SOAP 添付ファイルの text/plain MIME タイプではなく、XML スキーマの string 型として SOAP 本文の要素となります。
一方、java.lang.String パラメータまたは戻り値を text/plain MIME エンコードの SOAP 添付ファイルとして転送する場合は、web-services.xml デプロイメント記述子ファイルを手動で更新し、該当する <param> 要素または <return-value> 要素の location 属性の値をデフォルトの Body から attachment に変更する必要があります。
web-services.xml ファイルの属性と要素の詳細については、「WebLogic Web サービス デプロイメント記述子の要素」を参照してください。
javax.activation.DataHandler データ型は、「SOAP 添付ファイルを使用する」の表にないデータを SOAP 添付ファイルで表すために使用します。
DataHandler クラスは、多くの異なるソースおよび形式のデータに対する一貫性のあるインタフェースを提供します。このクラスでは、ストリームから文字列への変換と関連するオペレーションが javax.activation.DataContentHandlers を使用して管理されます。DataHandler クラスは、データに作用できるコマンドへのアクセスも提供します。それらのコマンドは、javax.activation.CommandMap クラスを使用して確認できます。
DataHandlers は、J2EE JavaBeans Activation Framework 規格拡張機能の一部です。 WebLogic Web サービス オペレーションのパラメータまたは戻り値の型として DataHandler を使用する場合は、DataContentHandler などの必要なすべての構成要素が実装されていることが前提となります。
DataHandlers の一般情報とその実装方法については、「JavaBeans Activation Framework」を参照してください。JavaBeans Activation Framework API については、「Javadoc」を参照してください。
WebLogic Web サービス オペレーションが返す値は一般的には 1 つで、その Web サービス オペレーションを実装する EJB メソッドまたは Java クラス メソッドの戻り値を返します。Web サービスのオペレーションで複数の値が返されるようにする場合は、以下のいずれかを行います。
out および inout パラメータは、オペレーションのパラメータがパラメータと戻り値の両方の標準として機能できるメカニズムです。 out パラメータは、オペレーションの呼び出し時には未定義ですが、オペレーションの完了時にはそのオペレーションを実装するメソッドによって定義されます。inout パラメータは、呼び出し時および完了時に定義されます。たとえば、Web サービス オペレーションに out パラメータがあり、そのオペレーションは EJB メソッドを使用して実装されるとします。この EJB メソッドは、out パラメータの値を設定し、オペレーションを呼び出したクライアント アプリケーションにこの値を返します。すると、クライアント アプリケーションは、戻り値の場合と同様に、この out パラメータの値にアクセスすることができます。inout パラメータは、メソッドに情報を送信する標準の in パラメータと out パラメータの両方の機能を備えたパラメータです。この節では、out または inout パラメータを使用する EJB メソッドまたは Java クラス メソッドを使用して Web サービス オペレーションを実装する方法について説明します。
次の例は、第 2 のパラメータとして inout パラメータを持つメソッドを示しています。
public String myMethod( String param1,
javax.xml.rpc.holders.IntHolder intHolder ) {
System.out.println ("The input value is: " + intHolder.value );
intHolder.value = 20; // out パラメータの新しい値
return param1;
}
このメソッドは、文字列と整数の 2 つのパラメータを使用して呼び出します。このメソッドは、文字列 (標準の戻り値) と整数 (IntHolder ホルダ パラメータを介して) という 2 つの値を返します。
out パラメータおよび inout パラメータは、javax.xml.rpc.holders.Holder インタフェースを実装する必要があります。Holder.value フィールドを使用して、まず、inout パラメータの入力値にアクセスし、次に、out および inout パラメータの値を設定します。先の例で、第 2 のパラメータに値 40 を指定してメソッドを呼び出したものとします。このメソッドの完了時には、intHolder 値は 20 となります。
out または inout パラメータが標準のデータ型である場合は、次の表に記載する JAX-RPC のホルダ クラスのいずれかを使用することができます。
パラメータのデータ型が用意されていない場合は、自分で実装を作成する必要があります。
自分で javax.xml.rpc.holders.Holder インタフェースの実装を作成するには、次のガイドラインに従います。
TypeHolder という実装クラスを指名する。ここで、Type は、複合型の名前です。たとえば、複合型の名前が Person なら、実装クラスの名前は PersonHolder となります。Holder 実装クラスは、保持するクラス パッケージの下の holders サブパッケージにパッケージ化する必要がある。たとえば、複合型 Person が examples.webservices パッケージにある場合は、PersonHolder 実装クラスは examples.webservices.holders パッケージに作成します。
value というパブリック フィールドを作成する。そのデータ型はパラメータと同じです。value フィールドをデフォルト値に初期化するデフォルト コンストラクタを作成する。value フィールドを渡されたパラメータの値に設定するコンストラクタを作成する。次の例は、PersonHolder 実装クラスの概略を示しています。
package examples.webservices.holders;
public final class PersonHolder implements
javax.xml.rpc.holders.Holder {
public Person value;
public PersonHolder() {
// value 変数をデフォルト値に設定
}
public PersonHolder (Person value) {
// value 変数を渡された値に設定
}
}
out または inout パラメータの Holder 実装クラスを作成したら、Web サービス オペレーションを実装するメソッドの Java コードを更新し、作成した Holder クラスを使用します。後で servicegen Ant タスクを使用して Web サービスをアセンブルするときは、生成された web-services.xml ファイルの次の箇所によって、inout パラメータの使用が自動的に指定されます。
<param name="inoutparam" style="inout"
type="xsd:Person" />
inout パラメータではなく、out パラメータを使用する場合は、生成された web-services.xml ファイルを手動で更新する必要があります。
out または inout パラメータを使用する Web サービスを呼び出すクライアント アプリケーションを記述する方法の詳細については、「out または inout パラメータを使用するクライアントを記述する」を参照してください。
WebLogic Web サービスを実装する EJB または Java クラスにエラー処理用の Java コードを記述するときは、独自の例外または javax.xml.rpc.soap.SOAPFaultException 例外のいずれかを送出できます。SOAPFaultException を送出すると、WebLogic Server はその例外を SOAP 障害にマップして、オペレーションを呼び出すクライアント アプリケーションに送信します。
EJB または Java クラスが他のタイプの Java 例外を送出する場合、WebLogic Server は、それをできるだけ SOAP 障害にマップしようとします。とはいえ、クライアント アプリケーションが最も有効な例外情報を送受信するように制御するには、SOAPFaultException 例外またはこの例外を拡張する例外を明示的に送出する必要があります。
次の抜粋では、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 オブジェクトのコンテナになります。
次のクラスは、Web サービスの実装内から、SOAPFaultException を作成して送出する例です。
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.Detail;
import javax.xml.soap.SOAPException;
import javax.xml.namespace.QName;
import javax.xml.rpc.soap.SOAPFaultException;
public class HelloWorldService{
public void helloSOAPFault(){
Detail detail = null;
try{
detail = SOAPFactory.newInstance().createDetail();
detail.addChildElement( "MyDetails" ).addTextNode( "failed" );
}catch( SOAPException e ){
e.printStackTrace();
}
throw new SOAPFaultException(
new QName( "http://tutorial/sample9/fault", "ServerFailed" ),
"helloSOAPFault method failed",
"http://foo/bar/baz/",
detail );
}
public void helloCustomFault() throws HelloWorldException{
throw new HelloWorldException( "This is my error message, " +
"client should get this" );
}
}
警告 :SOAPFaultException を使用せずに独自の例外を作成および送出し、例外クラスの複数のプロパティのデータ型が同じである場合、JAX-RPC 仕様では必要とされていませんが、これらのプロパティのセッター メソッドも作成する必要があります。これは、WebLogic Web サービスが SOAP メッセージで例外を受け取り、XML を Java 例外クラスに変換するときに、対応するセッター メソッドがなければ、どの XML 要素をどのクラス プロパティにマップするのかを知る方法が存在しないからです。
次の節では、WebLogic Web サービスがサポートする組み込みデータ型およびその XML 表現と Java 表現間のマッピングについて説明します。Web サービスを実装するバックエンド コンポーネントのパラメータと戻り値のデータ型が、組み込みデータ型のセットの中にある限り、データは WebLogic Server によって、XML と Java 間で自動的に変換されます。
一方、非組み込みデータ型を使用する場合は、データの XML、Java 間のデータ変換を行うシリアライゼーション クラスを作成する必要があります。WebLogic Server には、ほとんどの非組み込みデータ型のシリアライゼーション クラスを生成できる servicegen および autotype Ant タスクが用意されています。サポートされている XML および Java データ型のリストは、「servicegen および autotype Ant タスクでサポートされる非組み込みデータ型」を参照してください。 servicegen および autotype の使い方の詳細については、「Ant タスクを使用した WebLogic Web サービスのアセンブル」を参照してください。
サポートされていないデータ型については、シリアライゼーション クラスを手動で作成する必要があります。詳細については、「非組み込みデータ型の使い方」を参照してください。
次の表に、XML スキーマ (ターゲット ネームスペース http://www.w3.org/2001/XMLSchema) が定義するすべての組み込みデータ型に対する定義済みマッピングと、対応する SOAP データ型 (ターゲット ネームスペース http://schemas.xmlsoap.org/soap/encoding/) を示します。
サポートされている非組み込み XML データ型のリストは、「サポートされている XML 非組み込みデータ型」を参照してください。
サポートされている非組み込み Java データ型のリストは、「サポートされている Java 非組み込みデータ型」を参照してください。
|
|
|