10g（10.1.3.1.0）
B31868-01
 目次 |
 索引 |
| Oracle Application Server Web Services開発者ガイド 10g（10.1.3.1.0） B31868-01 |
|
この章では、Oracle Application Server Web ServicesがREST Webサービスの生成と使用をサポートする方法を説明します。この章の内容は、次のとおりです。
REST（Representational State Transfer）Webサービス・アーキテクチャは、World Wide Web Consortium（W3C）が策定したWebアーキテクチャに準拠し、そのアーキテクチャの理念を使用したものです。HTTPのセマンティクスを可能なかぎり使用します。REST Webサービスはメッセージの送信にXML文書を使用し、SOAPエンベロープは使用しません。SOAP Webサービスとは異なり、RESTはスタイルであるため、標準やベンダーによるツールのサポートはありません。
Oracle Application Server Web Servicesを使用し、RESTを使用してエンドポイントを公開すると、そのエンドポイントはSOAPポートとしても公開されます。OracleAS Web Servicesは、HTTPコマンドのサポートをGETおよびPOSTに制限しています。REST Webサービスは、他のOracleAS Web Servicesと同様にデプロイします。
セキュリティおよび信頼性などのWebサービス管理機能は、REST Webサービスの起動（RESTまたはSOAP）では使用できません。これは、通常この情報の保持に使用するSOAPヘッダーが、REST Webサービスの呼出しでは使用できないためです。
この項の内容は、次のとおりです。
WebServicesAssemblerを使用して、REST Webサービスの機能を、HTTPをプロトコルとして使用できるWebアプリケーションに追加できます。これには、Javaクラス、EJBおよびデータベース・リソースに基づいて作成されるWebサービス・アプリケーションがあります。WebServicesAssemblerのブール型引数restSupportを使用すると、次のいずれかのコマンドでREST Webサービスをアセンブルできます。
Oracle固有の@Deployment注釈には、オプションのブール型属性restSupportを適用できます。属性の値がtrueの場合は、注釈が適用されたポートは、RESTスタイルのGETおよびPOSTのリクエストおよびレスポンスをサポートします。
この項の内容は、次のとおりです。
次の手順は、WSDLからのREST Webサービスのアセンブル方法を例で示しています。この例では、トップダウン方式によるWebサービスのアセンブルに必要な手順のアウトラインのみを示しています。
genInterfaceコマンドへの入力として指定します。 この例で使用されるWSDLを例12-1に示します。次は、genInterfaceコマンドのサンプルです。
java -jar wsa.jar -genInterface -output build/src/service -wsdl wsdl/MovieFacility.wsdl -unwrapParameters false
このコマンドの説明:
genInterface: 各ポート・タイプのサービス・エンドポイント・インタフェースと、WSDLに定義された複合型に対応するJava値タイプ・クラス（Bean）を作成します。また、XMLスキーマ型とJava値タイプ・クラス間のマッピングを記述するJAX-RPCマッピング・ファイルも作成されます。「genInterface」を参照してください。
output: 生成されるファイルを格納するディレクトリを指定します。そのディレクトリが存在しない場合は、作成します。「output」を参照してください。
wsdl: WSDLドキュメントの絶対ファイル・パス、相対ファイル・パスまたはURLを指定します。「wsdl」を参照してください。
unwrapParameters: この引数はdocument-literal操作に対してのみ設定でき、その他のメッセージ書式では無視されます。falseに設定すると、生成対象のサービス・エンドポイント・インタフェースが、入力パラメータおよび戻り型をラップするラッパーとともに生成されます。「unwrapParameters」を参照してください。
topDownAssembleコマンドを実行し、サービスを生成します。 restSupport引数をtrueに設定します。次に例を示します。
java -jar wsa.jar -topDownAssemble -wsdl ./wsdl/MovieFacility.wsdl -unwrapParameters false -className oracle.webservices.examples.rest.RpcLitMovieImpl -input build/classes/service -output build -ear dist/rpclit_topdown.ear -restSupport true
このコマンドの説明:
topDownAssemble: WSDL記述をベースにしたWebサービスで必要となるクラスとデプロイメント・ディスクリプタを作成します。これらのファイルは、EARファイル、WARファイル、ディレクトリのいずれにも格納できます。「topDownAssemble」を参照してください。
wsdl: WSDLドキュメントの絶対ファイル・パス、相対ファイル・パスまたはURLを指定します。「wsdl」を参照してください。
unwrapParameters: この引数はdocument-literal操作に対してのみ設定でき、その他のメッセージ書式では無視されます。falseに設定すると、生成対象のサービス・エンドポイント・インタフェースが、入力パラメータおよび戻り型をラップするラッパーとともに生成されます。「unwrapParameters」を参照してください。
className: Webサービスの実装クラスのクラス名（パッケージ名を含む）を指定します。「className」を参照してください。
input: WEB-INF/classesにコピーされるクラスを格納するJARまたはディレクトリを指定します。この引数は、WebServicesAssemblerによって使用されるクラスパスに追加されます。「input」を参照してください。
output: 生成されるファイルを格納するディレクトリを指定します。そのディレクトリが存在しない場合は、作成します。「output」を参照してください。
ear: 生成されるEARファイルの名前と位置を指定します。「ear」を参照してください。
restSupport: Representational State Transfer（REST）のサポートをこのWebサービスに対して有効にするかどうかを指定します。「restSupport」を参照してください。
通常の方法でEARファイルをOC4Jの実行中インスタンスにデプロイします。EARファイルのデプロイの詳細は、『Oracle Containers for J2EEデプロイメント・ガイド』を参照してください。
OracleAS Web Servicesでは、デプロイされたWebサービスごとにWebサービス・テスト・ページが提供されます。テスト・ページを使用すると、REST POSTまたはGETリクエストを生成して起動できます。Webサービス・テスト・ページへのアクセスおよびその使用方法の詳細は、「Webサービス・テスト・ページの使用方法」を参照してください。
例12-1は、「トップダウン方式でのREST Webサービスのアセンブル手順」でprc-literalサービスのアセンブルに使用されたWSDLフラグメントです。
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns0="http://www.oracle.com/rest/doc/types" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://www.oracle.com/rest" name="rest-service" targetNamespace="http://www.oracle.com/rest" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"> <types> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://www.oracle.com/rest/doc/types" elementFormDefault="qualified" targetNamespace="http://www.oracle.com/rest/doc/types"> <complexType name="Movie"> <sequence> <element name="Title" type="xsd:string"/> <element name="Director" type="xsd:string"/> <element name="Year" type="xsd:int" /> </sequence> </complexType> <complexType name="ArrayOfMovie"> <sequence> <element name="Movie" type="tns:Movie" maxOccurs="unbounded" /> </sequence> </complexType> </schema> </types> <message name="FindMoviesRequest"> <part name="TitleWords" type="xsd:string" /> <part name="Year" type="xsd:int" /> </message> <message name="FindMoviesResponse"> <part name="Movies" type="tns0:ArrayOfMovie" /> </message> <message name="AddMovieRequest"> <part name="Movie" type="tns0:Movie" /> </message> <message name="AddMovieResponse"> <part name="Added" type="xsd:boolean" /> </message> <portType name="MovieDB"> <operation name="findMovies"> <input message="tns:FindMoviesRequest" /> <output message="tns:FindMoviesResponse" /> </operation> <operation name="addMovie"> <input message="tns:AddMovieRequest" /> <output message="tns:AddMovieResponse" /> </operation> </portType> <binding name="HttpSoap11Binding" type="tns:MovieDB"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="findMovies"> <soap:operation soapAction="http://www.oracle.com/rest/findMovies"/> <input> <soap:body use="literal" parts="TitleWords Year" namespace="http://www.oracle.com/rest"/> </input> <output> <soap:body use="literal" parts="Movies" namespace="http://www.oracle.com/rest"/> </output> </operation> <operation name="addMovie"> <soap:operation soapAction="http://www.oracle.com/rest/addMovie"/> <input> <soap:body use="literal" parts="Movie" namespace="http://www.oracle.com/rest"/> </input> <output> <soap:body use="literal" parts="Added" namespace="http://www.oracle.com/rest"/> </output> </operation> </binding> <service name="rest-service"> <port name="HttpSoap11" binding="tns:HttpSoap11Binding"> <soap:address location="http://localhost:8888/webservice/webservice/"/> </port> </service> </definitions>
前述のWSDLを使用し、「トップダウン方式でのREST Webサービスのアセンブル手順」に記載の手順を実行することで、次のようなインタフェースが生成されます。
interface MovieDb { public Movie[] findMovies (String titleWords, int year); public boolean addMovie (Movie movie); }
生成されたインタフェース内の最初のメソッドは、単純なパラメータのみを持ちます。このメソッドは、HTTP GETを使用して起動できます。次に例を示します。
http://{yourhost}/{context-path}/{service-url}/findMovies?TitleWords=Star+Wars&Year=1977
この問合せ文字列は、次のXMLレスポンスを返します。
<ns0:findMoviesResponse xmlns:ns0="http://www.oracle.com/rest"> <Movies> <ns1:Movie xmlns:ns1="http://www.oracle.com/rest/doc/types"> <ns1:Title>tim</ns1:Title> <ns1:Director>tim</ns1:Director> <ns1:Year>1978</ns1:Year> </ns1:Movie> </Movies> </ns0:findMoviesResponse>
生成されたインタフェース内のaddMovieメソッドは、複雑なパラメータを取るため、HTTP POSTによってのみ起動できます。たとえば、次のXMLメッセージを独自のWebサービスのURL、http://{yourhost}/{context-path}/{service-url}に対してPOSTできます。
<ns0:addMovie xmlns:ns0="http://www.oracle.com/rest"> <Movies> <ns1:Movie xmlns:ns1="http://www.oracle.com/rest/doc/types"> <ns1:Title>tim</ns1:Title> <ns1:Director>tim</ns1:Director> <ns1:Year>1978</ns1:Year> </ns1:Movie> </Movies> </ns0:addMovie>
次の手順は、JavaクラスからのREST Webサービスのアセンブル方法を例で示しています。この例では、ボトムアップ方式によるWebサービスのアセンブルに必要な手順のアウトラインのみを示しています。
例12-2は、この例で使用しているStringToolsインタフェースです。
restSupport引数をtrueにしたassembleコマンドを指定して、サービスのアーチファクトを生成します。
java -jar wsa.jar -assemble -appName tools -serviceName StringTools -interfaceName oracle.webservices.examples.rest.StringTools -className oracle.webservices.examples.StringToolsImpl -input ./build/classes/service -output build -use literal -ear dist/tools.ear -uri StringToolsService -restSupport true
このコマンドの説明:
assemble: ボトムアップ方式でJavaファイルからWebサービスを生成します。このコマンドにより、デプロイ可能なアーカイブを作成するために必要なすべてのファイルが作成されます。「assemble」を参照してください。
appName: アプリケーションの名前を指定します。この名前は、通常contextやuriなどの他の引数のベース値として使用されます。「appName」を参照してください。
serviceName: サービス名を指定します。「serviceName」を参照してください。
interfaceName: サービス・エンドポイント・インタフェース（SEI）を格納するJavaクラスの名前（パッケージ名を含む）を指定します。「interfaceName」を参照してください。
className: Webサービスの実装クラスのクラス名（パッケージ名を含む）を指定します。「className」を参照してください。
input: WEB-INF/classesにコピーされるクラスを格納するJARまたはディレクトリを指定します。この引数は、WebServicesAssemblerによって使用されるクラスパスに追加されます。「input」を参照してください。
output: 生成されるファイルを格納するディレクトリを指定します。そのディレクトリが存在しない場合は、作成します。「output」を参照してください。
use: ボトムアップ方式Webサービス・アセンブリの場合、この引数は、生成されるWSDL内のメッセージ書式のuse属性を指定します。「use」を参照してください。
ear: 生成されるEARファイルの名前と位置を指定します。「ear」を参照してください。
uri: Webサービスに使用するURIを指定します。「uri」を参照してください。
restSupport: Representational State Transfer（REST）のサポートをこのWebサービスに対して有効にするかどうかを指定します。「restSupport」を参照してください。
通常の方法でEARファイルをOC4Jの実行中インスタンスにデプロイします。EARファイルのデプロイの詳細は、『Oracle Containers for J2EEデプロイメント・ガイド』を参照してください。
テスト・ページを使用すると、REST POSTまたはGETリクエストを生成して起動できます。Webサービス・テスト・ページへのアクセスおよびその使用方法の詳細は、「Webサービス・テスト・ページの使用方法」を参照してください。
例12-2は、前述のステップ2でREST Webサービスのアセンブルに使用されていたStringToolsインタフェースです。
interface StringTools { package oracle.webservices.examples.rest; import java.rmi.Remote; import java.rmi.RemoteException; public interface StringTools extends Remote{ public String appendStrings (String a, String b) throws RemoteException; public String toUpperCase (String c) throws RemoteException; public String concatArrayOfStrings (String s[]) throws RemoteException;
このインタフェースの最初の2つのメソッド、appendStringsおよびtoUpperCaseは、単純なパラメータを使用しています。このため、これらは、REST Webサービス操作として公開すると、HTTP GETを使用してアクセスできます。次の例は、アセンブリ時にdocumentスタイルを指定した場合の、appendStrings操作のコールを示します。
http://{yourserver}/{context-path}/{service-URL}/appendStrings?String_1=Hello+&String_2 =World
この問合せ文字列は、次のXMLレスポンスを返します。
<appendStringsResponseElement xmlns="http://oracle.webservices.examples.rest/"> <result>Hello World</result> </appendStringsResponseElement>
このインタフェース内の3番目のメソッドconcatArrayOfStringsは、複雑なパラメータを取ります。このため、これは、REST Webサービス操作として公開しても、HTTP GETではコールできません。HTTP POSTによってのみ、コールできます。次に例を示します。
<ns1:concatArrayOfStringsElementxmlns:ns1="http://oracle.webservices.examples.rest/"> <ns1:arrayOfString_1>a,</ns1:arrayOfString_1> <ns1:arrayOfString_1>b.</ns1:arrayOfString_1> </ns1:concatArrayOfStringsElement> <concatArrayOfStringsRequest xmlns="http://oracle.webservices.examples.rest/">
このリクエスト文字列は、次のXMLコードを返します。
<ns0:concatArrayOfStringsResponseElement xmlns:ns0="http://oracle.webservices.examples.rest/"> <ns0:result>a,b.</ns0:result> </ns0:concatArrayOfStringsResponseElement>
Webサービス・テスト・ページを使用して、REST Webサービスが正常にデプロイされたかどうかをテストできます。
RESTサポートがWebサービスに対して有効になっている場合は、オプションのブール型<rest-support>サブ要素が、oracle-webservices.xmlデプロイメント・ディスクリプタの<port-component>要素に追加されます。<rest-support>がtrueに設定されると、サブ要素が適用されるポートは、RESTスタイルのGETおよびPOSTのリクエストおよびレスポンスをサポートします。デフォルト値はfalseです。
次の各項では、REST Webサービス・リクエストのクライアント・サイドでの構築方法、およびサーバー・サイドでの処理方法を説明します。
SOAPエンドポイントが次のURLにデプロイされていると仮定します。
http://example.com/my-app/my-service
このエンドポイントがREST対応の場合は、次のURLへのHTTP GETリクエストが受け入れられます。
http://example.com/my-app/my-service/{operationName}?{param1}={value1}&{param2}={value2}
この例において、{operationName}はサービスに対するWSDL内の操作名の1つです。RPC-literal操作の場合は、{param1}、{param2}などが、操作の入力であるwsdl:message内で定義される各部分の名前になります。ただし、これらの各部分はsimpleTypes（xsd:intなど）である必要があります。
document-literal操作では、メッセージはパラメータを1つのみ持ちます。複数パラメータをシミュレートするため、WSDLには、スキーマでsequenceとして定義されているパラメータを指定します。sequenceの各メンバーをパラメータと考えることができます。この場合、{param1}、{param2}などが、message部分ではなくsequence型のメンバーになります。RPCの場合と同様に、これらのメンバーはsimpleTypesである必要があります。
例12-3は、addNumbersという名前の操作に対して定義されたリクエスト・メッセージです。
<wsdl:message name="AddNumbersRequest"> <wsdl:part name="a" type="xsd:int" /> <wsdl:part name="b" type="xsd:int" /> </wsdl:Message>
このリクエストは、次のURLを指定したGETで起動できます。
http://{yourhost}/{context-path}/{service-url}/addNumbers?a=23&b=24
例12-4は、OracleAS Web ServicesプラットフォームがGETリクエストからサーバー・サイドで作成するSOAPエンベロープを示します。このメッセージは、他の受信SOAPリクエストと同様に処理されます。
<soap:Envelope> <soap:Body> <ns:addNumbers> <ns:a>23</ns:a> <ns:b>24</ns:b> </ns:addNumbers> <soap:Body> <soap:Envelope>
例12-5は、addNumbersサービスがdocument-literal操作として定義されている場合に送信されるリクエスト・メッセージです。
<wsdl:message name="AddNumbersRequest"> <wsdl:part name="params" type="tns:AddNumbersRequstObject" /> </wsdl:Message>
例12-6は、AddNumbersRequestObjectの定義を示しています。これはスキーマでも同じ定義になります。
<xsd:complexType name="AddNumbersRequestObject"> <xsd:complexContent> <xsd:sequence> <xsd:element name="a" type="xsd:int"/> <xsd:element name="b" type="xsd:int"/> </xsd:sequence> </xsd:complexContent> </xsd:complexType>
この操作は、次のURLを指定したGETリクエストによって起動できます。これは、例12-3のRPC-literalリクエストに対して使用したものと同じURLである点に注意してください。
http://{yourhost}/{context-path}/{service-url}/addNumbers?a=23&b=24
REST Webサービスでは、単純なXMLメッセージのHTTP POSTリクエストはサポートされていますが、SOAPエンベロープのHTTP POSTリクエストはサポートされていません。RESTリクエストでは、添付ファイル付きのメッセージはサポートされていません。REST WebサービスではSOAPリクエストもサポートされているため、指定されたリクエストがSOAPまたはRESTのどちらであるかを実装側で判断する必要があります。
SOAPサービスは、POSTリクエストを受信するとSOAPActionヘッダーを検索します。ヘッダーが存在する場合は、実装はこのリクエストをSOAPリクエストであると判断します。存在しない場合は、リクエストのroot要素のQNameが検索されます。それがSOAPエンベロープのQNameの場合は、メッセージはSOAPリクエストとして処理されます。そうでない場合は、RESTリクエストとして処理されます。
RESTリクエストは、リクエスト・ドキュメントをSOAPエンベロープでラップすることで処理されます。SOAP 1.2リクエストのContent-TypeヘッダーではないHTTPヘッダーのみが、そのまま受信されます。このContent-Typeヘッダーは、SOAP 1.2に対する適切なコンテンツ・タイプであるapplication/soap+xmlに変更されます。
たとえば、例12-7のRESTリクエストは、例12-8のSOAPエンベロープにラップされます。
<ns:addNumbers> <ns:a>23</ns:a> <ns:b>24</ns:b> </ns:addNumbers>
例12-8のリクエストは、通常のSOAPリクエストとして処理されます。
<soap:Envelope> <soap:Body> <ns:addNumbers> <ns:a>23</ns:a> <ns:b>24</ns:b> </ns:addNumbers> </soap:Body> </soap:Envelope>
RESTリクエストとして処理される（GETまたはPOST）リクエストに対するレスポンスも、RESTスタイルである必要があります。OracleAS Web Servicesプラットフォームは、サーバー上のSOAPレスポンスをクライアントに送信する前に、RESTレスポンスに変換します。RESTレスポンスは、SOAP本体の最初の子要素をルート要素として持つXML文書になります。たとえば、例12-9のSOAPエンベロープが、サーバー上にあると想定します。
<soap:Envelope> <soap:Body> <ns0:result xmlns:nso="…"> <ns:title>How to Win at Poker</ns:title> <ns:author>John Doe</ns:author> </ns0:result> </soap:Body> </soap:Envelope>
例12-10は、クライアントに返送されるレスポンスを示します。Content-Typeが常にtext/xmlである点に注意してください。SOAPヘッダーや添付ファイルは、クライアントに返送されません。
<ns0:result xmlns:ns0="…"> <ns:title>How to Win at Poker</ns:title> <ns:author>John Doe</ns:author> </ns0:result>
WebサービスのREST機能を有効化するオプションが、Oracle JDeveloperのJava Webサービスの作成ウィザードに用意されています。Oracle JDeveloperを使用してWebサービスのREST機能を有効化する方法の詳細は、Oracle JDeveloperのオンライン・ヘルプを参照してください。
「REST Webサービスのアセンブル」を参照してください。
詳細は、次を参照してください。
|
 Copyright © 2006 Oracle Corporation. All Rights Reserved. |
|