Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS Webサービス・スタート・ガイド 11g リリース1 (10.3.6) B61645-05 |
|
前 |
次 |
この章では、Java API for XML-based Web services (JAX-WS)を使用したWebLogic Webサービスを実装するJWSファイルのプログラミング方法について説明します。
この章では、以下のトピックについて説明します。
WebLogic Webサービスをゼロからプログラムする方法は2つあります。
JSR-181、JAX-WS仕様、およびWebLogic Webサービス・プログラミング・モデルで規定されているように、標準のEJBまたはJavaクラスにWebサービスJavaアノテーションを付けます。
デプロイメント記述子、WSDLファイル、データ・マッピング記述子、データ・バインディング・アーティファクト(ユーザー定義のデータ型用)など、JSR-109で指定されている様々なXML記述子ファイルやアーティファクトと、標準のEJBまたはJavaクラスを結合します。
上のオプション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 WebLogic Server WebLogic 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 WebLogic Server WebLogic 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 WebLogic Server WebLogic Webサービス・リファレンス』のWebサービスのアノテーション・サポートに関する項を参照してください。 |
3 |
必須の標準 |
|
4 |
標準の |
特に、このアノテーションを使用して、Webサービスがドキュメント・リテラルか、ドキュメント・エンコードかなどを指定します。「WebサービスとSOAPメッセージ・プロトコルのマッピングの指定(@SOAPBindingアノテーション)」を参照してください。 このJWSアノテーションは必須ではありませんが、JWSファイルで明示的に指定し、クライアント・アプリケーションがWebサービスの呼出しに使用するSOAPバインディングのタイプを明確にすることをお薦めします。 |
5 |
クラス・レベルでJAX-WS |
|
6 |
パブリック操作として公開するJWSファイルの各メソッドで標準の |
必要に応じて、標準の |
7 |
|
|
8 |
|
|
9 |
独自のビジネス・コードを追加します。 |
Webサービスが希望どおりに動作するように、独自のビジネス・コードをメソッドに追加します。 |
次のサンプルJWSファイルでは、簡単なWebサービスの実装方法を示します。
package examples.webservices.simple; // Import the standard JWS annotation interfaces import javax.jws.WebMethod; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; // Standard JWS annotation that specifies that the porType name of the Web // Service is "SimplePortType", the service name is "SimpleService", and the // targetNamespace used in the generated WSDL is "http://example.org" @WebService(name="SimplePortType", serviceName="SimpleService", targetNamespace="http://example.org") // Standard JWS annotation that specifies the mapping of the service onto the // SOAP message protocol. In particular, it specifies that the SOAP messages // are document-literal-wrapped. @SOAPBinding(style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.WRAPPED) /** * This JWS file forms the basis of simple Java-class implemented WebLogic * Web Service with a single operation: sayHello * */ public class SimpleImpl { // Standard JWS annotation that specifies that the method should be exposed // as a public operation. Because the annotation does not include the // member-value "operationName", the public name of the operation is the // same as the method name: 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アノテーション(http://docs.oracle.com/javaee/5/api/javax/xml/ws/BindingType.html
)を参照してください。
クライアント・アプリケーションが、JWSファイルで実装されたWebLogic Webサービスを呼び出すと、WebLogic Serverは、Webサービスやクライアントが、サービスに関する実行時情報のアクセス、および場合によっては変更に使用できるコンテキストを自動的に作成します。
実行時情報には、以下のいずれかの方法でアクセスできます。
javax.xml.ws.BindingProvider
(http://download.oracle.com/javaee/5/api/javax/xml/ws/BindingProvider.html
)- クライアント・アプリケーションから、プロトコル・バインディングのリクエストおよびレスポンス・コンテキストへアクセスします。「プロトコル・バインディング・コンテキストへのアクセス」を参照してください。
javax.xml.ws.WebServiceContext
(http://download.oracle.com/javaee/5/api/javax/xml/ws/WebServiceContext.html
)- Webサービスから、処理されているリクエストに関連する実行時メッセージ・コンテキストやセキュリティ情報にアクセスします。WebServiceContext
は通常、@Resource
アノテーションを使用してエンドポイントにインジェクトされます。「Webサービス・コンテキストへのアクセス」を参照してください。
javax.xml.ws.handler.MessageContext
(http://download.oracle.com/javaee/5/api/javax/xml/ws/handler/MessageContext.html
)- WebサービスのWebServiceContext
から直接、あるいはクライアント・アプリケーションやWebサービスのメッセージ・ハンドラから実行時プロパティ・セットへアクセスします。「MessageContextプロパティ値の使用」を参照してください。
以降の項では、BindingProvider
、WebServiceContext
、およびMessageContext
を使用して実行時情報へアクセスする方法の詳細を説明します。
注意:
|
javax.xml.ws.BindingProvider
インタフェースを使用すると、クライアント・アプリケーションから、プロトコル・バインディングのリクエストおよびレスポンス・コンテキストへアクセスすることができます。詳細については、http://download.oracle.com/javaee/5/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; /** * This is a simple standalone client application that invokes the * the <code>sayHelloWorld</code> operation of the Simple Web service. */ 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 (http://jax-ws.java.net/nonav/jax-ws-20-fcs/arch/com/sun/xml/ws/developer/JAXWSProperties.html#CONNECT_TIMEOUT
)を参照してください。
BindingProviderProperties.REQUEST_TIMEOUT
プロパティを使用してリクエスト・タイムアウトを定義しています。設定可能なBindingProviderProperties
の完全なリストは、com.sun.xml.ws.client.BindingProviderProperties
のJavadoc (http://jax-ws.java.net/nonav/jax-ws-20-fcs/arch/com/sun/xml/ws/client/BindingProviderProperties.html#REQUEST_TIMEOUT
)を参照してください。
javax.xml.ws.WebServiceContext
インタフェースを使用すると、Webサービスから、処理されているリクエストに関連する実行時メッセージ・コンテキストやセキュリティ情報にアクセスできます。WebServiceContext
は通常、@Resource
アノテーションを使用してエンドポイントにインジェクトされます。詳細は、http://download.oracle.com/javaee/5/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") /** * Simple web service to show how to use the @Context annotation. */ 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ファイルで使用できるjavax.xml.ws.WebServiceContext
のメソッドの要約を示します。詳細は、http://download.oracle.com/javaee/5/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://download.oracle.com/javaee/5/api/javax/xml/ws/handler/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 WebLogic Server WebLogic Enterprise JavaBeansバージョン3.0のプログラミング』を参照してください。
JWSファイルにEJBを実装するには、次の手順に従います。
EJB 3.0アノテーションをインポートします。これらのアノテーションはすべてjavax.ejb
パッケージにあります。少なくとも、@Stateless
アノテーションはインポートする必要があります。JWSファイルにはEJBの形式および動作を指定する追加のEJBアノテーションを指定することもできます。詳細は、javax.ejb
Javadoc (http://download.oracle.com/javaee/5/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; /** * A transaction-awared stateless EJB-implemented JWS */ // Standard JWS annotation that specifies that the portName,serviceName and // target Namespace of the Web Service. @WebService( name = "Simple", portName = "SimpleEJBPort", serviceName = "SimpleEjbService", targetNamespace = "http://wls/samples") //Standard EJB annotation @Stateless public class SimpleEjbImpl { @Resource private WebServiceContext context; private String constructed = null; // The WebMethod annotation exposes the subsequent method as a public // operation on the Web Service. @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()
メソッドの両方を定義します。
公開される各メンバー変数のデータ型は、組込みデータ型のいずれか、または組込みデータ型で構成されるユーザー定義のデータ型にします。
jwsc
Antタスクでは、最も一般的なXMLおよびJavaデータ型のデータ・バインディング・アーティファクトを生成できます。サポートされるユーザー定義のデータ型のリストは、「サポートされるユーザー定義のデータ型」を参照してください。サポートされる組込みデータ型の完全なリストは、「サポートされる組込みデータ型」参照してください。
次の例では、BasicStruct
という簡単なユーザー定義のJavaデータ型を示します。
package examples.webservices.complex; /** * Defines a simple JavaBean called BasicStruct that has integer, String, * and String[] properties */ public class BasicStruct { // Properties private int intValue; private String stringValue; private String[] stringArray; // Getter and setter methods 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; // Import the standard JWS annotation interfaces import javax.jws.WebMethod; import javax.jws.WebParam; import javax.jws.WebResult; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; // Import the WebLogic-specific JWS annotation interface // Import the 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 SEアプリケーションからのWebサービスの呼出し」で説明した手順と似ています(ただしこの場合は、clientgen
Antタスクを実行してクライアント・スタブを生成するのではなく、呼出し側のWebサービスを構築するjwsc
Antタスクに<clientgen>
子要素を含めてクライアント・スタブを生成します)。その後は、Java SEクライアント・アプリケーションの場合と同じように、JWSファイル内で標準のJAX-WS APIを使用します。
詳細な手順については、「WebLogic 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) /** * This JWS file forms the basis of simple Java-class implemented WebLogic * Web Service with a single operation: sayHello. The class uses SOAP 1.2 * as its binding. * */ 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スキーマ検証を有効化することができます。SOAPメッセージが無効の場合は、SOAPフォルトが返されます。
注意: この機能により、Webサービス・リクエストに対してわずかな処理が追加されます。 デフォルトでは、SOAPフォルトの詳細にはスタック・トレースが含まれます。スタック・トレースの無効化については、『Oracle WebLogic Server JAX-WS Webサービスの高度な機能のプログラミング』のスタック・トレースの無効化に関する項を参照してください。 |
注意:
|
サーバーでスキーマ検証を有効化するには、エンドポイント実装で@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)
注意:
|
クライアントでスキーマ検証を有効化するには、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が戻り値のデフォルト名になります。