Oracle Application Server Containers for J2EE JSPタグ・ライブラリおよびユーティリティ・リファレンス
10g(9.0.4)
       

Webサービス・タグについて

OC4Jには、Webサービスのクライアント・プログラムとして使用するJSPページの作成を可能にするタグ・ライブラリが用意されています。

このトピックでは、そのタグ・ライブラリを次の構成で説明します。

このトピックは、読者がWebサービス、Simple Object Access Protocol(SOAP)およびWeb Services Definition Language(WSDL)に習熟していることを前提としていますが、ある程度の概略はここでも示しました。また、World Wide Web Consortium(W3C)の仕様を含めた追加ドキュメントへの参照もあります。

OC4JのWebサービス・タグ・ライブラリは、OracleAS Web Servicesに基づいています。詳細は、『Oracle Application Server Web Services開発者ガイド』を参照してください。

Webサービスの概要

このセクションでは、次のトピックに分けてWebサービスの概念を簡単に解説します。

Webサービス全般の概要

Webサービスとは、インターネット上でクライアントによって起動することのできる手順つまりアクションのセットです。たとえば、点数、スケジュールおよび順位表を取得するアクションで構成される「ワールド・カップ・サッカー」サービスなども考えられます。

Webサービスには、次の機能が必要です。

Webサービスの詳細、特にOracleAS Web Servicesについては、『Oracle Application Server Web Services開発者ガイド』を参照してください。

関連する仕様は、次のWebサイトを参照してください。

http://www.w3.org/TR/SOAP(W3CのSOAP仕様)

http://www.w3.org/TR/wsdl(W3CのWSDL仕様)

http://www.uddi.org/specification.html(UDDI仕様)

SOAPと関連機能の概要

このセクションでは、SOAPの概要を簡単に説明します。詳細は、W3CのSimple Object Access Protocol(SOAP)1.1の仕様を参照してください。

SOAPは、インターネットまたはその他の分散環境で、型付けされた構造化データを交換するための、XMLベースの軽量なプロトコルです。SOAPの重要な機能として、リモート・プロシージャ・コール(RPC)とメッセージ指向のデータ交換がサポートされています。

メッセージ指向の実装により、データ交換にはモジュールのパッケージ化およびエンコーディング・モデルが利用されます。メッセージは、オペレーションに関連付けられた入力データ部分と出力データ部分を指定する、WSDLのコンポーネントです。詳細は、「Webサービス・メッセージとXMLスキーマ定義の概要」を参照してください。

RPCはソケットの代替手段であり、通信インタフェースがプロシージャ・コールのレベルにあります。ローカル・プロシージャのコールと似ていますが、コールの引数は実際にはパッケージ化されてリモート・ターゲットに送信されます。RPCメカニズムはリクエスト/レスポンスの手法を利用しており、エンドポイントがプロシージャ指向のメッセージを受信し、対応するレスポンスを送り返します。

RPCによるSOAPの使用は、プロトコル・バインドから独立しています。HTTPがプロトコル・バインドである場合、HTTPリクエストがRPCコールに相当し、HTTPレスポンスがRPCレスポンスに相当します。

SOAPには、主として次のような機能があります。

Web Services Definition Languageの主な要素の概要

Webサービスは、XMLベースのWeb Services Definition Languageを使用して、WSDL(.wsdl)ドキュメントで記述されます。

WSDLの重要な用語を次に示します。

WSDL仕様では、WSDLドキュメントの一般的な構造のアウトラインを定めており、そこには次の主な要素が含まれています。完全な情報は、W3CのWeb Services Description Language(WSDL)1.1仕様を参照してください。

Webサービス・メッセージとXMLスキーマ定義の概要

メッセージは、Webサービスのオペレーションすなわちメソッドによって使用されるパラメータを定義します。メッセージは通信されるデータの型付けされた定義であり、1つ以上の部分で構成されます。「注文書」パートや「請求書」パートのように、各パートが論理エンティティに対応します。各パートごとに、関連付けられるデータ項目の型定義があります。

OracleAS Web ServicesなどSOAPベースの実装の場合、メッセージによって使用されるデータ型はXMLスキーマ定義(XSD)言語によって定義されるため、事前定義された単純な型だけでなくユーザー定義の複雑な型もサポートされます。

XSDを使用する実装では、メッセージを定義する構文は次のようになります。


   <message name="nmtoken">
      <part name="nmtoken" [type="qname"] [element="qname"] />
   </message>

