12 MTOM/XOPを使用したバイナリ・データ転送の最適化

以下の節では、MTOM/XOPを使用してバイナリ・データを送信する方法について説明します。

MTOM/XOPを使用したバイナリ・データの送信
SOAP添付ファイルのストリーミング

MTOM/XOPを使用したバイナリ・データの送信

SOAP MTOM/XOP (Message Transmission Optimization Mechanism/XML-binary Optimized Packaging)では、SOAPメッセージ内のxs:base64Binary型またはxs:hexBinary型のXMLデータの転送を最適化する方法が定義されています。転送プロトコルがHTTPの場合、MIME添付ファイルを使用して、送信側と受信側の両方に対して同時にSOAPメッセージ内のXMLデータへの直接アクセスを許可する間にデータを伝達します。このとき、base64BinaryまたはhexBinaryデータのマーシャリングにMIMEアーティファクトが使用されていたことを意識する必要はありません。バイナリ・データの最適化プロセスでは、1)バイナリ・データのエンコード、2) SOAPエンベロープからのバイナリ・データの削除、3)バイナリ・データの圧縮、4) MIMEパッケージへのバイナリ・データの添付、および5) SOAPエンベロープ内のMIMEパッケージへの参照の追加を行います。

MTOM/XOPのサポートは、JWSアノテーションの使用によって、JAX-WSでは標準となっています。MTOM仕様では、MTOMが有効化されている場合に、base64binaryまたはhexBinaryデータの送信時にWebサービスのランタイムでXOPバイナリ最適化を使用することは必須ではありません。むしろ、この仕様では、ランタイムがこれを選択して行うようになっています。これは場合によっては、バイナリ・データをSOAPメッセージに直接入れて送信するほうが効率的であるとランタイムで判断されることがあるためです。一例としては、トランスポートされるデータ量が少なく、単にデータをそのままインライン処理するよりも多くのリソースが、会話およびトランスポートのオーバーヘッドにより消費されてしまう場合があげられます。

デフォルトでbase64Binary XMLデータ型にマップされるJava型は、javax.activation.DataHandler、java.awt.Imageとjavax.xml.transform.Sourceです。base64BinaryまたはhexBinary型の要素は、デフォルトでbyte[]にマップされます。

次の表に、MTOM/XOPを使用してbase64BinaryまたはhexBinary型の添付ファイルを送信する手順をまとめます。

表12-1 MTOM/XOPを使用してバイナリ・データを送信する手順

#	手順	説明
1	MTOM添付ファイルとして使用する予定のデータ型のアノテーションを追加します。(オプション)	使用するプログラミング・モデルに応じ、JavaクラスまたはWSDLにアノテーションを追加して、バイナリ・データの送信に使用するコンテンツ・タイプを定義できます。この手順は省略可能です。XMLバイナリ型は、デフォルトではJava `byte[]`にマップされます。詳細については、「データ型のアノテーションの追加」を参照してください。
2	WebサービスでMTOMを有効にします。	「WebサービスでMTOMの有効化」を参照してください。
3	WebサービスのクライアントでMTOMを有効にします。	「クライアントでMTOMの有効化」を参照してください。
4	添付ファイルのしきい値の設定	`xs:binary64`データをインラインまたは添付ファイルとして送信する場合に指定する添付ファイルのしきい値を設定します。「添付ファイルのしきい値の設定」を参照してください。

データ型のアノテーションの追加

使用するプログラミング・モデルに応じ、JavaクラスまたはWSDLにアノテーションを追加して、バイナリ・データの送信に使用するMIMEコンテンツ・タイプを定義できます。この手順は省略可能です。

次の表に、MIMEコンテンツ・タイプとJava型のマッピングを定義します。型によっては、デフォルトのマッピングが存在します。デフォルトのマッピングが存在しないMIMEコンテンツ・タイプは、DataHandlerにマップされます。

