JAX-WS Web サービスでの MTOM の使用可能化

Java™ API for XML-Based Web Services (JAX-WS) を使用する場合、Web サービス要求のほかに、イメージやファイルなどのバイナリー添付を送信することができます。JAX-WS では、SOAP Message Transmission Optimization Mechanism (MTOM) 仕様に指定された、 バイナリー・データの最適化伝送のサポートが追加されています。

このタスクについて

JAX-WS は、バイナリー添付データの送信用に SOAP Message Transmission Optimized Mechanism (MTOM) の使用をサポートします。MTOM を有効にすることにより、 バイナリー・データを XML 文書に組み込むために必要なデータ・エンコードを行うコストを負担することなく、 バイナリー・データの送受信を最適に行うことができます。

アプリケーション・サーバーは、JAX-WS アプリケーションの場合にのみ、MTOM を使用した添付の送信をサポートします。 本製品は、新規の MTOM および XOP 規格を使用することによって、Web Services Security SOAP メッセージに添付を提供する機能も提供します。

JAX-WS アプリケーションは、XML 文書内に含まれる base64 または hexBinary エンコード・データとして、バイナリー・データを送信できます。 しかし、MTOM が備える最適化機能を利用するには、MTOM を使用可能にして、 バイナリーの base64 データを XML 文書外に含まれる添付として送信してください。MTOM 最適化は、デフォルトでは使用不可になっています。 JAX-WS アプリケーションでは、MTOM サポートを有効にするために、クライアント成果物とサーバー成果物の両方を別個に構成する必要があります。