この構文で、element属性はXSD構文を使用して定義されるXSDの複雑な型を、type属性はXSDの単純な型を示しており、"nmtoken"は標準のXML名トークン、"qname"は標準のXML修飾名をそれぞれ示しています。メッセージの数は0以上、各メッセージのパートは0以上です。

encodedのSOAPエンコーディング・スタイルでは単純な型のみが許可されるため、element属性は使用されません。literalのエンコーディング・スタイルでは単純な型または複雑な型が許可されるため、<part>属性にはtype属性またはelement属性のいずれかを指定します(両方は不可)。

次に、「例: WSDL定義」から、メッセージ定義の例を示します。


   <message name="GetLastTradePriceInput">
      <part name="body" element="xsd1:TradePriceRequest"/>
   </message>

GetLastTradePriceInputがメッセージの名前で、これが入力メッセージになります(名前のとおりに)。この場合、element属性は複雑な型TradePriceRequestが定義されているネームスペースを示します。次に示すのは、このような定義の例です(これも、後述する「例: WSDL定義」の一部)。


   <element name="TradePriceRequest">
      <complexType>
         <all>
             <element name="tickerSymbol" type="string"/>
             <element name="companyName" type="string"/>
         </all>
      </complexType>
   </element>

XMLスキーマの基本は、次に示すW3Cのサイトで入手できます。


http://www.w3.org/TR/xmlschema-0/

Webサービスの例

この例は、WebサービスのWSDL定義を示したもので、入力メッセージがHTTPリクエストに、出力メッセージがHTTPレスポンスにそれぞれ埋め込まれていることを示しています。

例: WSDL定義

W3CのWeb Services Description Language(WSDL)1.1仕様では、WSDLドキュメントとして次の例をあげており、入力として証券コードをとり、出力として現在の株価を返す株式市況サービスを定義しています。この例では、literalのSOAPエンコーディング・スタイルを使用しているため、複雑な型が許可されている(実際に使用されている)ことに注意してください。


<?xml version="1.0"?>
<definitions name="StockQuote"

targetNamespace="http://example.com/stockquote.wsdl"
          xmlns:tns="http://example.com/stockquote.wsdl"
          xmlns:xsd1="http://example.com/stockquote.xsd"
          xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
          xmlns="http://schemas.xmlsoap.org/wsdl/">

   <types>
      <schema targetNamespace="http://example.com/stockquote.xsd"
              xmlns="http://www.w3.org/2000/10/XMLSchema">
         <element name="TradePriceRequest">
            <complexType>
               <all>
                  <element name="tickerSymbol" type="string"/>
               </all>
            </complexType>
         </element>
         <element name="TradePrice">
            <complexType>
               <all>
                  <element name="price" type="float"/>
               </all>
            </complexType>
         </element>
      </schema>
   </types>

   <message name="GetLastTradePriceInput">
      <part name="body" element="xsd1:TradePriceRequest"/>
   </message>

   <message name="GetLastTradePriceOutput">
      <part name="body" element="xsd1:TradePrice"/>
   </message>

   <portType name="StockQuotePortType">
      <operation name="GetLastTradePrice">
         <input message="tns:GetLastTradePriceInput"/>
         <output message="tns:GetLastTradePriceOutput"/>
      </operation>
   </portType>

   <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
      <soap:binding style="document"
                    transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="GetLastTradePrice">
         <soap:operation soapAction="http://example.com/GetLastTradePrice"/>
            <input>
               <soap:body use="literal"/>
            </input>
            <output>
               <soap:body use="literal"/>
            </output>
      </operation>
   </binding>

   <service name="StockQuoteService">
      <documentation>My first service</documentation>
         <port name="StockQuotePort" binding="tns:StockQuoteBinding">
            <soap:address location="http://example.com/stockquote"/>
          </port>
   </service>

</definitions>

このWSDL定義では、まず入力および出力メッセージとしてGetLastTradePriceInputおよびGetLastTradePriceOutputを指定し、次にそれをオペレーションGetLastTradePriceに結び付け、そのオペレーションのバインドとポートを定義しています。


注意:

  • この例は、データ交換のためのXMLスキーマ定義をはじめとして、Webサービス定義のすべての側面を同じドキュメント内に含んでいます。別の方法として、たとえばstockquote.xsdをこのドキュメント内のネームスペースとするかわりに別のXSDドキュメントとすることもできます。これは、W3CのWSDL仕様に例があります。ただし、OC4JのWebサービス・タグ・ライブラリでは、<import>要素を使用して他のWSDLドキュメントをインポートするWSDLドキュメントはサポートされていません。

  • この例では、ドキュメント・スタイルのバインドを利用しています。Oracle9iASリリース2(9.0.3)では、OC4JのWebサービス・タグ・ライブラリ実装でサポートされているのがRPCスタイルのみであることに注意してください。