表12-2 MIMEコンテンツ・タイプとJava型のマッピング

MIMEコンテンツ・タイプ	Java型
image/gif	java.awt.Image
image/jpeg	java.awt.Image
text/plain	java.lang.String
text/xml or application/xml	javax.xml.transform.Source
/	javax.activation.DataHandler

以下の節では、データ型のアノテーションを追加する方法について説明します。Javaから始める方法と、WSDLから始める方法があります。

データ型のアノテーションを追加する: Javaから始める場合
データ型のアノテーションを追加する: WSDLから始める場合

データ型のアノテーションを追加する: Javaから始める場合

バイナリ・データの送信に使用するコンテンツ・タイプの定義をJavaから始める場合は、バイナリ・データを保持するフィールドに@XmlMimeTypeアノテーションを追加します。

バイナリ・データを保持するフィールドは、DataHandler型にする必要があります。

次のサンプルに、バイナリ・データを保持するJavaクラス内のフィールドにアノテーションを追加する方法を示します。

@WebMethod
@Oneway
public void dataUpload(
    @XmlMimeType("application/octet-stream") DataHandler data) 
{
}

データ型のアノテーションを追加する: WSDLから始める場合

バイナリ・データの送信に使用するコンテンツ・タイプの定義をWSDLから始める場合は、以下のいずれかの属性を使用して、xs:base64Binaryまたはxs:hexBinary型のWSDL要素にアノテーションを追加します。

xmime:contentType - この要素のコンテンツ・タイプを定義します。
xmime:expectedContentType - バイナリ・データとして容認するメディア・タイプの範囲を定義します。

次のサンプルでは、base64binary型のimage要素を、java.awt.Image Java型にマップされるimage/gif MIMEタイプにマップしています。

<element name="image" type="base64Binary"
xmime:expectedContentTypes="image/gif"
xmlns:xmime="http://www.w3.org/2005/05/xmlmime"/>

WebサービスでMTOMの有効化

次の項で説明しているように、アノテーションまたはWS-Policyファイルを使用してWebサービスでMTOMを有効にすることができます。

アノテーションを使用してWebサービスでMTOMの有効化
WS-Policyファイルを使用してWebサービスでMTOMの有効化

アノテーションを使用してWebサービスでMTOMの有効化

WebサービスでMTOMを有効にするには、次のサンプルのようにサービス・エンド・ポイント実装クラスに@java.xml.ws.soap.MTOMアノテーションを指定します。関連するコードは太字で示されています。

package examples.webservices.mtom;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.soap.MTOM; 

@MTOM
@WebService(name="MtomPortType",
            serviceName="MtomService",
            targetNamespace="http://example.org")
public class MTOMImpl { 
  @WebMethod
  public String echoBinaryAsString(byte[] bytes) {
    return new String(bytes);

  }
}

WS-Policyファイルを使用してWebサービスでMTOMの有効化

