| Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS を使用した Web サービスの高度な機能のプログラミング 11g リリース 1 (10.3.1) B55543-01 |
|
 戻る |
 次へ |
| Oracle® Fusion Middleware Oracle WebLogic Server JAX-WS を使用した Web サービスの高度な機能のプログラミング 11g リリース 1 (10.3.1) B55543-01 |
|
戻る |
次へ |
以下の節では、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 型の添付ファイルを送信する手順をまとめます。
表 5-1 MTOM/XOP を使用してバイナリ データを送信する手順
| # |
手順 | 説明 |
|---|---|---|
|
1 |
MTOM 添付ファイルとして使用する予定のデータ型のアノテーションを追加する。(省略可能) |
使用するプログラミング モデルに応じ、Java クラスまたは WSDL にアノテーションを追加して、バイナリ データの送信に使用するコンテンツ タイプを定義できます。この手順は省略可能です。XML バイナリ型は、デフォルトでは Java |
|
2 |
Web サービスで MTOM の有効 |
「Web サービスで MTOM の有効化」を参照してください。 |
|
3 |
Web サービスのクライアントで MTOM の有効 |
「クライアントで MTOM の有効化」を参照してください。 |
|
4 |
添付ファイルのしきい値の設定 |
|
使用するプログラミング モデルに応じ、Java クラスまたは WSDL にアノテーションを追加して、バイナリ データの送信に使用する MIME コンテンツ タイプを定義できます。この手順は省略可能です。
次の表に、MIME コンテンツ タイプと Java 型のマッピングを定義します。型によっては、デフォルトのマッピングが存在します。デフォルトのマッピングが存在しない MIME コンテンツ タイプは、DataHandler にマップされます。
表 5-2 MIME コンテンツ タイプと Java 型のマッピング
| MIME コンテンツ タイプ | Java 型 |
|---|---|
image/gif |
java.awt.Image |
image/jpeg |
java.awt.Image |
text/plain |
java.lang.String |
text/xml または application/xml |
javax.xml.transform.Source |
*/* |
javax.activation.DataHandler |
以下の節では、データ型のアノテーションを追加する方法について説明します。Java から始める方法と、WSDL から始める方法があります。
バイナリ データの送信に使用するコンテンツ タイプの定義を Java から始める場合は、バイナリ データを保持するフィールドに @XmlMimeType アノテーションを追加します。
バイナリ データを保持するフィールドは、DataHandler 型にする必要があります。
次のサンプルに、バイナリ データを保持する Java クラス内のフィールドにアノテーションを追加する方法を示します。
@WebMethod
@Oneway
public void dataUpload(
@XmlMimeType("application/octet-stream") DataHandler data)
{
}
バイナリ データの送信に使用するコンテンツ タイプの定義を 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"/>
次の節で説明しているように、アノテーションまたは WS-Policy ファイルを使用して 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 アノテーションに加えて、WebLogic JAX-WS Web サービスでの MTOM/XOP のサポートはあらかじめパッケージ化された WS-Policy ファイル Mtom.xml を使用して実装されます。WS-Policy ファイルは、(http://www.w3.org/TR/ws-policy) で説明されている WS-Policy 仕様に準拠しています。この仕様では、Web サービスのポリシー (この場合は、バイナリ データ送信のための MTOM/XOP の使用) を記述および通信する汎用モデルおよび XML 構文を提供しています。Web サービス WSDL の types セクションへの、あらかじめパッケージ化された Mtom.xml WS-Policy ファイルのインストールは、次のようになります (参考のためにのみ掲載しています。このファイルを変更することはできません)。
<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 ファイルを関連付けることができます。動的 WSDL に、必須である Mtom.xml ファイルへの参照が確実に含まれるよう、必ず attachToWsdl=true 属性も指定します。下記の例を参照してください。
デプロイメント時に Web サービスと Mtom.xml WS-Policy ファイルを関連付けるには、デプロイメント直前に types セクションにポリシーを追加し、WSDL を修正します。
また、Administration Console を使用して実行時にファイルを添付できます。詳細については、『Oracle Fusion Middleware Oracle WebLogic Server Administration Console ヘルプ』の「WS-Policy ファイルと Web サービスとの関連付け」を参照してください。この節では、JWS アノテーションの使用方法について説明します。
次の簡単な JWS ファイルの例は、あらかじめパッケージ化された Mtom.xml ファイルを Web サービスに適用するために、JWS ファイルで @weblogic.jws.Policy アノテーションの使用方法を示します。（該当するコードは太字で示してあります）。
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); }
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 メッセージ本文の一部としてインラインで送信されます。
|
注意 : 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 {
// @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);
}
@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 添付ファイルのストリーミングは、以下を指定することでコンフィグレーションできます。
大きな添付ファイルを格納するディレクトリ。
ストリーミング添付ファイルを徹底的に解析するかどうか。
メモリに格納できる添付ファイルの最大サイズ (バイト)。添付ファイルのサイズが指定したバイト数を超える場合はファイルに書き込まれます。
|
注意 : 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 { }
|
注意 : 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); ...