例: HTTPリクエストおよびレスポンスに埋め込まれたSOAPメッセージ

前述の例で定義されたWebサービスに対応して、このセクションではSOAPエンベロープによる入力メッセージをHTTPリクエストに埋め込み、SOAPエンベロープによる出力メッセージをHTTPレスポンスに埋め込んだ場合にメッセージがどうなるかを示します。これらの例も、W3CのWeb Services Description Language(WSDL)1.1仕様のものです。

リクエストは次のようになります。


POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "SOAP_URI"

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
         <m:GetLastTradePrice xmlns:m="xmlns_URI">
            <m:tickerSymbol>DIS</m:tickerSymbol>
         </m:GetLastTradePrice>
      </soapenv:Body>
   </soapenv:Envelope>

この例では、xmlns_URIが、GetLastTradePriceオペレーションとそのメッセージを定義している(前述の「例: WSDL定義」を参照)場所へのURIです。この中でtickerSymbolも定義されています。リクエストは、Walt Disney Co.の株価に対して行われています。SOAP_URIが、SOAPのHTTPバインドに対するSOAPアクションHTTPヘッダーのURIです。

レスポンスは次のようになります。


HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
         <m:GetLastTradePriceResponse xmlns:m="Some_URI">
            <m:price>34.5</m:price>
         </m:GetLastTradePriceResponse>
      </soapenv:Body>
   </soapenv:Envelope>

規則により、オペレーションXxxxに対するレスポンスはXxxxResponseと呼ばれます。

OC4J Webサービス・タグ

このセクションでは、Webサービス・タグ・ライブラリの概要および詳細と、タグ・ライブラリ実装のベースとなるOracleAS Web Servicesの概要を示します。このセクションの構成は、次のとおりです。

Oracle Application Server Web Servicesとタグ・ライブラリ実装の概要

OC4Jで提供されるWebサービス・タグ・ライブラリを使用すると、開発者はWebサービス・クライアント・アプリケーション用のJSPページを簡単に作成することができます。実装ではSOAPベースのRPCスタイルのメカニズムを使用します。クライアント・アプリケーションはWSDLドキュメントにアクセスし、次にそのWSDL情報を使用してWebサービスのオペレーションにアクセスします。

タグ・ライブラリは、Oracle実装の動的起動API(『Oracle Application Server Web Services開発者ガイド』を参照)も利用します。クライアント・アプリケーションが実行時にWSDLドキュメントを取得する際には、WSDLドキュメントに記述されているSOAPオペレーションが、動的起動APIによって起動されます。タグ・ハンドラは、Webサービスを起動するSOAPリクエストを送信するとき、およびSOAPレスポンスを処理するときにAPIを使用します。

Oracleの動的起動APIは、oracle.j2ee.ws.clientパッケージおよびoracle.j2ee.ws.client.wsdlパッケージのクラスとインタフェースで構成されます。

oracle.j2ee.ws.clientパッケージには、次のものが含まれます。

oracle.j2ee.ws.client.wsdlパッケージには、次のものが含まれます。

Webサービス・タグの機能の概要

このセクションでは、OC4J Webサービス・タグ・ライブラリとその機能の概要について説明します。タグ・ライブラリによって、Webサービスへのバインド、SOAPリクエストおよびSOAPレスポンスを通じたWebサービス・オペレーションの使用、入力および出力メッセージ・パートの定義、SOAP/XMLデータ型からJava型へのマッピング、クライアント・アプリケーションが使用するカスタム・プロパティの設定などがサポートされます。

タグ・ライブラリは、WSDLドキュメントで定義されるオペレーションの起動をサポートしますが、そのドキュメントでは次のようなネームスペースを持つW3C XMLスキーマ・バージョンを使用します。


http://www.w3.org/2001/XMLSchema

Webサービス・タグ・ライブラリに含まれるのは、webserviceタグとその内部でネスト可能なオプションのmapおよびpropertyタグ、そしてinvokeタグとその内部でネスト可能なオプションのpartタグです。使用方法は次のとおりです。

Webサービス・タグの説明

このセクションでは、OC4J Webサービス・タグとその構文の詳細を説明します。

標準に準拠したJavaServer Pagesタグ・ライブラリの実装であるWebサービス・タグ・ライブラリは、OC4Jで提供されるojsputil.jarファイルに含まれています。このファイルがインストール済で、クラスパスに存在していることを確認してください。