前の項で説明した@MTOMアノテーションに加えて、WebLogic JAX-WS WebサービスでのMTOM/XOPのサポートはあらかじめパッケージ化されたWS-PolicyファイルMtom.xmlを使用して実装されます。WS-Policyファイルは、WS-Policy仕様(http://www.w3.org/TR/ws-policyを参照)に準拠しています。この仕様では、Webサービスのポリシー(この場合は、バイナリ・データ送信のためのMTOM/XOPの使用)を記述および伝達するための汎用モデルとXML構文を提供しています。あらかじめパッケージ化されたMtom.xml WS-PolicyファイルをWebサービスWSDLのtypesセクションに組み込むには、次のように指定します(あくまでも参考として掲載しています。このファイルは変更できません)。

<wsp:Policy wsu:Id="myService_policy">
     <wsp:ExactlyOne>
         <wsp:All>
             <wsoma:OptimizedMimeSerialization 
                    xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization" /> 
         </wsp:All>
     </wsp:ExactlyOne>
 </wsp:Policy>

コンパイルされたJWSファイルをWebLogic Serverにデプロイすると、MTOM WS-Policyファイルを参照する次のスニペットが動的WSDLに自動的に含まれます。このスニペットでは、WebサービスがMTOM/XOPを使用することを示しています。

<wsdl:binding name="BasicHttpBinding_IMtomTest" 
                       type="i0:IMtomTest">
     <wsp:PolicyReference URI="#myService_policy" /> 
     <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

JWSファイルで@Policyメタデータ・アノテーションを指定すると、開発時にWebサービスとMtom.xml WS-Policyファイルを関連付けることができます。必須であるMtom.xmlファイルへの参照が動的WSDLに確実に含まれるよう、必ずattachToWsdl=true属性も指定します。次の例を参照してください。

デプロイメント時にWebサービスとMtom.xml WS-Policyファイルを関連付けるには、デプロイメント直前にtypesセクションにポリシーを追加し、WSDLを修正します。

また、管理コンソールを使用して実行時にファイルを追加できます。詳細は、Oracle WebLogic Server管理コンソール・ヘルプのWS-PolicyファイルとWebサービスとの関連付けに関する項を参照してください。この項では、JWSアノテーションの使用方法について説明します。

次の簡単なJWSファイルの例では、JWSファイルで@weblogic.jws.Policyアノテーションを使用して、あらかじめパッケージ化されたMtom.xmlファイルをWebサービスに適用することを指定する方法を示します(該当するコードは太字で示してあります)。

package examples.webservices.mtom;
import javax.jws.WebMethod;
import javax.jws.WebService;
 import weblogic.jws.Policy;
@WebService(name="MtomPortType",
             serviceName="MtomService",
             targetNamespace="http://example.org")
@Policy(uri="policy:Mtom.xml", attachToWsdl=true)
public class MtomImpl {
  @WebMethod
   public String echoBinaryAsString(byte[] bytes) {
     return new String(bytes);
   }

クライアントでMTOMの有効化

WebサービスのクライアントでMTOMを有効にするには、次のサンプルのように、Webサービスのプロキシまたはディスパッチの作成時にパラメータとしてjavax.xml.ws.soap.MTOMFeatureのインスタンスを渡します。関連するコードは太字で示されています。

package examples.webservices.mtom.client;

import javax.xml.ws.soap.MTOMFeature;

public class Main {
  public static void main(String[] args) {
    String FOO = "FOO";
    MtomService service = new MtomService()
    MtomPortType port = service.getMtomPortTypePort(new MTOMFeature()); 
    String result = null;
    result = port.echoBinaryAsString(FOO.getBytes());
    System.out.println( "Got result: " + result );
  }
}

添付ファイルのしきい値の設定

xs:binary64データをインラインまたは添付ファイルとして送信する場合に指定する添付ファイルのしきい値を設定できます。デフォルトの添付ファイルのしきい値は0バイトです。すべてのxs:binary64データは添付ファイルとして送信されます。

添付ファイルのしきい値を設定する方法は以下のとおりです。

Webサービスで、threshold属性を@java.xml.ws.soap.MTOMアノテーションに渡します。例:
```
@MTOM(threshold=3072)
```
Webサービスのクライアントで、しきい値をjavax.xml.ws.soap.MTOMFeatureに渡します。例:
```
MtomPortType port = service.getMtomPortTypePort(new MTOMFeature(3072));
```

上のどちらの例でも、メッセージが3KB以上だと添付ファイルとして送信されます。それ以外の場合、コンテンツはSOAPメッセージ本文の一部としてインラインで送信されます。

SOAP添付ファイルのストリーミング

注意:

com.sun.xml.ws.developer.StreamingDataHandler APIは、(https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/StreamingAttachment.htmlを参照。) Sun Microsystemsが提供するJAX-WS RIの拡張としてサポートされています。このAPIはWebLogicソフトウェアの一部としては提供されないため、変更される可能性があります。

MTOMと、javax.activation.DataHandlerおよびcom.sun.xml.ws.developer.StreamingDataHandler APIを使用すると、添付ファイルを含む着信SOAPメッセージを読み取る際に、デフォルト動作としてメッセージ全体をメモリーに読み込むかわりに、WebサービスでストリーミングAPIを使用することを指定できます。この機能を使用すると、SOAPメッセージが非常に大きいWebサービスのパフォーマンスを向上させることができます。

注意:

ストリームMTOMはメッセージの暗号化と組み合せて使用できません。

以降の節では、クライアント側およびサーバー側でSOAP添付ファイルのストリーミングを使用する方法について説明します。

クライアント側のサンプル

次のサンプルでは、クライアント側でSOAP添付ファイルのストリーミングを使用する方法を示します。

package examples.webservices.mtomstreaming.client;

import java.util.Map;
import java.io.InputStream;
import javax.xml.ws.soap.MTOMFeature;
import javax.activation.DataHandler;
import javax.xml.ws.BindingProvider;
import com.sun.xml.ws.developer.JAXWSProperties;
import com.sun.xml.ws.developer.StreamingDataHandler;

public class Main {
   public static void main(String[] args) {
      MtomStreamingService service = new MtomStreamingService();
      MTOMFeature feature = new MTOMFeature();
      MtomStreamingPortType port = service.getMtomStreamingPortTypePort(
         feature);
      Map<String, Object> ctxt=((BindingProvider)port).getRequestContext();
      ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192);
      DataHandler dh = new DataHandler(new
                  FileDataSource("/tmp/example.jar"));
      port.fileUpload("/tmp/tmp.jar",dh);

      DataHandler dhn = port.fileDownload("/tmp/tmp.jar");
      StreamingDataHandler sdh = {StreamingDataHandler)dh;
      try{
         File file = new File("/tmp/tmp.jar");
         sdh.moveTo(file);    
         sdh.close();
       }
       catch(Exception e){
          e.printStackTrace();
       }
  }
}

このサンプルでは以下を行っています。

WebサービスのクライアントでMTOMを有効にし、Webサービスのプロキシまたはディスパッチの作成時にパラメータとしてjavax.xml.ws.soap.MTOMFeatureのインスタンスを渡します。
MTOMストリーミング・クライアントでのHTTPチャンクを有効にすることで、HTTPストリーミングのサポートを構成します。
```
Map<String, Object> ctxt = ((BindingProvider)port).getRequestContext();
   ctxt.put(JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192);
```
port.fileUploadメソッドを呼び出します。
DataHandlerをStreamingDataHandlerにキャストし、StreamingDataHandler.readOnce()メソッドを使用して添付ファイルを読み込みます。

サーバー側のサンプル

次のサンプルでは、サーバー側でSOAP添付ファイルのストリーミングを使用する方法を示します。

package examples.webservices.mtomstreaming;

import java.io.File;
import java.jws.Oneway;
import javax.jws.WebMethod;
import java.io.InputStream;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlMimeType;
import javax.xml.ws.WebServiceException;
import javax.xml.ws.soap.MTOM;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import com.sun.xml.ws.developer.StreamingAttachment;
import com.sun.xml.ws.developer.StreamingDataHandler;

@StreamingAttachment(parseEagerly=true, memoryThreshold=40000L)
@MTOM
@WebService(name="MtomStreaming", 
            serviceName="MtomStreamingService",
            targetNamespace="http://example.org",
            wsdlLocation="StreamingImplService.wsdl")
@Oneway
@WebMethod
public class StreamingImpl {

   // Use @XmlMimeType to map to DataHandler on the client side
   public void fileUpload(String fileName,
                          @XmlMimeType("application/octet-stream") 
                          DataHandler data) {
      try {
            StreamingDataHandler dh = (StreamingDataHandler) data;
            File file = new File(fileName);
            dh.moveTo(file);
            dh.close();
      } catch (Exception e) {
            throw new WebServiceException(e);
   }

  @XmlMimeType("application/octet-stream")
  @WebMethod
  public DataHandler fileDownload(String filename)
  {
    return  new DataHandler(new FileDataSource(filename));
  }
}

このサンプルでは以下を行っています。

ストリームSOAP添付ファイルを構成するには、@StreamingAttachementアノテーションを使用します。詳細については、「SOAP添付ファイルのストリーミングの構成」を参照してください。
DataHandlerをマップするため、@XmlMimeTypeアノテーションを以下のように使用します。
- WSDLから始める場合は、生成されたSEIでxmime:expectedContentTypes="application/octet-stream"をDataHandlerにマップするために使用します。
- Javaから始める場合は、生成されたWSDLで適切なスキーマ・タイプを生成するために使用します。
DataHandlerをStreamingDataHandlerにキャストし、StreamingDataHandler.moveTo(File)メソッドを使用して添付されたコンテンツをファイルに格納します。

SOAP添付ファイルのストリーミングの構成

クライアント側およびサーバー側でのSOAP添付ファイルのストリーミングは、以下を指定することで構成できます。

大きな添付ファイルを格納するディレクトリ。
ストリーミング添付ファイルを徹底的に解析するかどうか。
メモリーに格納できる添付ファイルの最大サイズ(バイト)。添付ファイルのサイズが指定したバイト数を超える場合はファイルに書き込まれます。

サーバーでSOAP添付ファイルのストリーミングの構成

注意:

com.sun.xml.ws.developer.StreamingAttachment APIは、(https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/StreamingAttachment.htmlを参照。) Sun Microsystemsが提供するJDK 6.0の拡張としてサポートされています。このAPIはJDK 6.0キットの一部としては提供されないため、変更される可能性があります。

サーバーでSOAP添付ファイルのストリーミングを構成するには、エンド・ポイント実装で@StreamingAttachmentアノテーションを追加します。次のサンプルでは、ストリーミング添付ファイルを徹底的に解析すること(完全な添付ファイルの読取りまたは書込み)を指定し、メモリーのしきい値を4MBに設定しています。4MB以下の添付ファイルはメモリーに格納されます。

... 
import com.sun.xml.ws.developer.StreamingAttachment; 
import javax.jws.WebService;

@StreamingAttachment(parseEagerly=true, memoryThreshold=4000000L) 
@WebService(name="HelloWorldPortType", serviceName="HelloWorldService")
public class StreamingImpl {
}

クライアントでのSOAP添付ファイルのストリーミングの構成

注意:

com.sun.xml.ws.developer.StreamingAttachmentFeature APIは、(https://jax-ws-architecture-document.dev.java.net/nonav/doc/com/sun/xml/ws/developer/StreamingAttachment.htmlを参照してください。) Sun Microsystemsが提供するJDK 6.0の拡張としてサポートされています。このAPIはJDK 6.0キットの一部としては提供されないため、変更される可能性があります。

クライアントでSOAP添付ファイルのストリーミングを構成するには、StreamingAttachmentFeatureオブジェクトを作成し、PortTypeスタブ実装の作成時に引数として渡します。次のサンプルでは、大きなファイルを格納するディレクトリを/tmpに設定し、ストリーミング添付ファイルを徹底的に解析することを指定した上で、メモリーのしきい値を4MBに設定しています。4MB以下の添付ファイルはメモリーに格納されます。

... 
import com.sun.xml.ws.developer.StreamingAttachmentFeature; 
...
MTOMFeature mtom = new MTOMFeature();
StreamingAttachmentFeature stf = new StreamingAttachmentFeature("/tmp", true, 4000000L); 
MtomStreamingService service = new MtomStreamingService();
MtomStreamingPortType port = service.getMtomStreamingPortTypePort(
         mtom, stf); 
...