JAX-WS を使用した WebLogic Web サービスの高度な機能のプログラミング

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

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

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 型の添付ファイルを送信する手順をまとめます。

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

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

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

以下の節では、データ型のアノテーションを追加する方法について説明します。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 要素にアノテーションを追加します。

次のサンプルでは、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 を有効にする

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);

  }
}

クライアントで 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:binary 64 データが添付ファイルとして送信されます。

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

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

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

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

以降の節では、クライアント サイドおよびサーバ サイドで 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 = port.fileUpload(...);
      StreamingDataHandler sdh = {StreamingDataHandler)dh;
      InputStream in = sdh.readOnce();
      ...
      in.close();
      sdh.close();
  }
}

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

サーバ サイドのサンプル

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

package examples.webservices.mtomstreaming;

import java.io.File;
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 com.sun.xml.ws.developer.StreamingDataHandler;
...

@MTOM
@WebService(name="MtomStreaming", 
            serviceName="MtomStreamingService",
            targetNamespace="http://example.org",
            wsdlLocation="StreamingImplService.wsdl")
public class StreamingImpl {

   // クライアント サイドで @XmlMimeType から DataHandler へのマッピングに使用	
   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);
   }
}

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

SOAP 添付ファイルのストリーミングをコンフィグレーションする

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

サーバで SOAP 添付ファイルのストリーミングをコンフィグレーションする

サーバで 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 添付ファイルのストリーミングをコンフィグレーションする

クライアントで 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(
         feature, stf);
...