Webサービス・タグ・ライブラリを使用するには、タグ・ライブラリ・ディスクリプタ・ファイルwstaglib.tldが、アプリケーションとともにデプロイされている必要があります。また、ライブラリを使用するJSPページには、適切なtaglibディレクティブが存在する必要があります。OracleASのインストール時、TLDファイルは、予約済のタグ・ライブラリ・ディレクトリに置かれます。taglibディレクティブと予約済のタグ・ライブラリ・ディレクトリの詳細は、『Oracle Application Server Containers for J2EE JavaServer Pages開発者ガイド』を参照してください。

このセクションで説明するタグを使用した例は、「Webサービス・タグの例」を参照してください。


注意:

  • このタグ構文では、接頭辞「ws:」が使用されます。慣例的にこのように表記しますが、必須ではありません。任意の接頭辞をtaglibディレクティブに指定できます。

  • このヘルプのタグ構文規則の詳細は、「タグ構文の表記と意味」を参照してください。


webserviceタグ

このタグを使用してWebサービス・プロキシを作成します。Webサービス・プロキシは、oracle.j2ee.ws.client.WebServiceProxyインタフェースを実装するクラスのインスタンスです。タグにはWSDLドキュメントのURLが必要で、次のようにバインドおよびSOPAの場所、またはサービス名とポートを使用します。

  1. まず、タグの属性にバインドおよびSOAPの場所が指定されている場合、タグ・ハンドラはそれを使用してプロキシを作成します。(この場合、サービス名とポートの属性は無視されます。)

  2. バインドおよびSOAPの場所が指定されていない場合、タグ・ハンドラは次のようにサービス名とポートを使用します。

    1. サービス名とポートがタグの属性で指定されている場合、タグ・ハンドラはそれらを使用してプロキシを作成します。

    2. サービス名とポートがタグの属性で指定されている場合、タグ・ハンドラはWSDLドキュメントの最初のサービスと、そのサービスにリストされている最初のポートを使用します。

バインドおよびSOAPの場所を使用すると、UDDIレジストリを介してアクセスされるWSDLドキュメントを持つWSDLサービスで特に便利です。その場合、バインドと場所はUDDIへの問合せで決定し、リクエスト時の式でタグに指定することかできます。

作成したWebサービス・プロキシは、ネストしているmapタグを使用して、エントリをSOAPマッピング・レジストリに追加します。次項の「mapタグ」を参照してください。

構文


<ws:webservice wsdlUrl = "WSDL_URL_of_Web_service"
             [ id = "variable_name_for_Web_service_proxy" ]
             [ scope = "page" | "request" | "session" | "application" ]
             [ binding = "SOAP_binding_information" ]
             [ soapLocation = "SOAP_endpoint_URL" ]
             [ service = "service_name_in_WSDL" ]
             [ port = "port_name_for_service" ]

...body / nested tags...

</ws:webservice>


注意:

scope属性に、リクエスト時の式は指定できません。


属性

mapタグ

相互運用性のために、WSDLで定義されるSOAP/XMLデータ型を、Javaクライアント・アプリケーションのJSPページで使用されるJavaデータ型にマップするマッピング・メカニズムが必要です。これは、OracleAS Web ServicesのSOAPマッピング・レジストリにより実現されます。

任意の数のmapタグをwebserviceタグ内でネストして、Webサービス・プロキシでエントリをレジストリに追加することができます。目的の型マッピングごとに1つのmapタグを使用してください。

このレジストリは、org.apache.soap.util.xmlパッケージのXMLJavaMappingRegistryクラスのインスタンスです。WebServiceProxyインスタンスには、レジストリにアクセスするためのgetXMLMappingRegistry()メソッドがあります。

mapタグには、エンコーディング・スタイル、シリアライザ、デシリアライザ、および型マッピングを簡易化するネームスペースURIを指定する属性を指定できます。Webサービス・タグ・ライブラリでは、必要があればカスタムのシリアライザとデシリアライザがサポートされます。


重要: 

mapタグを使用する場合は、webserviceタグ内でネストする必要があります。


構文


<ws:map localName = "local_name_of_SOAPXML_type"
        namespaceUri = "URI_of_namespace_for_SOAPXML_type"
        javaType = "Java_type_to_map"
        encodingStyle = "URL_of_SOAP_encoding_style"
        java2xmlClassName = "Java_to_XML_serializer"
        xml2javaClassName = "XML_to_Java_deserializer" />

属性

propertyタグ

