| Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS を使用した Web サービス入門 11g リリース 1 (10.3.1) B55565-01 |
|
 戻る |
 次へ |
| Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS を使用した Web サービス入門 11g リリース 1 (10.3.1) B55565-01 |
|
戻る |
次へ |
以下の節では、Web サービスを実装する JWS ファイルのプログラミングについて説明します。
WebLogic Web サービスをゼロからプログラムする方法は 2 つあります。
JSR-181、JAX-WS 仕様、および WebLogic Web サービス プログラミング モデルで規定されているように、標準の EJB または Java クラスに Web サービス Java アノテーションを付けます。
デプロイメント記述子、WSDL ファイル、データ マッピング記述子、データ バインディング アーティファクト (ユーザ定義のデータ型用) など、JSR-109 で指定されているさまざまな XML 記述子ファイルやアーティファクトと、標準の EJB または Java クラスを結合します。
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) (http://www.jcp.org/en/jsr/detail?id=181 を参照) で定義される標準的な JWS アノテーションに加え、作成中の Web サービスの種類 (JAX-WS または JAX-RPC) に基づいたその他のアノテーション セットの使用が可能です。JAX-WS Web サービスおよび JAX-RPC Web サービスに対してサポートされている JWS アノテーションの完全なリストについては、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「Web サービスのアノテーション サポート」を参照してください。
JWS ファイルをプログラミングする際は、基本的な Web サービス機能をプログラムするためにアノテーションを含めます。アノテーションは、JWS ファイル内のさまざまなレベル、さまざまな対象で使用されます。一部のアノテーションはクラス レベルで使用され、そのアノテーションが JWS ファイル全体に適用されることを示します。それ以外のアノテーションには、メソッド レベルで使用するものや、パラメータ レベルで使用するものがあります。
JWS ファイルをプログラミングする場合は、Web Services Metadata for the Java Platform 仕様 (JSR-181) (http://www.jcp.org/en/jsr/detail?id=181) で指定された一連の要件に従う必要があります。特に、Web サービスを実装する Java クラスは、次の要件に従う必要があります。
パブリック クラスでなければならない。final クラスや abstract クラスとして宣言することはできません。
デフォルトのパブリック コンストラクタを持つ必要がある。
finalize() メソッドは定義できない。
少なくとも、クラス レベルで @WebService JWS アノテーションを指定して、その JWS ファイルが Web サービスを実装することを指定する必要がある。
@WebService.endpointInterface アノテーションを使用して、サービス エンドポイント インタフェースを参照できる。この場合は、サービス エンドポイント インタフェースが存在することを前提としています。JWS ファイルでは @WebService.endpointInterface、@WebService.serviceName および @WebService.targetNamespace 以外の JWS アノテーションを指定することはできません。
JWS ファイルにサービス エンドポイント インタフェースが実装されていない場合は、java.lang.Object から継承されたもの以外のすべてのパブリック メソッドが、Web サービス オペレーションとして公開される。この動作は、@WebMethod アノテーションを使用して、公開するパブリック メソッドを明示的に指定することによって、オーバーライドできます。@WebMethod アノテーションが存在する場合は、それが適用されるメソッドのみが公開されます。
以下の手順では、Web サービスを実装する JWS ファイルをプログラミングするための一般的な手順を説明します。
|
注意 : JWS ファイルを作成してあり、そこに JWS アノテーションを追加する予定であることを前提としています。 |
各 JWS アノテーションの詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「JWS アノテーション リファレンス」を参照してください。
表 4-1 JWS ファイルのプログラミング手順
| # |
手順 | 説明 |
|---|---|---|
|
1 |
JWS ファイルで使用する標準の JWS アノテーションをインポートする。 |
標準の JWS アノテーションは import javax.jws.WebMethod; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; import javax.xml.ws.BindingType; |
|
2 |
必要に応じて、追加のアノテーションをインポートする。 |
サポートされている JWS アノテーションの完全なリストについては、『Oracle Fusion Middleware Oracle WebLogic Server Web サービス リファレンス』の「Web サービスのアノテーション サポート」を参照。 |
|
3 |
必須の標準 |
|
|
4 |
標準の |
特に、このアノテーションを使用して、Web サービスがドキュメントリテラルか、ドキュメントエンコードかなどを指定する。「Web サービスと SOAP メッセージ プロトコルのマッピングの指定 (@SOAPBinding アノテーション)」を参照。 この JWS アノテーションは必須ではないが、JWS ファイルで明示的に指定し、クライアント アプリケーションが Web サービスの呼び出しに使用する SOAP バインディングのタイプを明確にすることが推奨される。 |
|
5 |
クラス レベルで JAX-WS |
|
|
6 |
パブリック オペレーションとして公開する JWS ファイルの各メソッドで標準の |
必要に応じて、標準の |
|
7 |
|
「オペレーションのパラメータと WSDL 要素のマッピングのカスタマイズ (@WebParam アノテーション)」を参照。 |
|
8 |
|
「オペレーションの戻り値と WSDL 要素のマッピングのカスタマイズ (@WebResult アノテーション)」を参照。 |
|
9 |
独自のビジネス コードを追加する。 |
Web サービスが希望どおりに動作するように、独自のビジネス コードをメソッドに追加する。 |
以下のサンプル JWS ファイルでは、簡単な Web サービスの実装方法を示します。
package examples.webservices.simple;
// 標準の JWS アノテーション インタフェースをインポートする
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// 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)
/**
* この 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 に入っていると想定します。
portname - wsdl:port 内で使用される名前。
@WebService アノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181) 仕様 (http://www.jcp.org/en/jsr/detail?id=181) を参照してください。
ここでは、Web サービスを SOAP メッセージ プロトコルで使用できるようにします。そのためには、JWS ファイル内にクラス レベルで標準の @SOAPBinding アノテーションを含めて、Web サービスの SOAP バインディング (document-encoded または document-literal-wrapped など) を指定します。次のコードの抜粋を参照してください。
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
この例で、Web サービスは document-wrapped-style エンコーディングとリテラル メッセージ フォーマットを使用しています。@SOAPBinding アノテーションを使用しない場合でも、これらはデフォルトのフォーマットとなります。一般に、最も相互運用性の高いタイプの Web サービスは、document-literal-wrapped の Web サービスである。
(style=SOAPBinding.Style.DOCUMENT 属性と一緒に) parameterStyle 属性を使用して、Web サービス オペレーションのパラメータが、SOAP メッセージ本文全体を表すかどうか、または、オペレーションと同じ名前の最上位要素内にラップされる要素かどうかを指定します。
次の表では、標準および WebLogic 固有の @SOAPBinding アノテーションの 3 つの属性の指定できる値とデフォルト値を示します。
標準の @WebMethod アノテーションを使用して、JWS ファイルのメソッドを Web サービスのパブリック オペレーションとして公開することを指定します。次のコードの抜粋を参照してください。
public class SimpleImpl {
@WebMethod(operationName="sayHelloOperation")
public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}
...
この例では、SimpleImpl JWS ファイルの sayHello() メソッドが、Web サービスのパブリック オペレーションとして公開されます。ただし、operationName 属性では、WSDL ファイル内のオペレーションのパブリック名は sayHelloOperation になることを指定しています。operationName 属性を指定しない場合は、メソッドの名前がオペレーションのパブリック名になります。
action 属性を使用してオペレーションのアクションを指定することもできます。SOAP をバインディングとして使用する場合、action 属性の値によって、SOAP メッセージ内の SOAPAction ヘッダの値が決まります。
Web サービス オペレーションとしてメソッドを除外するには、@WebMethod(exclude="true") を指定します。
|
注意 : サービス エンドポイント インタフェース (SEI) は、JAX-WS のためにパブリック メソッドを定義します。SEI が存在しない場合、すべてのパブリック メソッドが、明示的にタグの付いたそれらが @WebMethod(exclude="true") になければ、Web サービス オペレーションとしてエクスポーズされます。 |
標準の @Oneway アノテーションを使用して、オペレーションが呼び出し側アプリケーションに値を返さないことを指定できます。次の例を参照してください。
public class OneWayImpl {
@WebMethod()
@Oneway()
public void ping() {
System.out.println("ping operation");
}
...
オペレーションが一方向であることを指定する場合、実装するメソッドは void を返す必要があります。パラメータとしてホルダ クラスを使用したり、チェック済み例外を送出したりすることはできません。
@WebMethod アノテーションの属性はいずれも必須ではありません。@WebMethod および @Oneway アノテーションに関する追加情報や、各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181) 仕様 (http://www.jcp.org/en/jsr/detail?id=181) を参照してください。
標準の @WebParam アノテーションを使用して、Web サービス オペレーションの入力パラメータと生成される WSDL ファイルの要素との間のマッピングをカスタマイズしたり、パラメータの動作を指定したりします。次のコードの抜粋を参照してください。
public class SimpleImpl {
@WebMethod()
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/docLiteralBare")
public int echoInt(
@WebParam(name="IntegerInput",
targetNamespace="http://example.org/docLiteralBare")
int input)
{
System.out.println("echoInt '" + input + "' to you too!");
return input;
}
...
この例では、生成される WSDL ファイル内の echoInt オペレーションのパラメータ名は IntegerInput になります。JWS ファイルに @WebParam アノテーションがない場合、生成される WSDL ファイル内のパラメータ名は、メソッドのパラメータ名 input と同じになります。targetNamespace 属性は、パラメータの XML ネームスペースが http://example.org/docLiteralBare であることを指定します。この属性は、パラメータと XML 要素がマップされる、ドキュメント スタイルの SOAP バインディングを使用する場合にのみ有効です。
@WebParam アノテーションの以下の追加の属性を指定することもできます。
mode - パラメータの入出力の方向 (WebParam.Mode.IN、WebParam.Mode.OUT、または WebParam.Mode.INOUT)。OUT および INOUT モードは、RPC 形式のオペレーション、またはヘッダにマップされるパラメータでのみサポートされます。
header - true に設定した場合、パラメータの値はデフォルトの本文からではなく SOAP ヘッダから取得されることを指定する、ブール型の属性。
@WebParam アノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181) 仕様 (http://www.jcp.org/en/jsr/detail?id=181) を参照してください。
標準の @WebResult アノテーションを使用して、Web サービス オペレーションの戻り値と生成される WSDL ファイル内の対応する要素との間のマッピングをカスタマイズします。次のコードの抜粋を参照してください。
public class Simple {
@WebMethod()
@WebResult(name="IntegerOutput",
targetNamespace="http://example.org/docLiteralBare")
public int echoInt(
@WebParam(name="IntegerInput",
targetNamespace="http://example.org/docLiteralBare")
int input)
{
System.out.println("echoInt '" + input + "' to you too!");
return input;
}
...
この例では、生成される WSDL ファイル内の echoInt オペレーションの戻り値の名前は IntegerOutput になります。JWS ファイルに @WebResult アノテーションがない場合、生成される WSDL ファイル内の戻り値の名前は、ハードコード化された名前 return になります。targetNamespace 属性は、戻り値の XML ネームスペースが http://example.org/docLiteralBare であることを指定します。この属性は、戻り値と XML 要素がマップされる、ドキュメント スタイルの SOAP バインディングを使用する場合にのみ有効です。
@WebResult アノテーションの属性はいずれも必須ではありません。各属性のデフォルト値については、Web Services Metadata for the Java Platform (JSR 181) 仕様 (http://www.jcp.org/en/jsr/detail?id=181) を参照してください。
JAX-WS @BindingType アノテーションを使用すると、Web サービス エンドポイント実装クラスに使用するバインディングをカスタマイズすることができます。次のコードの抜粋を参照してください。
import javax.xml.ws.BindingType; import javax.xml.ws.soap.SOAPBinding; public class Simple { @WebService() @BindingType(value=SOAPBinding.SOAP12HTTP_BINDING) public int echoInt( @WebParam(name="IntegerInput", targetNamespace="http://example.org/docLiteralBare") int input) { System.out.println("echoInt '" + input + "' to you too!"); return input; } ...
この例のデプロイメントされたエンドポイントでは、SOAP1.2 over HTTP バインディングが使用されます。何も指定しない場合、バインディングのデフォルトは SOAP 1.1 over HTTP になります。
@BindingType アノテーションの以下の追加属性を指定することもできます。
features — 指定したバインディングにおいて有効化/無効化する機能の配列。指定しない場合、機能は独自規則に基づいて有効化されます。
@BindingType アノテーションの詳細については、JAX-WS 2.1 アノテーション (https://jax-ws.dev.java.net/nonav/2.1.4/docs/annotations.html) を参照してください。
クライアント アプリケーションが、JWS ファイルで実装された WebLogic Web サービスを呼び出すと、WebLogic Server は、Web サービスやクライアントが、サービスに関する実行時情報のアクセス、および場合によっては変更に使用できるコンテキストを自動的に作成します。
実行時情報には、以下のいずれかの方法でアクセスできます。
javax.xml.ws.BindingProvider (http://java.sun.com/javase/6/docs/api/javax/xml/ws/BindingProvider.html) — クライアント アプリケーションから、プロトコル バインディングの要求および応答コンテキストへアクセスします。「プロトコル バインディング コンテキストへのアクセス」を参照してください。
javax.xml.ws.WebServiceContext (http://java.sun.com/javase/6/docs/api/javax/xml/ws/WebServiceContext.html) — Web サービスから、処理されている要求に関連するセキュリティ情報や実行時メッセージ コンテキストにアクセスします。WebServiceContext は通常、@Resource アノテーションを使用してエンドポイントに注入されます。「Web サービス コンテキストへのアクセス」を参照してください。
javax.xml.ws.handler.MessageContext (http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/MessageContext.html) — Web サービスの WebServiceContext から直接、あるいはクライアント アプリケーションや Web サービスのメッセージ ハンドラから実行時プロパティ セットへアクセスします。「MessageContext プロパティ値の使用」を参照してください。
以降の節では、BindingProvider、WebServiceContext、および MessageContext を使用して実行時情報へアクセスする方法の詳細を説明します。
|
注意 : com.sun.xml.ws.developer.JAXWSPropertieshttps://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/JAXWSProperties.html) および com.sun.xml.ws.client.BindingProviderProperties (https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/client/BindingProviderProperties.html) API は、Sun Microsystems が提供する JDK 6.0 の拡張としてサポートされています。これらの API は JDK 6.0 キットの一部としては提供されないため、変更される可能性があります。 |
javax.xml.ws.BindingProvider インタフェースを使用すると、クライアント アプリケーションから、プロトコル バインディングの要求および応答コンテキストへアクセスすることができます。詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/ws/BindingProvider.html を参照してください。Web サービス クライアント ファイルの開発に関する詳細については、「Web サービスの呼び出し」を参照してください。
次に、コンテキストを使用して HTTP リクエスト ヘッダ情報へアクセスする簡単な Web サービス クライアント アプリケーションの例を示します。太字のコードについては、例の後のプログラミングのガイドラインで説明しています。
package examples.webservices.hello_world.client; import javax.xml.namespace.QName; import java.net.MalformedURLException; import java.net.URL; import java.util.Map; import javax.xml.ws.BindingProvider; import javax.xml.ws.handler.MessageContext; import com.sun.xml.ws.developer.JAXWSProperties; import com.sun.xml.ws.client.BindingProviderProperties; /** * 簡単な Web サービスの <code>sayHelloWorld</code> オペレーションを呼び出す * 単純なスタンドアロンのクライアント アプリケーション */ public class Main { public static void main(String[] args) { HelloWorldService service; try { service = new HelloWorldService(new URL(args[0] + "?WSDL"), new QName("http://hello_world.webservices.examples/", "HelloWorldService") ); } catch (MalformedURLException murl) { throw new RuntimeException(murl); } HelloWorldPortType port = service.getHelloWorldPortTypePort(); String result = null; result = port.sayHelloWorld("Hi there!"); System.out.println( "Got result: " + result ); Map requestContext = ((BindingProvider)port).getRequestContext(); requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://examples.com/HelloWorldImpl/HelloWorldService"); requestContext.put(JAXWSProperties.CONNECT_TIMEOUT, 300); requestContext.put(BindingProviderProperties.REQUEST_TIMEOUT, 300); Map responseContext = ((BindingProvider)port).getResponseContext(); Integer responseCode = (Integer)responseContext.get(MessageContext.HTTP_RESPONSE_CODE); ... } }
上記の例の太字のコードで示すように、Web サービスの実行時コンテキストにアクセスするには、JWS ファイルで以下のガイドラインに従います。
javax.xml.ws.BindingProvider API に加え、使用する可能性のあるその他の関連 API をインポートする。
import java.util.Map; import javax.xml.ws.BindingProvider; import javax.xml.ws.handler.MessageContext; import com.sun.xml.ws.developer.JAXWSProperties; import com.sun.xml.ws.client.BindingProviderProperties; import com.sun.xml.ws.client.BindingProviderProperties;
BindingProvider クラスのメソッドを使用して、バインディング プロトコル コンテキスト情報へアクセスする。次の例は、プロトコル バインディングの要求および応答コンテキストを取得してから要求コンテキスト用にクライアントで使用される対象サービス エンドポイント アドレスを設定し、要求コンテキストの接続や読み取りのタイムアウト時間 (ミリ秒単位) と HTTP 応答ステータス コードを設定する方法を示しています。
Map requestContext = ((BindingProvider)port).getRequestContext(); requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://examples.com/HelloWorldImpl/HelloWorldService"); requestContext.put(JAXWSProperties.CONNECT_TIMEOUT, 300); requestContext.put(BindingProviderProperties.REQUEST_TIMEOUT, 300); Map responseContext = ((BindingProvider)port).getResponseContext(); Integer responseCode = (Integer)responseContext.get(MessageContext.HTTP_RESPONSE_CODE);
次の表では、Web サービスに関する実行時情報にアクセスするために JWS ファイルで使用できる javax.xml.ws.BindingProvider のメソッドについて簡単に説明します。
表 4-3 BindingProvider のメソッド
| メソッド | 戻り値 | 説明 |
|---|---|---|
|
|
|
バインディング プロバイダのバインディングを返す。 |
|
|
|
要求メッセージのコンテキストおよびメッセージの初期化に使用されるコンテキストを返す。 |
|
|
|
応答コンテキストを返す。 |
要求および応答コンテキストを取得したら、次の表で定義している BindingProvider プロパティ値と、「MessageContext プロパティ値の使用」で定義している MessageContext プロパティ値にアクセスできます。
表 4-4 BindingProvider のプロパティ
| プロパティ | タイプ | 説明 |
|---|---|---|
|
|
|
対象サービス エンドポイント アドレス。 |
|
|
|
認証用パスワード。 |
|
|
|
サービス クライアントがサービス エンドポイントとのセッションに参加するかどうかを示すフラグ。デフォルト値の |
|
|
|
SOAPAction URI. を指定する SOAPAction のプロパティ。このプロパティは、 |
|
|
|
SOAPAction を使用するかどうかを指定する SOAPAction のプロパティ。 |
|
|
|
認証用ユーザ名。 |
また、前の例の以下の点に注目してください。
JAXWSProperties.CONNECT_TIMEOUT プロパティを使用して接続タイムアウトを定義している。設定可能な JAXWSProperties の完全なリストについては、com.sun.xml.ws.developer.JAXWSProperties Javadoc (https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/JAXWSProperties.html) を参照してください。
BindingProviderProperties.REQUEST_TIMEOUT プロパティを使用して要求タイムアウトを定義している。設定可能な BindingProviderProperties の完全なリストについては、com.sun.xml.ws.client.BindingProviderProperties Javadoc (https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/client/BindingProviderProperties.html) を参照してください。
javax.xml.ws.WebServiceContext インタフェースを使用すると、Web サービスから、処理されている要求に関連するセキュリティ情報や実行時メッセージ コンテキストにアクセスできます。WebServiceContext は通常、@Resource アノテーションを使用してエンドポイントに注入されます。詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/ws/WebServiceContext.html を参照してください。
次に、コンテキストを使用して HTTP リクエスト ヘッダ情報へアクセスする簡単な JWS ファイルの例を示します。太字のコードについては、例の後のプログラミングのガイドラインで説明しています。
package examples.webservices.jws_context;
import javax.jws.WebMethod;
import javax.jws.WebService;
import java.util.Map;
import javax.xml.ws.WebServiceContext;
import javax.annotation.Resource;
import javax.xml.ws.handler.MessageContext;
@WebService(name="JwsContextPortType", serviceName="JwsContextService",
targetNamespace="http://example.org")
/**
* @Context アノテーションの使い方を示す簡単な Web サービス
*/
public class JwsContextImpl {
@Resource
private WebServiceContext ctx;
@WebMethod()
public String msgContext(String msg) {
MessageContext context=ctx.getMessageContext();
Map requestHeaders = (Map)context.get(MessageContext.HTTP_REQUEST_HEADERS);
}
}
上記の例の太字のコードで示すように、Web サービスの実行時コンテキストにアクセスするには、JWS ファイルで以下のガイドラインに従います。
@javax.annotation.Resource JWS アノテーションをインポートする。
import javax.annotation.Resource;
javax.xml.ws.WebServiceContext API に加え、使用する可能性のあるその他の関連 API をインポートする。
import java.util.Map; import javax.xml.ws.WebServiceContext; import javax.xml.ws.handler.MessageContext;
データ型 javax.xml.ws.WebServiceContext のプライベート変数に、フィールド レベルの @Resource JWS アノテーションを指定する。
@Resource private WebServiceContext ctx;
WebServiceContext クラスのメソッドを使用して、Web サービスの実行時情報にアクセスする。次の例は、現在のサービス要求のメッセージ コンテキストを取得してから、HTTP リクエスト ヘッダにアクセスする方法を示しています。
MessageContext context=ctx.getMessageContext(); Map requestHeaders = (Map)context.get(MessageContext.HTTP_REQUEST_HEADERS)
MessageContext プロパティ値の詳細については、「MessageContext プロパティ値の使用」を参照してください。
次の表では、Web サービスに関する実行時情報にアクセスするために JWS ファイルで使用できる avax.xml.ws.WebServiceContext のメソッドについて簡単に説明します。詳細については、http://java.sun.com/javase/6/docs/api/javax/xml/ws/WebServiceContext.html. を参照してください。
表 4-5 WebServiceContext のメソッド
| メソッド | 戻り値 | 説明 |
|---|---|---|
|
|
|
現在のサービス要求の MessageContext を返す。MessageContext プロパティ値の使用で定義しているように、 |
|
|
|
現在のサービス要求の送信者を識別するプリンシパルを返す。送信者が認証されていない場合、 |
|
|
|
指定された論理的なロールに認証ユーザが含まれているかどうかを示すブール値を返す。ユーザが認証されていない場合、 |
次の表では、Web サービスの WebServiceContext から直接、あるいはクライアント アプリケーションや Web サービスのメッセージ ハンドラからアクセス可能な javax.xml.ws.handler.MessageContext プロパティ値を示しています。詳細については、javax.xml.ws.handler.MessageContext Javadoc (http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/class-use/MessageContext.html) を参照してください。
表 4-6 MessageContext のプロパティ
| プロパティ | タイプ | 説明 |
|---|---|---|
|
|
|
リクエスト メッセージの HTTP リクエスト ヘッダのマップ。 |
|
|
|
GET、POST、PUT などの HTTP リクエスト メソッド。 |
|
|
|
最終呼び出しの HTTP 応答ステータス コード。 |
|
|
|
HTTP 応答ヘッダ。 |
|
|
|
着信メッセージの添付のマップ。 |
|
|
|
メッセージの方向。このプロパティは、発信メッセージの場合は |
|
|
|
発信メッセージの添付のマップ。 |
|
|
|
リクエスト パス情報。 |
|
|
|
リクエストのクエリ文字列。 |
|
|
|
WS-Addressing 参照パラメータ。リストには、 |
|
|
|
リクエストに関連するサーブレット コンテキスト オブジェクト。 |
|
|
|
リクエストに関連するサーブレット リクエスト オブジェクト。 |
|
|
|
リクエストに関連するサーブレット応答オブジェクト。 |
|
|
|
WSDL ドキュメントの入力ソース (解決可能な URI)。 |
|
|
|
ポート タイプまたは WSDL インタフェースの名前。 |
|
|
|
現在のメッセージが所属する WSDL オペレーションの名前。 |
|
|
|
メッセージを受け取った WSDL ポートの名前。 |
|
|
|
呼び出し対象サービスの名前。 |
jwsc Ant タスクでは、JWS ファイルを処理するときは常に、Web サービスの基底の実装としてプレーン Java オブジェクトが選択されます。
しかし、Web サービスの基底の実装をステートレス セッション EJB にして、EJB が提供するすべての機能 (インスタンス プール、トランザクション、セキュリティ、コンテナ管理による永続性、コンテナ管理による関係、データ キャッシュなど) を活用したい場合もあります。Web サービスの実装を EJB にする場合は、次の節のプログラミング ガイドラインに従ってください。
EJB 3.0 では、EJB を実装する場合に必要な EJB リモートおよびホーム インタフェース クラスおよびデプロイメント記述子ファイルを、手動で作成するのではなく、自動的に生成することができるメタデータ アノテーションが導入されました。EJB 3.0 の詳細については、『Oracle Fusion Middleware Oracle WebLogic Server エンタープライズ JavaBeans バージョン 3.0 プログラマーズ ガイド』を参照してください。
JWS ファイルに EJB を実装するには、次の手順に従います。
EJB 3.0 アノテーションをインポートする。これらのアノテーションはすべて javax.ejb パッケージにあります。少なくとも、@Stateless アノテーションはインポートする必要があります。JWS ファイルには EJB の形式および動作を指定する追加の EJB アノテーションを指定することもできます。詳細については、javax.ejbJavadoc (http://java.sun.com/javaee/5/docs/api/javax/ejb/package-summary.html) を参照してください。
次に例を示します。
import javax.ejb.Stateless;
少なくとも、クラス レベルで @Stateless アノテーションを使用し、EJB を識別する。
@Stateless
public class SimpleEjbImpl {
以下の例では、ステートレス セッション EJB を実装する簡単な JWS ファイルを示します。関連するコードは太字で示されています。
package examples.webservices.jaxws; import weblogic.transaction.TransactionHelper; import javax.ejb.Stateless; import javax.ejb.SessionContext; import javax.ejb.TransactionAttribute; import javax.ejb.TransactionAttributeType; import javax.annotation.Resource; import javax.jws.WebService; import javax.jws.WebMethod; import javax.transaction.SystemException; import javax.transaction.Status; import javax.transaction.Transaction; import javax.xml.ws.WebServiceContext; /** * トランザクションを認識したステートレス EJB 実装の JWS */ // Web サービスのポート名、サービス名、および対象ネームスペースを // 指定する標準の JWS アノテーション @WebService( name = "Simple", portName = "SimpleEJBPort", serviceName = "SimpleEjbService", targetNamespace = "http://wls/samples") //標準の EJB アノテーション @Stateless public class SimpleEjbImpl { @Resource private WebServiceContext context; private String constructed = null; // WebMethod アノテーションで、以降のメソッドを Web サービスのパブリック // オペレーションとしてエクスポーズする @WebMethod() @TransactionAttribute(TransactionAttributeType.REQUIRED) public String sayHello(String s) throws SystemException { Transaction transaction = TransactionHelper.getTransactionHelper().getTransaction(); int status = transaction.getStatus(); if (Status.STATUS_ACTIVE != status) throw new IllegalStateException("transaction did not start, status is: " + status + ", check ejb annotation processing"); return constructed + ":" + s; }
Web サービス オペレーションとして公開される JWS ファイルのメソッドでは、パラメータや戻り値として必ずしも組み込みのデータ型 (String や integer など) を取る必要はなく、独自に作成する Java データ型を使用することができます。ユーザ定義のデータ型の例としては、String の銘柄記号と integer の売買株式数という 2 つのフィールドを持つ TradeResult が挙げられます。
JWS ファイルで、1 つまたは複数のメソッドのパラメータまたは戻り値としてユーザ定義のデータ型を使用する場合は、データ型の Java コードを独自に作成して、JWS ファイルにそのクラスをインポートし、適切に使用する必要があります。必要なデータ バインディング アーティファクトはすべて、jwsc Ant タスクが後で作成します。
ユーザ定義のデータ型の Java コードを記述するときは、以下の基本的な要件に従います。
デフォルト コンストラクタを定義する。これは、パラメータを取らないコンストラクタです。
公開するメンバー変数ごとに getXXX() メソッドと setXXX() メソッドの両方を定義する。
公開される各メンバー変数のデータ型は、組み込みデータ型のいずれか、または組み込みデータ型で構成されるユーザ定義のデータ型にする。
|
注意 : カスタムマッピングを提供するには JAXB を使用することができます。詳細については、「JAXB アノテーションを使用した Java-to-XML スキーマ マッピングのカスタマイズ」を参照してください。 |
jwsc Ant タスクでは、最も一般的な XML および Java データ型のデータ バインディング アーティファクトを生成できます。サポートされるユーザ定義のデータ型のリストについては、「サポートされるユーザ定義のデータ型」を参照し、サポートされる組み込みデータ型の全リストについては、「サポートされる組み込みデータ型」を参照してください。
以下の例では、BasicStruct という簡単な Java ユーザ定義データ型を示します。
package examples.webservices.complex;
/**
* 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 アノテーション インタフェースをインポートする // BasicStruct JavaBean をインポートする import examples.webservices.complex.BasicStruct; @WebService(serviceName="ComplexService", name="ComplexPortType", targetNamespace="http://example.org") ... public class ComplexImpl { @WebMethod(operationName="echoComplexType") public BasicStruct echoStruct(BasicStruct struct) { return struct; } }
JWS ファイル内から別の Web サービス (WebLogic Server にデプロイされている Web サービス、または .NET などの他のアプリケーション サーバにデプロイされている Web サービス) を呼び出すことができます。その手順は、「スタンドアロンの Java クライアントからの Web サービスの呼び出し」で説明した手順と似ています。ただしこの場合は、clientgen Ant タスクを実行してクライアント スタブを生成するのではなく、呼び出し側の Web サービスを構築する jwsc Ant タスクに <clientgen> 子要素を含めてクライアント スタブを生成します。その後は、スタンドアロン クライアント アプリケーションの場合と同じように、JWS ファイル内で標準の JAX-WS API を使用します。
詳細な手順については、「別の Web サービスからの Web サービスの呼び出し」を参照してください。
WebLogic Web サービスでは、Web サービスとそのクライアントの間でデータや呼び出しを転送する際に、メッセージ フォーマットとしてデフォルトでバージョン 1.1 の SOAP (Simple Object Access Protocol) が使用されます。WebLogic Web サービスでは、SOAP 1.1 と新しい SOAP 1.2 の両バージョンがサポートされており、いずれかのバージョンを自由に使用できます。
Web サービスでバージョン 1.2 の SOAP を使用することを指定するには、JWS ファイルでクラス レベルの @javax.xml.ws.BindingTyp アノテーションを使用して、その唯一の属性の値を SOAPBinding.SOAP12HTTP_BINDING に設定します。次に例を示します (該当部分は太字で示してあります)。
package examples.webservices.soap12; import javax.jws.WebMethod; import javax.jws.WebService; import javax.xml.ws.BindingType; import javax.xml.ws.SOAPBinding; @WebService(name="SOAP12PortType", serviceName="SOAP12Service", targetNamespace="http://example.org") @BindingType(value = SOAPBinding.SOAP12HTTP_BINDING) /** * この 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 サービス ランタイムによってすべて自動的に処理されます。
デフォルトでは、SOAP メッセージは XML スキーマに対して検証されません。以降の節で説明するように、サーバまたはクライアントでドキュメントリテラル Web サービスに対して XML スキーマ検証を有効化することができます。
|
注意 : この機能により、Web サービス要求に対してわずかな処理が追加されます。 |
|
注意 : com.sun.xml.ws.developer.SchemaValidation API は、Sun Microsystems が提供する JDK 6.0 の拡張としてサポートされています。この API は JDK 6.0 キットの一部としては提供されないため、変更される可能性があります。詳細については、https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/SchemaValidation.html を参照してください。 |
サーバでスキーマ検証を有効化するには、エンドポイント実装で @SchemaValidation アノテーションを追加します。次に例を示します。
import com.sun.xml.ws.developer.SchemaValidation; import javax.jws.WebService; @SchemaValidation @WebService(name="HelloWorldPortType", serviceName="HelloWorldService") public class HelloWorldImpl { public String sayHelloWorld(String message) { System.out.println("sayHelloWorld:" + message); return "Here is the message: '" + message + "'"; } }
アプリケーション内のエラーを管理する場合、独自の検証エラー ハンドラ クラスを引数としてアノテーションに渡すことができます。次に例を示します。
@SchemaValidation(handler=ErrorHandler.class)
|
注意 : com.sun.xml.ws.developer.SchemaValidationFeature API は、Sun Microsystems が提供する JDK 6.0 の拡張としてサポートされています。この API は JDK 6.0 キットの一部としては提供されないため、変更される可能性があります。詳細については、https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/SchemaValidationFeature.html を参照してください。 |
クライアントでスキーマ検証を有効化するには、SchemaValidationFeature オブジェクトを作成し、PortType スタブ実装の作成時に引数として渡します。
package examples.webservices.hello_world.client; import com.sun.xml.ws.developer.SchemaValidationFeature; import javax.xml.namespace.QName; import java.net.MalformedURLException; import java.net.URL; public class Main { public static void main(String[] args) { HelloWorldService service; try { service = new HelloWorldService(new URL(args[0] + "?WSDL"), new QName("http://example.org", "HelloWorldService") ); } catch (MalformedURLException murl) { throw new RuntimeException(murl); } SchemaValidationFeature feature = new SchemaValidationFeature(); HelloWorldPortType port = service.getHelloWorldPortTypePort(feature); String result = null; result = port.sayHelloWorld("Hi there!"); System.out.println( "Got result: " + result ); } }
アプリケーション内のエラーを管理する場合、独自の検証エラー ハンドラを引数として SchemaValidationFeature オブジェクトに渡すことができます。次に例を示します。
SchemaValidationFeature feature = new SchemaValidationFeature(MyErrorHandler.class); HelloWorldPortType port = service.getHelloWorldPortTypePort(feature);
以下のリストでは、JWS ファイルをプログラミングする場合のベスト プラクティスを示します。
document-literal-bare の Web サービスを作成する場合は、@WebParam JWS アノテーションを使用して、特定の Web サービスのすべてのオペレーションのすべての入力パラメータにユニークな名前を付けるようにする。document-literal-bare の Web サービスの性質上、@WebParam アノテーションを使用して入力パラメータの名前を明示的に指定しない場合、WebLogic Server が入力パラメータの名前を作成するため、Web サービス内でパラメータの名前が重複するおそれがあります。
一般に、最も相互運用性の高いタイプの Web サービスは、document-literal-wrapped の Web サービスである。
ハードコード化された名前 return に常に依存するのではなく、@WebResult JWS アノテーションを使用して、オペレーションの戻り値の名前を明示的に設定する。JWS ファイルで @WebResult アノテーションを使用しない場合、return が戻り値のデフォルト名になります。