手順

  1. バイナリー添付ファイルが組み込まれた Web サービス・アプリケーションのデータを表す XML スキーマまたは Web サービス記述言語 (WSDL) ファイルを含む JAX-WS アプリケーションの、Java 成果物を開発します。
    1. WSDL ファイルから開始する場合、必要な JAX-WS 移植可能成果物を生成するために、wsimport コマンドを使用して WSDL ファイルから Java 成果物を開発します
    2. JavaBeans コンポーネントから開始する 場合、JAX-WS アプリケーションの Java 成果物を 開発し、オプションとして wsgen コマンドを使用して WSDL ファイルを生成します。 XML スキーマ または WSDL ファイルには、バイナリー・データの xsd:base64Binary または xsd:hexBinary エレメント定義が含まれています。
    3. JAXB によるマッピングに影響が及ぶように、エレメントに xmime:expectedContentTypes 属性を含めることもできます。
  2. 以下のいずれかのメソッドを使用して、エンドポイント実装クラスで MTOM を使用可能にします。
    • エンドポイントで @MTOM アノテーションを使用します。

      エンドポイントで MTOM を使用可能にするには、 エンドポイントで @MTOM (javax.xml.ws.soap.MTOM) アノテーションを使用します。@MTOM アノテーションには、2 つの パラメーター、enabled および threshold があります。 enabled パラメーターはブール値を持ち、MTOM が JAX-WS エンドポイントで使用可能かどうかを示します。threshold パラメーターの値は整数で、ゼロ以上でなければなりません。 MTOM が使用可能である場合、しきい値を超えるサイズの (バイト単位) バイナリー・データは、 XML-binary Optimized Packaging (XOP) にエンコードされるか、添付として送信されます。 メッセージ・サイズがしきい値よりも小さい場合、メッセージ は base64 または hexBinary データとして XML 文書内にインライン化されます。

      以下のスニペットは、 JAX-WS MyServiceImpl エンドポイントで MTOM を使用可能にし、 しきい値を 2048 バイトに指定する @MTOM アノテーションを追加する例を示しています。
      @MTOM(enabled=true, threshold=2048)
      @WebService
      public class MyServiceImpl {
      ...
      }
      さらに、エンドポイント実装クラスで @BindingType (javax.xml.ws.BindingType) アノテーションを使用して、 エンドポイントが MTOM バインディング・タイプの 1 つをサポートするように指定し、 応答メッセージを MTOM 対応にすることができます。javax.xml.ws.SOAPBinding クラスで、2 つの異なる定数、 SOAP11HTTP_MTOM_BINDINGSOAP12HTTP_MTOM_BINDING を定義します。 この定義は、次の例のように、@BindingType アノテーションの値として使用できます。
      // This example is for SOAP version 1.1.
      @BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING)
      @WebService
      public class MyServiceImpl {
      ...
      }
      // This example is for SOAP version 1.2.
      @BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING)
      @WebService
      public class MyServiceImpl {
      ...
      }

      @MTOM アノテーションおよびその値は、@BindingType アノテーションをオーバーライドします。例えば、 @BindingType が MTOM が使用可能であることを示していても、@MTOM アノテーションが存在し、 その enabled 値が false である場合、MTOM は使用不可になります。

    • <enable-mtom> および <mtom-threshold> デプロイメント記述子エレメントを使用します。
      サービス・エンドポイント実装クラスで @MTOM アノテーションを使用する 代わりに、webservices.xml デプロイメント記述子の <port-component> エレメント内 の <enable-mtom> および <mtom-threshold> エレメントを使用 することができます。例えば、次のように指定します。
      <port-component>
      						<port-component-name>MyPort1</port-component-name>
      			<enable-mtom>true</enable-mtom>
      						<mtom-threshold>2048</mtom-threshold>
      			<service-impl-bean>
      								<servlet-link>MyPort1ImplBean</servlet-link>
      			</service-impl-bean>
      </port-component>
      トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble): デプロイメント記述子エレメントは、 MTOM アノテーションの対応する属性に優先します。例えば、 アノテーションで enabled 属性が true に設定されていても、 webservices.xml ファイルで <enable-mtom> エレメント が false に設定されていると、MTOM は該当するエンドポイントで使用不可になります。gotcha
  3. クライアントの MTOM を使用可能にして、クライアントからサーバーに送信されるバイナリー・メッセージ を最適化します。 以下のいずれかの方法を使用して、クライアントで MTOM を使用可能にします。
    • ディスパッチ・クライアントの MTOM を使用可能にします。
      注: ディスパッチ・クライアントの場合、クライアント・アプリケーションは、最適化されたフォーマットで SOAP メッセージを構成する必要があります。

      以下の例では、 SOAP バージョン 1.1 を使用します。

      最初の方法では、SOAPBinding.setMTOMEnabled(); を使用します。 例えば、次のように指定します。
      SOAPBinding binding = (SOAPBinding)dispatch.getBinding();
          binding.setMTOMEnabled(true);
      2 番目の方法では、 Service.addPort を使用します。例えば、次のように指定します。
          Service svc = Service.create(serviceName);
          svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl); 
      3 番目の方法では、 MTOMFeature を使用します。例えば、次のように指定します。
         MTOMFeature mtom = new MTOMFeature(true, 2048);
          Service svc = Service.create(serviceName);
          svc.addPort(portName, SOAPBinding.SOAP11_HTTP_BINDING, endpointUrl);
          Dispatch<Source> dsp = svc.createDispatch(portName, Source.class, Service.Mode.PAYLOAD, mtom);
    • 動的プロキシー・クライアントで MTOM を使用可能にします。
      // Create a BindingProvider bp from a proxy port.
        Service svc = Service.create(serviceName);
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        
        //Enable MTOM using the SOAPBinding.
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        SOAPBinding binding = (SOAPBinding) bp.getBinding();
        binding.setMTOMEnabled(true);
      
        //Or, you can enable MTOM with the MTOMFeature.
        MTOMFeature mtom = new MTOMFeature();
        MtomSample proxy = svc.getPort(portName, MtomSample.class, mtom);
    • @MTOM アノテーションを使用してクライアントで MTOM を使用可能にします。 例えば、次のように指定します。
      public class MyClientApplication {
      
          // Enable MTOM for a port-comonent-ref resource injection.
      	    		   @MTOM(enabled=true, threshold=1024)
      	    		   @WebServiceRef(MyService.class)
      	    		   private MyPortType myPort;
          ...
      }
    • port-component-ref エレメント内のデプロイメント記述子を使用して、 クライアントで MTOM を使用可能にします。例えば、次のように指定します。
      <service-ref>
          <service-ref-name>service/MyPortComponentRef</service-ref-name>
          <service-interface>com.example.MyService</service-ref-interface>
          <port-component-ref>
              <service-endpoint-interface>com.example.MyPortType</service-endpoint-interface>
              <enable-mtom>true</enable-mtom>
              <mtom-threshold>1024</mtom-threshold>
          </port-component-ref>
      </service-ref>
      トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble): デプロイメント記述子エレメントは、 MTOM アノテーションの対応する属性に優先します。例えば、 アノテーションで enabled 属性が true に設定されていても、 クライアントの service-ref のデプロイメント記述子エントリーで <enable-mtom> エレメント が false に設定されていると、MTOM はそのサービス参照で使用不可になります。gotcha