オプションでこのタグを使用すると、サポートされているカスタム・プロパティのうちいずれかを定義する名前と値のペアを指定できます。このカスタム・プロパティは、Webサービスのクライアント・アプリケーションによって使用されます。たとえば、ネットワーク・ファイアウォールを越えるアクセスのためにプロキシが必要な場合は、propertyタグを使用して、HTTPプロキシ・ホストを指定できます。サポートされるプロパティは次のとおりです。

構文


<ws:property name="http.proxyHost" | "http.proxyPort" | "javax.net.ssl.KeyStore"
            value = "property_value" />

属性

invokeタグ

このタグを使用して、Webサービスのオペレーションを起動します。タグ・ハンドラは、SOAPリクエストにおける入力メッセージを渡すことによってリモートWebサービスのオペレーションをコールした後、SOAPレスポンスを待機します。オペレーションと、返されるレスポンスを含むオブジェクトのオブジェクトIDを指定する必要があります。タグ・ハンドラは、そのオペレーション名を使用して、WSDLドキュメント内のオペレーションを検索します。

invokeタグがWebサービス・プロキシにアクセスするには、次の2つの方法があります。

オーバーロードされたオペレーションがある(同じ名前の2つのオペレーションが異なるI/Oメッセージを使用している)場合、invokeタグには目的のオペレーションのための入力メッセージ名と出力メッセージ名を指定する属性があります。この場合、指定した入力および出力メッセージ名を使用して、オペレーションのRPCシグネチャが生成されます。それ以外の場合、RPCシグネチャはWSDLドキュメントに従ったデフォルトになります。

出力メッセージに複数のパートがある場合、返される結果はメッセージ・パートの配列になります(すべて1つのSOAPレスポンス内)。


重要: 

SOAPレスポンスの待機は、ブロック機能です。


構文


<ws:invoke id = "variable_name_for_output_result"
           operation = "operation_to_invoke"
         [ webservice = "variable_name_of_Web_service_proxy" ]
         [ inputMsgName = "name_of_input_message" ]
         [ outputMsgName = "name_of_output_message" ]

...body / nested tags...

</ws:invoke>

属性

partタグ

実行するオペレーションに入力メッセージ・パートの値が必要な場合、各入力パートに対し1つのpartタグを使用します。


重要: 

partタグを使用する場合は、invokeタグ内でネストする必要があります。


構文


<ws:part name = "part_name"
         value = "part_value" />

属性

Webサービス・タグの例

このセクションでは、タグ・ライブラリを使用するテンプレートと、実際のJSPページの2つの例を示します。

Webサービスの例: 使用テンプレート


<HTML>
<HEAD>
<TITLE>Title</TITLE>
</HEAD>
<BODY>
<H2>This is sample HTML text.</H2>
<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ws/WsTagLibrary.tld"
           prefix="ws" %>
<ws:webservice id="myws"
               wsdlUrl="wsdlurl"
               {
                  binding="" soapLocation="" | service="" port=""
               }
               {
                  scope="page | request | session | application"
               }
                >
   <ws:property name="property" value="string"/>

   <ws:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
           localname="SOAPStruct"
           namespaceUri="http://soapinterop.org/xsd"
           javaType="MySoapStructBean"
           java2xmlClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
           xml2javaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
    />

</ws:webservice>

<ws:invoke id="result" webservice="myws" operation="add" inputMsgName=""
           outputMsgName="">
   <ws:part name="part_name" value="{string | <%= expression %>}"/>
</ws:invoke>

<% =result %>
</BODY>
</HTML>

Webサービスの例: サンプルJSPページ


<%@ page contentType="text/html"%>
<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ws/wstaglib.tld"
           prefix="ws" %>
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; ">
</HEAD>
<BODY>
<%
 String itemID = request.getParameter("itemID");
%>
<ws:webservice id="ebay"
    wsdlUrl="http://www.xmethods.net/sd/2001/EBayWatcherService.wsdl"
    binding="eBayWatcherBinding"
    soapLocation="http://services.xmethods.net:80/soap/servlet/rpcrouter"
    scope="page">
  <ws:property name="http.proxyHost" value="www-proxy.us.oracle.com"/>
  <ws:property name="http.proxyPort" value="80"/>
</ws:webservice>
<ws:invoke id="price" webservice="ebay" operation="getCurrentPrice">
  <ws:part name="auction_id" value="<%=itemID%>"/>
</ws:invoke>
<B>
Action price for eBay Item # <%=itemID%> is :
</B>
<P>
$<%= price%>
@
<%= new java.util.Date()%>
</P>
</BODY>
</HTML>