10g（10.1.3.1.0）
B31868-01
 目次 |
 索引 |
| Oracle Application Server Web Services開発者ガイド 10g（10.1.3.1.0） B31868-01 |
|
この章では、JavaクラスからWebサービスを短時間で開発するための注釈の使用方法を説明します。Webサービスは、トランスポート・メカニズムとしてHTTPまたはJMSを使用できます。注釈機能を使用できるのは、Javaクラスからのボトムアップ方式でWebサービスを開発する場合のみです。
この章の内容は、次のとおりです。
標準のJavaメカニズムでWebサービスを設計、開発およびデプロイするには、膨大な量の情報を提供する必要があります。たとえば、Javaクラスをベースにしたサービスをデプロイするためには、そのクラス自体、関連するサービス・エンドポイント・インタフェース、および場合によってはメタデータ・ファイルが必要になります。
Oracle Application Server Web Servicesは、J2SE 5.0 Webサービス注釈（Web Services Metadata for the Java Platform（JSR-181）仕様とも呼ばれます）をサポートしています。次のWebサイトから入手できるこの仕様では、Webサービスのプログラミングに使用する注釈付きJava構文が定義されています。
http://www.jcp.org/en/jsr/detail?id=181
J2SE 5.0 Webサービス注釈を使用するメリットとデメリットを次のリストに記載します。
J2SE 5.0 Webサービス注釈を使用するメリット
J2SE 5.0 Webサービス注釈のデメリット
注釈付きJava構文を使用するには、J2SE 5.0 JDKが必要になります。また、J2SE 5.0 JDKには、注釈の定義方法、構文、および新しい注釈の作成方法など、言語レベルでの注釈のサポートを記述したドキュメントが付属しています。J2SE 5.0 JDKは、次のWebサイトから入手できます。
http://java.sun.com/j2se/1.5.0/download.jsp
J2SE 5.0 JDKには、Javaメタデータ注釈という機能があり、固有のタグをJavaクラスに追加できます。これらのタグは、クラスのバイト・コードにコンパイルされ、サード・パーティの注釈プロセッサからアクセス可能になります。Web Services Metadata for the Java Platform仕様は、この機能をWebサービスのメタデータ・タグ用にまで拡張したものです。OracleAS Web Servicesはこの仕様をサポートしており、開発者は注釈を使用してWebサービス生成プロセスをカスタマイズできます。
OracleAS Web ServicesでWebサービス注釈を使用するには、J2SE 5.0 JDKのJVMが必要です。WebServicesAssemblerツールは、J2SE 5.0注釈が含まれるJavaクラスからWebサービスを生成できます。このツールをJ2SE 5.0 JDKのJVMで使用すると、assembleおよびgenWsdlコマンドが、指定されたJavaクラスの注釈を処理します。
EJB 3.0仕様は、EJB用のメタデータ・タグを追加できるように、Web Services Metadata for the Java Platform仕様を拡張したものです。この仕様は、Web Services Metadata for the Java Platformのタグをサポートしており、EJBをWebサービスとして公開できるようにします。EJB 3.0注釈は、EJBを含むEARファイルが動作中のOracle Application Serverにデプロイされたときに処理されます。セッションBeanで実装された、J2SE 5.0 JDK注釈付きのインタフェースがすべて処理されます。WebServicesAssemblerツールは、EJB 3.0注釈の処理には使用できない点に注意してください。
次の各項では、OracleAS Web Servicesでサポートされている注釈について説明します。
OracleAS Web Servicesでは、Web Services Metadata for the Java Platform仕様で記述されている注釈セットをすべて使用できます。表11-1は、これらの注釈の簡単な説明です。Web Services Metadata for the Java Platform仕様では、これらの注釈についてのさらに詳しい情報が提供されています。
また、表11-1には、@WebServiceRef注釈についての簡単な説明もあります。OracleAS Web Servicesでは、@WebServiceRef注釈を使用して、アプリケーション・クライアント・コンテナ内のバージョン3.0 EJB、サーブレットまたはJavaクラスから、Webサービス・エンドポイントを参照できます。また、@WebServiceRef注釈のサポートには、ejb-jar.xmlデプロイメント・ディスクリプタでのservice-refターゲットのインジェクションのサポートも含まれます。この注釈の詳細は、Java API for XML-based Web Services 2.0（JSR-224）仕様を参照してください。
http://www.jcp.org/en/jsr/detail?id=224
| J2SE 5.0 JDK注釈 | 説明 |
|---|---|
|
javax.jws.HandlerChain |
Webサービスと外部で定義されているハンドラ・チェーンを関連付けます。 |
|
javax.jws.Oneway |
特定のWebメソッドが入力メッセージのみを持ち、出力を持たないことを示します。 |
|
javax.jws.WebMethod |
メソッドがWebサービス操作として公開されることを示します。 |
|
javax.jws.WebParam |
Webサービスのメッセージ部分およびXML要素に対する個別のパラメータのマッピングをカスタマイズします。 |
|
javax.jws.WebResult |
WSDL部分およびXML部分に対する戻り値のマッピングをカスタマイズします。 |
|
javax.jws.WebService |
Webサービスを実装しているJavaクラス、またはWebサービス・インタフェースを定義しているJavaインタフェースを指定します。 |
|
javax.jws.soap.SOAPBinding |
SOAPメッセージ・プロトコルに対するWebサービスのマッピングを指定します。 |
|
javax.jws.soap.SOAPMessageHandlers |
Webサービスでビジネス・メソッドの前または後に実行するSOAPプロトコル・ハンドラのリストを指定します。 |
|
javax.xml.ws.WebServiceRef |
アプリケーション・クライアント・コンテナ内のバージョン3.0 EJB、JavaクラスまたはサーブレットからWebサービス・エンドポイントへの参照を宣言します。
|
Java API for XML-based Web Services 2.0（JSR-224）仕様では、使用して、アプリケーション・クライアント・コンテナ内のバージョン3.0 EJB、サーブレットまたはJavaクラスからWebサービス・エンドポイントを参照するための、@WebServiceRef注釈が定義されています。表11-2は、@WebServiceRef注釈で使用できるプロパティです。
次の各項では、OracleAS Web Servicesでの@WebServiceRef注釈の使用方法についてさらに詳しく説明します。
Javaクラスまたはバージョン3.0 EJBに存在する@WebServiceRefごとに、JAX-RPCマッピング・ファイルがデプロイされるアーカイブに含まれる必要があります。マッピング・ファイルの生成はWebServicesAssemblerが行いますが、Webサービスに対する適切な場所にマッピング・ファイルが存在することはユーザーが確認する必要があります。マッピング・ファイルが適切な場所にない場合は、手動でコピーする必要があります。
META-INFディレクトリのすぐ下に存在する必要があります。
WEB-INFディレクトリのすぐ下に存在する必要があります。
WebServicesAssemblerは、次の手順でマッピング・ファイルの名前を判別します。名前の割当てに成功するまで、この手順に従います。最後のステップが失敗すると、プロセス全体が失敗し、名前は割り当てられません。
@WebService注釈とserviceNameプロパティが指定されている場合は、デプロイ・システムは次の名前でマッピング・ファイルのロードを試みます。[@WebService.serviceName]Service-java-wsdl-mapping.xml
この例で、[@WebService.serviceName]はserviceNameプロパティの値を表しています。
@WebServiceRef注釈とserviceNameプロパティが指定されている場合は、デプロイ・システムは次の名前でマッピング・ファイルのロードを試みます。[@WebServiceRef.name]Service-java-wsdl-mapping.xml
この例で、[@WebServiceRef.name]はnameプロパティの値を表します。
@WebServiceRef注釈とwsdlLocationプロパティが指定されている場合は、マッピング・ファイルのベース名は、wsdlLocationプロパティで参照されているWSDLファイルと同じです。 [base name of WSDL file]Service-java-wsdl-mapping.xml
たとえば、WSDLファイルがMyService.wsdlという名前である場合、そのサービスに対するマッピング・ファイルはMyServiceService-java-wsdl-mapping.xmlである必要があります。これは、genWSDLコマンドまたはgenInterfaceコマンドを実行するとWebServicesAssemblerが生成する名前と整合しています。したがって、WebServicesAssemblerが生成するマッピング・ファイルをコピーすると、必然的に動作するはずです。
Java API for XML-based Web Services 2.0仕様によると、@WebServiceRefに対して指定されているWSDLが複数のポートを備えている場合は、その注釈に対するインジェクション・ターゲットはjavax.xml.rpc.Service型である必要があります。サービスがこのターゲットにインジェクトされると、getPort(QName portName, Class serviceEndpointInterface)をコールして、呼出し用に正確なポートを取得できます。このシグネチャでは、portNameは使用する特定のポートの名前であり、serviceEndpointInterfaceはサービス・エンドポイント・インタフェース・クラス・ファイルの名前です。
ここでは、@WebServiceRef注釈の使用例を示します。
例11-1では、サービス・エンドポイント・インタフェースに対する参照はフィールドにインジェクトされ、さらにsetterメソッドにインジェクトされています。この場合、マッピング・ファイルの名前はSimpleService-java-wsdl-mapping.xmlです。
@Stateless(name="WSRefBean") public class StatelessEJBClient implements StatelessEJBClientInterface{ @WebServiceRef(name="Simple",wsdlLocation="META-INF/SimpleEJBServiceService.wsdl") private SimpleEJBService svc; private SimpleEJBService svc2; public String echoString(String str) throws RemoteException { if(svc == null){ return "fail1"; } if(svc2 == null){ return "fail2"; } String test = svc.echoString("Success"); test = svc2.echoString(test); return str + test; } @WebServiceRef(name="Simple",wsdlLocation="META-INF/SimpleEJBServiceService.wsdl") public void setSvc2(SimpleEJBService service){ svc2 = service; } }
例11-2は前の例とよく似ています。唯一違うところは、インジェクションが、実際のサービス・エンドポイント・インタフェースではなくjavax.xml.Serviceオブジェクトに対して行われていることです。前に説明したように、wsdlLocationに基づいて、マッピング・ファイルは（EJBなので）META-INFに存在することが予想され、名前はSimpleService-java-wsdl-mapping.xmlである必要があります。
@Stateless(name="WSRefBean3") public class StatelessEJBClient3 implements StatelessEJBClientInterface3{ @WebServiceRef(name="Simple",wsdlLocation="META-INF/SimpleEJBServiceService.wsdl") private Service svc; public String echoString(String test) throws RemoteException { if(svc == null){ return "fail"; } try{ SimpleEJBService port = (SimpleEJBService)svc.getPort(SimpleEJBService.class); return port.echoString(test); }catch(Exception ex){ ex.printStackTrace(); throw new RemoteException(ex.getMessage(),ex); } } }
例11-3では、インジェクションにejb-jar.xmlデプロイメント・ディスクリプタを使用します。この技法を使用するときは、ejb-jar.xmlでversion="3.0"を指定する必要があります。このデプロイメント・ディスクリプタは、@WebServiceRefと組み合せて使用できます。
インジェクションにejb-jar.xmlデプロイメント・ディスクリプタを使用するときは、<jaxrpc-mapping-file>要素でマッピング・ファイルを直接指定することもできます。この場合、マッピング・ファイルの名前はCustomSessionBeanService-java-wsdl-mapping.xmlです。
<ejb-jar version="3.0"> <enterprise-beans> <session> <ejb-name>WSRefBean2</ejb-name> <ejb-class>oracle.j2ee.tests.ejb.impl.StatelessEJBClient2</ejb-class> <session-type>Stateless</session-type> <service-ref> <service-ref-name>CustomSessionEJB</service-ref-name> <service-interface>javax.xml.rpc.Service</service-interface> <service-ref-type>oracle.j2ee.tests.ejb.impl.CustomSession</service-ref-type> <wsdl-file>META-INF/CustomSessionBeanService.wsdl</wsdl-file> <jaxrpc-mapping-file>META-INF/CustomSessionBeanService-java-wsdl-mapping.xml</jaxrpc-ma pping-file> <injection-target> <injection-target-class>oracle.j2ee.tests.ejb.impl.StatelessEJBClient2</injection-targe t-class> <injection-target-name>svc</injection-target-name> </injection-target> </service-ref> </session> </enterprise-beans> </ejb-jar>
この項では、J2SE 5.0 JDKのJavaメタデータ注釈機能で読取りおよび処理が可能なOracle固有の注釈を説明します。
@Deployment注釈（oracle.webservices.annotations.Deployment）は、エンドポイント実装またはサービス・エンドポイント・インタフェースにデプロイ属性を設定するために使用します。
表11-3は、@Deployment注釈のプロパティの説明です。すべてのプロパティはオプションです。
|
注意 次の表のプロパティは、デプロイメント・ディスクリプタによって、またはWebServicesAssemblerで渡される引数値によって、オーバーライドされる可能性があります。詳細は、「WebServicesAssemblerで注釈値をオーバーライドする方法」を参照してください。 |
次に、@Deployment注釈を使用するインタフェースの例を示します。この例のWebサービスは、デプロイされてから、URL http://$HOST:$PORT/ejb30/ejb30-simpleによってアクセスできるようになります。
... @WebService(name="CustomSession", targetNamespace="http://ejb.oracle.com/targetNamespace", serviceName="CustomSessionBeanService") @Deployment(contextPath="ejb30", uriPath="ejb30-simple", portName="Custom") public interface CustomSessionIntf extends Remote{ ...
@Schema注釈（oracle.webservices.annotations.Schema）を使用すると、WSDLでのスキーマ要素の生成方法を構成できます。これはオプションの注釈で、オプションのプロパティelementFormDefaultとtargetNamespaceのみを持ちます。
elementFormDefaultプロパティを使用すると、WSDLのelementFormDefault属性の値を変更できます。この属性の値は、ローカルに宣言されている要素を、インスタンス・ドキュメント内ではターゲット名前空間で修飾する必要があるかどうかを示します。この属性の値がunqualifiedである場合は、ローカルに宣言された要素をターゲット名前空間で修飾することはできません。この属性の値がqualifiedである場合は、ローカルに宣言された要素をターゲット名前空間で修飾する必要があります。
@Schema.elementFormDefaultプロパティは、@Schema.ElementFormDefault.QUALIFIEDと@Schema.ElementFormDefault.UNQUALIFIEDという2つの値を持つ列挙です。デフォルトでは、OracleAS Web Servicesツールは、WSDL内のすべてのスキーマのelementFormDefault属性をqualifiedに設定します。@Schema.elementFormDefaultプロパティを使用することで、この動作を変更できます。
targetNamespaceプロパティを使用すると、生成されるスキーマのtargetNamespace属性を設定できます。この名前空間は、すべての型に対するデフォルトになります。
表11-4は、@Schema注釈のプロパティをまとめたものです。
|
注意 次の表のプロパティは、デプロイメント・ディスクリプタによって、またはWebServicesAssemblerで渡される引数値によって、オーバーライドされる可能性があります。詳細は、「WebServicesAssemblerで注釈値をオーバーライドする方法」を参照してください。 |
@WSIFEJBBinding注釈（oracle.webservices.annotations.@WSIFEJBBinding）は、バージョン3.0 EJB用のWSDLにWeb Services Invocation Framework（WSIF）のバインディングを生成します。WSIFバインディングは、単一のポートに対してのみ適用されます。この注釈および関連するプロパティは、WSDLに拡張機能を追加し、Webサービスとして公開された3.0 EJBにWSIFクライアントがアクセスできるようにします。
表11-5は、@WSIFEJBBinding注釈に対して指定できるプロパティです。classNameプロパティとjndiNameプロパティは必須です。
|
注意 次の表のプロパティは、デプロイメント・ディスクリプタによって、またはWebServicesAssemblerで渡される引数値によって、オーバーライドされる可能性があります。詳細は、「WebServicesAssemblerで注釈値をオーバーライドする方法」を参照してください。 |
次の例は、バージョン3.0 EJBに対するインタフェース・ファイルで使用されている@WSIFEJBBinding注釈を示しています。
... @WebService(name="Hello", targetNamespace="http://ejb.oracle.com/targetNamespace", serviceName="CustomHelloBeanService") @WSIFEJBBinding( className="oracle.demo.hello.HelloBean", jndiName="Hello", initialContextFactory="com.evermind.server.rmi.RMIInitialContextFactory", jndiProviderUrl="ormi://localhost:23791/ejb30wsif") public interface CustomHelloBeanIntf extends Remote { ...
ファイルをコンパイルすると、WSDLでのEJB WSIFバインディングと、次の値を持つEJBポートが生成されます。
... <port name="WsifEJBPort" binding="tns:WsifEjbBinding"> <ejb:address className="oracle.demo.hello.HelloBean" jndiName="Hello" initialContextFactory="com.evermind.server.rmi.RMIInitialContextFactory" jndiProviderURL="ormi://localhost:23791/ejb30wsif"/> </port> ...
この項の内容は、次のとおりです。
J2SE 5.0注釈付きのJavaクラスからWebサービスを生成する手順は、次のとおりです。
例11-4は、注釈付きのJavaファイルのサンプルです。
@WebService注釈がクラス内に存在する必要があります。
@WebService注釈にendpointInterfaceプロパティを追加します。サービス・エンドポイント・インタフェースにも@WebService注釈がある場合は、各注釈はこちらの開始ポイントで処理されるようになります。
@WebMethodの注釈を、Webサービスで公開する各メソッドに追加します。サービス・エンドポイント・インタフェースに注釈を追加すると、そのすべてのメソッドが@WebMethod注釈の有無に関係なく公開される点に注意してください。 クラスはJDK 5.0対応のコンパイラでコンパイルする必要があります。
assembleコマンドを使用して、Webサービス・アーチファクト（WSDL、デプロイ・ディスクリプタなど）を生成します。
Webサービスは、デプロイ時にEJB 3.0準拠のBeanからアセンブルできます。Webサービス・エンドポイントをEJB 3.0 Beanから生成する手順は、次のとおりです。
@Stateless注釈をBeanに追加します。ステートレスEJBセッションBeanのみがサポートされています。
@Stateless注釈のnameプロパティに、Webサービス・エンドポイントの名前を指定します。このプロパティを指定しない場合、デフォルトのエンドポイント名は、EJB Beanクラスの非修飾クラス名になります。
@WebService注釈を追加します。
@Deployment注釈を、uriPathおよびportNameプロパティに値を指定して、インタフェースに追加します。 EJB 3.0 Beanのポート名およびデフォルトURIが、デフォルトのEJB名になります。この名前がBeanの@Stateless注釈に設定されます。Bean名が@Stateless注釈に指定されていない場合は、かわりにBeanのこの短縮クラス名が使用されます。@Deployment注釈のuriPathおよびportNameプロパティに値を指定することで、この指定をオーバーライドできます。
この項では、デプロイメント・ディスクリプタまたはWebServicesAssemblerを使用した、Javaファイルの注釈値のオーバーライド方法を説明します。
WebServicesAssemblerのassembleおよびgenWsdlコマンドにコマンドライン引数を渡すことで、同じ機能を実行するJavaクラス・ファイルの注釈をオーバーライドできます。たとえば、portName引数をassembleまたはgenWsdlコマンドに渡すと、渡した値が@Deployment.portName注釈の値をオーバーライドします。
Oracle固有の@Deployment注釈で指定されたプロパティをオーバーライドするには、META-INF/oracle-webservices.xml（Webモジュールの場合はWEB-INF/oracle-webservices.xml）のEARファイルに、オーバーライドする値を指定するデプロイメント・ディスクリプタをパッケージします。
oracle-webservices.xmlデプロイメント・ディスクリプタを使用して、@Deployment注釈プロパティをオーバーライドする場合は、ディスクリプタの各<webservice-description>要素が、WebサービスのserviceNameをベースにしてデプロイされるWebサービスと一致する必要があります。serviceNameは、@WebService.serviceName注釈で指定します。
@Deployment注釈を使用する複数のWebサービスをアセンブルしようとしており、ただ1つのサービスのプロパティをオーバーライドするデプロイメント・ディスクリプタを指定する場合は、その他のサービスは影響を受けません。デプロイメント・ディスクリプタには、オーバーライドするプロパティのみを指定します。
たとえば、次にあげるoracle-webservices.xmlデプロイメント・ディスクリプタからのXMLフラグメントの値は、@Deployment注釈のプロパティをオーバーライドします。このフラグメントでは、<port-component name>属性および<endpoint-address-uri>要素に対して値を指定しているため、注釈のportNameおよびuriPathプロパティがオーバーライドされます。<context-root>要素はこの例では指定されていないため、注釈のcontextPathプロパティはオーバーライドされません。
<webservice-description name="CustomSessionBeanService"> <port-component name="CustomSession"> <endpoint-address-uri>/custom-session</endpoint-address-uri> </port-component> </webservice>
もちろん、クラスに注釈を付けるかわりにoracle-webservices.xmlデプロイメント・ディスクリプタのみを使用してデプロイメント・プロパティを指定することも可能です。
JavaクラスからWebサービスを生成する際、J2SE 5.0注釈を次のいずれかに入力できます。
注釈をエンドポイント・クラスおよびサービス・エンドポイント・インタフェースの両方に入力する場合は、エンドポイント・クラスには最小限の注釈のみを入力する必要があります。
例11-4に、Webサービス・メタデータ注釈付きの実装クラスを示します。この例の中で@WebService、@WebMethodおよび@WebParamの各注釈がどのように使用されているかに注目してください。
@WebService注釈を使用すると、serviceNameおよびtargetNamespaceプロパティに値を指定できます。これらのプロパティは、生成されるWSDLファイル内のwsdl:service nameおよびwsdl:targetNamespace要素に値を移入するために使用されます。targetNamespaceプロパティは、WSDLおよびスキーマ型に対するデフォルトの名前空間を提供します。
オプションとして、サービス・エンドポイント・インタフェースの完全修飾クラス名を使用して、endpointInterfaceプロパティを指定できます。この場合、次の注釈を追加します。
@WebMethod注釈は、Webサービスとしてアセンブルするメソッドを指定します。注釈が付けられたこれらのメソッドは、生成されるWSDL内のwsdl:operation要素にアセンブルされます。operationNameプロパティの値は、@WebMethod注釈に指定されている場合、wsdl:operationの操作名として使用されます。値が指定されていない場合は、メソッドの名前がデフォルトで使用されます。
@WebParam注釈は、wsdl:operationsに対するメッセージ部分またはメッセージ・パラメータを指定します。Modeを、オプションとして各パラメータに指定できます。INOUTまたはOUTモードは、javax.xml.rpc.holders.Holderインタフェースを実装するパラメータに対してのみ指定できます。Holderインタフェースを実装するパラメータは、Mode.OUTが注釈で明示的に指定されていない場合、デフォルトとしてINOUTパラメータになります。それ以外のパラメータは、すべてINパラメータとして使用する必要があります。package oracle.webservices.examples.annotations; import java.rmi.RemoteException; import javax.jws.*; import javax.jws.WebParam.Mode; @WebService ( serviceName = "annotatedBank", targetNamespace = "http://service.annotatedBank" ) public class BankServiceImpl { @WebMethod (operationName="create-account") public String createAccount( @WebParam(name="accountName") String acctName, float initBalance ) throws RemoteException, AccountException { return m_bank.addNewAccount(acctName,initBalance); } @WebMethod public void deposit( @WebParam(name="accountID", mode=Mode.IN) String acctID, float amount ) throws RemoteException, AccountException { Account theAccount = m_bank.getAccount(acctID); if ( theAccount == null ) { throw new AccountException("No account found for " + acctID); } theAccount.deposit(amount); } //class truncated… }
「注釈を使用したWebサービスのアセンブル」を参照してください。
詳細は、次を参照してください。
|
 Copyright © 2006 Oracle Corporation. All Rights Reserved. |
|