タスクの結果

MTOM を使用してバイナリー・データを最適な状態で送受信する、JAX-WS Web サービスのサーバーおよびクライアント・アプリケーションを開発しました。

以下の例は、WSDL ファイルから開始する際に、Web サービスのクライアント・エンドポイントとサーバー・エンドポイントの両方で MTOM サポートを有効にする方法を示しています。

  1. xsd:base64Binary エレメントを含む WSDL ファイルを見つけます。 次の例は、xsd:base64Binary エレメントを含む WSDL ファイルの一部分です。
      <types>
        ........
        <xs:complexType name="ImageDepot">
            <xs:sequence>
                <xs:element name="imageData" 
                            type="xs:base64Binary"                        
                            xmime:expectedContentTypes="image/jpeg"/>
    
            </xs:sequence>
        </xs:complexType>
        ........
    </types>
  2. WSDL ファイルの app_server_root¥bin¥ ディレクトリーから wsimport コマンドを実行して、一連の JAX-WS 移植可能成果物を生成します。
    [Windows]
    app_server_root¥bin¥wsimport.bat <wsdl_url>
    [AIX][HP-UX][Linux][Solaris]
    app_server_root/bin/wsimport.sh <wsdl_url>
    WSDL ファイルに含まれる expectedContentTypes 値に応じて、 生成される JAXB 成果物は次の表に記述されている Java タイプになります。
    表 1. MIME タイプおよび Java 型のマッピング. MIME タイプと Java 型のマッピングについて説明します。
    MIME タイプ Java 型
    image/gif java.awt.Image
    image/jpeg java.awt.Image
    text/plain java.lang.String
    text/xml javax.xml.transform.Source
    application/xml javax.xml.transform.Source
    */* javax.activation.DataHandler
  3. 他の JAX-WS アプリケーションと同様に、JAXB 成果物を使用します。 これらの Bean を使用して、ディスパッチ・クライアント API と動的プロキシー・クライアント API の両方からバイナリー・データを送信します。
  4. ディスパッチ・クライアントで MTOM を使用可能にします。
    //Create the Dispatch instance.
            JAXBContext jbc = JAXBContext.newInstance("org.apache.axis2.jaxws.sample.mtom");
            Dispatch<Object> dispatch = svc.createDispatch(portName, jbc, Service.Mode.PAYLOAD);
    
    //Enable MTOM.
            SOAPBinding binding = (SOAPBinding) dispatch.getBinding();
            binding.setMTOMEnabled(true);
  5. 動的プロキシー・クライアントで MTOM を使用可能にします。
    //Create the Dynamic Proxy instance.
            Service svc = Service.create(serviceName);
            MtomSample proxy = svc.getPort(portName, MtomSample.class);
    
    //Enable MTOM.
            BindingProvider bp = (BindingProvider) proxy;
            SOAPBinding binding = (SOAPBinding) bp.getBinding();
            binding.setMTOMEnabled(true);
    JAX-WS クライアントを MTOM 対応にしたので、サーバーに送られるメッセージでも MTOM が使用可能になっています。しかし、サーバーが MTOM を使用してクライアントに応答する場合は、 エンドポイントで MTOM を使用可能にする必要があります。
  6. エンドポイント実装クラスで MTOM を使用可能にします。
    @MTOM(enabled, threshold=4096)
    @WebService (endpointInterface="org.apache.axis2.jaxws.sample.mtom.MtomSample")
    
    public class MtomSampleService implements MtomSample {
       ....
    }
    jaxax.xml.ws.SOAPBinding クラスには、サポートされるバインディング・タイプごとに静的メンバーが含まれています。 SOAP11HTTP_MTOM_BINDING または SOAP12HTTP_MTOM_BINDING のいずれかを、@BindingType アノテーションの値として含めます。 この値により、すべてのサーバー応答で MTOM が使用可能になります。

サーバーおよびクライアントで MTOM を使用可能にすると、 添付を表すバイナリー・データは Multipurpose Internet Mail Extensions (MIME) 添付として SOAP メッセージに組み込まれます。MTOM を使用しない場合、 同じデータは XML スキーマを記述するフォーマット (base64 または 16 進エンコード) でエンコードされて、 XML 文書にインラインで組み込まれます。

この例は、 添付付きの MTOM 対応 SOAP バージョン 1.1 メッセージを示しています。 type 属性と content-type 属性は、両方とも値 application/xop+xml を取ります。 これは、MTOM を有効にしたときに XML-binary Optimized Packaging (XOP) を使用してメッセージが正常に最適化されたことを示します。 この例は、MTOM を有効にした通信線上で、最適化されたメッセージがどのようになるかを示しています。
... other transport headers ...
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812; 
type="application/xop+xml"; start="
<0.urn:uuid:0FE43E4D025F0BF3DC11582467646813@apache.org>"; start-info="text/xml"; charset=UTF-8

--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812
content-type: application/xop+xml; charset=UTF-8; type="text/xml";
content-transfer-encoding: binary
content-id:
   <0.urn:uuid:0FE43E4D025F0BF3DC11582467646813@apache.org>

<?xml version="1.0" encoding="UTF-8"?>
         <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
            <soapenv:Header/>
            <soapenv:Body>
               <sendImage xmlns="http://org/apache/axis2/jaxws/sample/mtom">
                  <input>
                     <imageData>
                        <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" 
href="cid:1.urn:uuid:0FE43E4D025F0BF3DC11582467646811@apache.org"/>
                     </imageData>
                  </input>
               </sendImage>
            </soapenv:Body>
         </soapenv:Envelope>
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812
content-type: text/plain
content-transfer-encoding: binary
content-id:
         <1.urn:uuid:0FE43E4D025F0BF3DC11582467646811@apache.org>

… binary data goes here …
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812--
それとは対照的に、 次の例は、MTOM を無効にした通信線上の SOAP バージョン 1.1 メッセージを示しています。 バイナリー・データは SOAP メッセージの本体に組み込まれており、 SOAP メッセージは最適化されません。
... other transport headers ...
Content-Type: text/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header/>
      <soapenv:Body>
         <sendImage xmlns="http://org/apache/axis2/jaxws/sample/mtom">
            <input>
               <imageData>R0lGADl ... more base64 encoded data ... KTJk8giAAA7</imageData>
            </input>
         </sendImage>
      </soapenv:Body>
   </soapenv:Envelope>

追加情報については、インフォメーション・センターの『サンプル』セクションを参照してください。このセクションには、JAX-WS Web サービスでの MTOM の使用方法を示すサンプルがあります。


トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_enablemtom
ファイル名:twbs_enablemtom.html