A メッセージ・コンテキスト
この付録では、Service Busメッセージ・コンテキスト・モデルとメッセージ・フローで使用する事前定義されたコンテキスト変数について説明します。
この章の内容は次のとおりです。
A.1 メッセージ・コンテキスト・モデル
Service Busメッセージ・コンテキストは、Service Busでメッセージがルーティングされるときに、メッセージ・コンテキストとメッセージに関する情報を保持する一連のプロパティです。
これらのプロパティは、コンテキスト変数と呼ばれます。たとえば、サービス・エンドポイントは、事前定義されたコンテキスト変数によって表されます。Service Busは、ユーザー定義のコンテキスト変数もサポートします。
メッセージ・コンテキストは、XMLスキーマによって定義されます。通常は、XQuery式を使用して、パイプライン・サービスのコンテキスト変数を操作します。
A.2 事前定義されたコンテキスト変数
事前定義されたコンテキスト変数のタイプは、メッセージ関連の変数、inboundおよびoutbound変数、$operation変数、fault変数に分けられます。
表A-1に、事前定義されたコンテキスト変数を示します。
ノート:
メッセージ・コンテキスト・スキーマは、メッセージ・コンテキスト変数の要素の型を指定します。
メッセージ・コンテキスト変数の要素の型については、「メッセージ・コンテキスト・スキーマ」を参照してください。
表A-1 Service Busの事前定義されたコンテキスト変数
| コンテキスト変数 | 説明 | 関連項目 |
|---|---|---|
|
header |
SOAPメッセージの場合、 メッセージのタイプがSOAP以外の場合、 |
|
|
body |
この変数は、次に説明するようにメッセージ・タイプに応じて異なります。
|
|
|
attachments |
メッセージのMIME添付。 |
|
|
inbound |
インバウンド・トランスポート・ヘッダーとメッセージを受信したプロキシ・サービスについての情報。 |
|
|
outbound |
アウトバウンド・トランスポート・ヘッダーとメッセージが送信されるターゲット・サービスについての情報。 |
|
|
operation |
パイプラインで呼び出される操作 |
|
|
fault |
メッセージの処理中に発生したエラーに関する情報。 |
|
|
messageId |
トランスポート・プロバイダ固有のメッセージIDです。このIDは、Service Busランタイムを通過するその他のメッセージからメッセージを一意に識別できることが必要です。ただし、この値は一意である必要はありません。 |
A.3 メッセージ関連の変数
メッセージ関連の変数である$header、$bodyおよび$attachmentsは、Service Busのメッセージ・フローでのメッセージの標準書式を表します。
これらの変数は、パイプラインが受信したメッセージ・コンテンツを使用して初期化され、他のサービスにルーティングまたはパブリッシュされる送信メッセージを作成するために使用されます。メッセージの処理の一部としてメッセージを変更するには、これらの変数を変更する必要があります。
メッセージ・ペイロード(つまり、ヘッダーや添付を除くメッセージ・コンテンツ)は、$body変数に格納されます。送信メッセージに含める変数のコンテンツは、Service Busからメッセージがディスパッチ(パブリッシュまたはルーティング)される時点で決定されます。この決定は、ターゲットのエンドポイントがSOAPメッセージを受信するか非SOAPメッセージを受信するかによって異なります。
-
SOAPメッセージが要求される場合は、
$header変数と$body変数がSOAPエンベロープで結合され、メッセージが作成されます。 -
非SOAPメッセージが要求される場合は、
$body変数のBody要素のコンテンツによってメッセージ全体が構成されます。 -
いずれの場合も、サービスが添付を受信するときは、生成されたメッセージと
$attachments変数からMIMEパッケージが作成されます。
A.3.1 header変数
$header変数には、メッセージに関連付けられているSOAPヘッダーが格納されます。$header変数は、下位要素にヘッダーを含む<SOAP:Header>要素を参照します。プロキシ・サービスがSOAP 1.2の場合、$header変数にはSOAP 1.2 Header要素が格納されます。非SOAPメッセージまたはヘッダーがないSOAPメッセージの場合、<SOAP:Header>要素は空になり、下位要素を持ちません。
A.3.2 body変数
$body変数はコアのメッセージ・ペイロードを表し、常に<SOAP:Body>要素を参照します。プロキシ・サービスがSOAP 1.2の場合、$bodyにはSOAP 1.2 Body要素が格納されます。SOAPメッセージでも非SOAPメッセージでも、コアのペイロードは同じ変数とパッケージで使用できます。つまり、<SOAP:Body>要素でラップされます。
-
SOAPメッセージの場合は、SOAP本文がエンベロープから抽出され、
$body変数に割り当てられます。 -
バイナリ以外の非SOAPメッセージの場合は、新しく作成された
<SOAP:Body>要素内にメッセージ・コンテンツ全体が挿入されます。 -
バイナリ・メッセージの場合は、メッセージ・コンテンツが
$body変数に挿入されるのではなく、<binary-content/>参照要素が作成され、<SOAP:Body>要素に挿入されます。バイナリ・コンテンツの処理方法を学習するには、「body変数とattachments変数内のバイナリ・コンテンツ」を参照してください。 -
Javaオブジェクトの場合は、
<java-content/>参照要素が作成され、<SOAP:Body>要素に挿入されます。Javaコンテンツの処理方法を学習するには、「body変数内のJavaコンテンツ」を参照してください。
A.3.3 attachments変数
$attachments変数には、メッセージに関連付けられた添付が格納されます。attachments変数は、XMLスキーマで定義されます。これは、単一のルート・ノードである<ctx:attachments>と、各添付の<ctx:attachment>下位要素で構成されます。この下位要素には、添付に関する情報(MIMEヘッダーから派生)と、添付コンテンツおよび添付のカスタム・ヘッダーが含まれます。
他のメッセージ関連の変数と同様に、$attachmentsは常に設定されます。ただし、添付がない場合は、$attachments変数は空の<ctx:attachments>要素で構成されます。各添付の$attachments変数には、次のものが含まれます。
-
添付、添付がXMLの場合。
-
参照XML、添付がバイナリの場合。
-
テキスト、添付がテキストの場合。
ノート:
メッセージ・コンテキスト・スキーマは、メッセージ・コンテキスト変数の要素の型を指定します。
各attachment要素には、表A-2に示す一連の下位要素が含まれます。
表A-2 attachments変数の下位要素
| attachments変数の要素 | 説明 |
|---|---|
|
Content-ID |
添付を識別するグローバルに一意の参照。型は |
|
Content-Type |
添付のメディアのタイプとサブタイプ。型は |
|
Content-Transfer-Encoding |
添付のエンコード方法のインジケータ。型は |
|
Content-Description |
コンテンツの説明。型は |
|
Content-Location |
添付を識別するローカルに一意のURIベースの参照。型は |
|
Content-Disposition |
受信者による添付の処理方法のインジケータ。型は |
|
user-headers |
添付のカスタムMIMEヘッダーのリスト。この要素には、各カスタム・ヘッダーを定義する1つ以上の |
|
user-header |
カスタムMIMEヘッダー。 |
|
body |
添付データを保持します。型は |
型なしのbody要素を除き、すべてのその他の要素には、MIMEと同じ方法で解釈される文字列値が含まれます。たとえば、Content-Type要素の有効な値には、text/xmlおよびtext/xml; charset=utf-8が含まれます。
添付の解析は再帰的ではありません。添付のContent-Typeがmultipart/...の場合、body要素には元のアンパックのMIMEコンテンツがバイトのストリームとして保持され、添付の下位要素は含まれません。MIMEストリームにはバイナリ・データが含まれることがあり、その場合このストリームは<binary-content>参照要素で表します。バイナリ・コンテンツの処理方法を学習するには、「body変数とattachments変数内のバイナリ・コンテンツ」を参照してください。
Content-Typeがmultipart/form-dataであるメッセージは、実行時に次のように作成されます。
-
インバウンド: 受信したインバウンド
multipart/form-dataタイプのメッセージのすべての部分が$attachments変数に割り当てられます。$body変数は空のままになります。 -
アウトバウンド: アウトバウンド
multipart/form-dataタイプのメッセージのコンテンツが$attachments変数のコンテンツから作成されます。$headerまたは$bodyからは何も含まれません。ノート:
インバウンド・メッセージが
multipart/form-data以外のmultipartタイプ(multipart/relatedなど)で、アウトバウンド・メッセージがmultipart/form-dataの場合、インバウンド・ルート・パートのヘッダーとコンテンツを明示的に保持する必要があります。そうしないと、パススルーされません。
Service Busでは、EJB、TuxedoまたはDSPサービスへの添付の送信はサポートしていません。
A.3.4 メッセージ・タイプおよびコンテキスト変数
これらの変数は、SOAPヘッダー要素、SOAP本体要素、およびMIME添付を含むラッパー変数です。コンテキストによって、すべてのメッセージがSOAPメッセージであり、非SOAPメッセージがこのパラダイムにマップされるように見えます。次の表に、様々なメッセージ・タイプのマッピングを示します。Javaコンテンツの詳細は、「body変数内のJavaコンテンツ」を参照してください。
表A-3 メッセージのマッピング
| メッセージ・タイプ | マッピング |
|---|---|
|
XML |
|
|
binary |
|
|
MFL |
ドキュメントは、XMLとの相互変換が透過的に行われ、 |
|
text |
|
|
ファイル、FTPおよび電子メール |
参照渡しドキュメントの場合、 |
|
SOAP |
|
A.3.5 body変数とattachments変数内のバイナリ・コンテンツ
$body変数と$attachments変数では、テキスト・ベース、XMLベースおよびMFLベースのコンテンツがXML要素内に直接挿入されます。バイナリ・データの場合、XMLで使用できないバイト値が含まれることがあるため、Service Busではバイナリ・コンテンツはXML要素内に挿入されません。したがって、バイナリ・コンテンツは操作できませんが効率的に処理されます。
バイナリ・コンテンツが受信されると、Service Busランタイムによってバイナリ・コンテンツがメモリー内ハッシュ表に格納され、そのコンテンツへの参照がXML (bodyまたはattachments)要素に挿入されます。この参照は、次のXMLスニペットで表されます。
<binary-content ref="..."/>
このref属性に、バイナリ・コンテンツを一意に識別するURIまたはURNを指定します。このXMLは、パイプライン・ペア、ブランチまたはルート・ノードで他のコンテンツと同様に操作できますが、影響を受けるのは、元のバイナリ・コンテンツではなく参照のみです。
たとえば:
-
$body変数のバイナリ・コンテンツを添付にコピーするには、参照XMLを添付要素のbody下位要素にコピーします。 -
2つの異なる添付のバイナリ・コンテンツを置き換えるには、参照XMLスニペットまたはref属性の値を置き換えます。
メッセージがService Busからディスパッチされると、参照XMLのURIを使用して、関連バイナリ・コンテンツが送信メッセージ内に復元されます。アウトバウンド・メッセージの作成方法については、「ディスパッチするメッセージの作成」を参照してください。
クライアントと特定の転送(特に、電子メール、ファイル、FTP)では、この同じ参照XMLを使用して参照渡しを実装できます。この場合、実行時のプロキシ・サービスではなく転送またはクライアントによって、参照XMLが作成されます。また、ref属性内のURIの値は、参照XMLを作成するユーザーによって指定されます。参照XMLが実行時のプロキシ・サービスによって作成されない場合(特に、URIの参照先が、内部で管理されているバイナリ・コンテンツであると認識されない場合)、URIはService Busにより逆参照されず、送信メッセージにコンテンツが挿入されません。
A.3.5.1 ビジネス・プロセスへの添付付きSOAPの送信
Service BusからBPELビジネス・プロセスへ添付付きSOAP (SwA)を送信し、XPath関数ora:getAttachmentContent('inputVariable','bin','/bin')を使用してBPEL内の複数の添付を取得するには、必ず次の手順を実行してください。
-
複数の添付に
Content-ID添付変数を設定します。 -
href属性を使用して、プライマリSOAPエンベロープ内の添付を参照します。
場合によっては、cid:情報がhref属性にない場合があります。
次に、例を示します。
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
start="<rootpart@example.com>"
Content-Description: This is the optional message description.
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <rootpart@example.com>
<?xml version='1.0' ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body xmlns:types="http://example.com/mimetypes">
<m:SendClaim xmlns:m="http://example.com/mimewsdl“>
<ClaimDetail>
<Name>...</Name>
<!-- additional claim details -->
</ClaimDetail>
<ClaimPhoto href="cid:4d7a5fa2-14af-451c-961b5c3abf786796@example.com"/>
</m:SendClaim>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
--MIME_boundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <4d7a5fa2-14af-451c-961b5c3abf786796@example.com>
...MIME attachment of binary photograph...
--MIME_boundary—
A.3.6 body変数内のJavaコンテンツ
Service Busパイプラインでは、Javaコールアウト・アクションへの入力および出力として、Javaオブジェクトをサポートしています。Javaコールアウトから返されたPOJOはパイプラインにキャッシュされ、そのキーは<java-content ref="cid:kkkkeeeeyyyy"/>の形式のXMLメッセージにラップされて返されます。ここで、cid:kkkkeeeeyyyyは、生成アクションによって自動的に生成されたキーであり、パイプラインのPOJOリポジトリにあるオブジェクトの索引を指定するために使用されます。後続するすべてのアクションに対して、このXMLが変更されずに引数として渡されます。
構成時にはPOJO変数のコンテンツは、パイプライン・アクションからは直接アクセスできません。かわりに、コンテンツは次の方法で操作できます。
-
コンテンツのメタデータ(コンテンツのキー)は、他のXML(たとえば、
$pojo/java-content/@refのようなXQuery)と同様に処理できます。これはロギングやデバッグに役立つことがありますが、オブジェクトのコンテンツに直接アクセスすることはできません。 -
(パイプライン内で)自動的にPOJO型として指定される新しい変数にコンテンツを割り当てることができます。オブジェクト自体にアクセスすることはできません。XMLスニペット
<java-content.../>がソース変数からターゲット変数にコピーされます。 -
コンテンツは、別の適切なアクション(Javaコールアウトなど)に変数(たとえば、
$pojo)として渡すことができます。オブジェクト自体にアクセスすることはできません。引数は、実際のオブジェクトに自動的に逆参照されます。
(<java-content />内に) Javaオブジェクトのキーを保持しているすべての変数を削除した場合、または<java-content />スニペットを指しているすべてのXPathを削除した場合、JavaオブジェクトはパイプラインのPOJOリポジトリから削除されます。
A.3.7 bodyコンテンツのストリーミング
メッセージ・コンテンツを処理する際に、パイプラインによってコンテンツをメモリーにロードするのではなく、コンテンツをストリームするように指定できます。パイプラインのコンテンツ・ストリーミングを有効にするときは、メッセージ処理時の中間ステップとして、ストリーミングされたコンテンツをメモリーとディスク・ファイルのどちらにバッファするかを指定します。これらの一時ファイルの作成は、パフォーマンスに影響を及ぼすことがあります。一時ファイルの保護については、『Oracle Service Busの管理』のbodyコンテンツをストリーミングする場合の一時ファイルの保護に関する項を参照してください。
ストリーミング・オプションを有効にした場合、コンテンツ・ストリーミングは$body変数のみに適用されます。
一般に、コンテンツ・ストリーミングを使用するのは次のような場合です。
-
サイズの大きいコンテンツのメッセージを処理する場合。「コンテンツ・ストリーミングを使用する際のベスト・プラクティス」のガイドラインを参照してください。
-
Service Busがペイロードにアクセスする回数が少ない場合。
-
トランスフォーメーションのないコンテンツ・ベースのルーティングの場合。コンテンツ・ストリーミングを使用すると、部分解析の利点が得られるため、パフォーマンスが向上します。
A.3.7.1 コンテンツ・ストリーミングを使用する際のベスト・プラクティス
コンテンツのストリーミングを有効にするには、次のガイドラインと推奨事項に従ってください。
-
サイズの大きいメッセージを処理するためにストリーミングを有効にした場合、
$bodyメッセージ・コンテキスト変数について、挿入、置換、名前変更、for each、検証、および削除の各アクションを使用することはできません。これらのアクションでは、入力変数をメモリー内で完全に実体化する必要がありますが、完全な実体化はコンテンツ・ストリーミング・オプションと互換性がないためです。 -
次のパイプライン・アクションでは、サイズの大きい
$bodyのXQuery変換またはXSL変換の結果を使用できます。-
割当て、挿入および置換の各アクション: この結果を使用して、別のコンテキスト変数(
$body以外)の値を更新します。ただし、式の結果が完全に実体化でき、メッセージ・コンテキストに格納できる小さなサイズであることを確認する必要があります。 -
Javaコールアウト: この結果を使用して、入力引数を渡します。Javaコールアウトへのすべての入力は完全に実体化されます。したがって、入力として使用する式の結果は、完全に実体化できる小さなサイズであることが必要です。
-
MFL変換: この結果を使用して、入力をXML Beanとしてあらかじめ実体化せずに、サイズの大きいペイロードを変換します。MFL変換への入力としてサイズの大きい
$bodyを使用する場合は、メッセージ・サービスをバイナリ・メッセージ・タイプのパイプラインとして宣言します。メッセージ・サービスをテキスト・メッセージ・タイプのパイプラインとして宣言すると、変換の入力ストリームを取得するために$bodyが完全に実体化されます。 -
アラート、ログおよびレポートの各アクション: この結果を使用して、サイズの大きい
$bodyのXQuery変換またはXSL変換の結果を報告します。 -
サービス・コールアウト
-
-
XSLトランスフォーメーションでは、トランスフォーメーションを実行するためにすべての入力が完全に実体化されます。したがって、入力が完全に実体化でき、XSLTプロセッサが処理できる小さなサイズであることを確認する必要があります。
-
サイズの大きいMFL入力を使用する場合、MFLステージ・アクションではなく、MFLサービスを使用してMFLからXMLへの変換を実行する必要があります。
-
コンテンツが完全に実体化されると、メモリー不足による例外が発生する可能性があり、コンテンツを表示することによって、テスト・コンソール・ウィンドウの処理速度が低下するので、テスト・コンソールを使用して、サイズの大きいコンテンツのメッセージでパイプラインをテストしないでください。
-
XQueryを作成するときは、適切な索引を使用して部分解析を実行できるようにします。
たとえば、入力ストリーム全体を使用する
$body/*:DateTimeStructを使用するのではなく、次のいずれかを使用します。($body/*:DateTimeStruct)[1]
または
$body[1]/*:DateTimeStruct[1]
索引を使用することにより、1つ目の
DateTimeStruct要素までのコンテンツのみが解析されます。 -
複数のコンシューマ(式)がアクセスする各変数が実体化されるため、XQueryを作成するときに、次のような文を記述しないようにしてください。
let $labdata1 := $body/* return <HEADER>{ $labdata1/HEADER/@*, $labdata1/HEADER/node() }</HEADER>この場合、
$labdata1はルート要素なしにドキュメント全体にバインドされるため、XQueryエンジンがこれを実体化しようとするとメモリー不足になります。この問合せを変更して必要以上に実体化されないようにする1つの方法として、
/HEADERパス式をlet句内に移動します。let $labdata1 := $body/*/HEADER ...
この場合、XQueryエンジンは
HEADER要素のみを実体化します。 -
実行時に、サイズの大きいメッセージの処理は、基になるトランスポートの制限と制約を受けます(メッセージ・サイズの処理の制限など)。サイズの大きいメッセージを受け入れるトランスポートの容量を制限するJVMおよびRMIの設定に注意してください。
A.3.8 添付のストリーミング
メッセージの添付を処理する際に、添付をメモリーにバッファリングしてXMLとして解析するのではなく、MIME添付をディスクにページングしてからコンテンツをストリーミングするように指定できます。サイズの大きい添付を扱う場合は、この方法が特に効果的です。この方法を使用すると、ヘッダーのみがバッファリングされ、残りのメッセージ・ペイロードは、小さい複数の部分を同時に読み込むことができるストリームとして公開されます。ストリーミングされた転送により、サイズの大きいメモリー・バッファが不要になるため、サービスのスケーラビリティが向上します。
ノート:
Service Busは、電子メールまたはWSトランスポートの添付のストリーミングをサポートしません。
パイプラインに対して有効になっている場合、設定はインバウンド・リクエスト・メッセージの処理に適用されます。HTTPビジネス・サービスの場合、設定はアウトバウンド・レスポンス・メッセージの処理に適用されます。アウトバウンド・リクエスト・メッセージをディスパッチすることができる次のアクションは、添付のストリーミングをサポートします。
-
ルート、動的ルーティング、およびルート表
-
パブリッシュ、動的パブリッシュ、およびパブリッシュ表
ストリーミングが有効な場合、バイナリ、テキストおよびXMLを含むすべての添付が不透明なデータとして処理されます。つまり、添付のXMLコンテンツに基づいてXQuery式またはXPath式を実行することはできません。
A.3.8.1 インバウンド・メッセージの処理
Service Busがインバウンド・メッセージを受信したとき、添付のストリーミングが構成されている場合は、各MIME添付のコンテンツはディスク上の別々のファイルに保存されます。各添付の標準MIMEヘッダー(これには、Content-ID、Content-Type、Content-Transfer-Encoding、Content-Description、Content-Location、およびContent-Disposition(指定されている場合)が含まれます)をattachment要素の下に追加するように、$attachments変数の値が設定されます。
body子要素には、ソース・リポジトリ内の対応するソースを参照する単一のbinary-content子要素が含まれます。
たとえば、$attachments変数は次のようになります。
<con:attachments xmlns:con="http://www.oracle.com/wli/sb/context">
<con:attachment>
<con:Content-Type>image/jpeg</con:Content-Type>
<con:Content-ID>
<1.urn:uuid:BFB7D745CBAF21BA5B12023554608963@apache.org>
</con:Content-ID>
<con:Content-Transfer-Encoding>
binary
</con:Content-Transfer-Encoding>
<con:body>
<con:binary-content ref="cid:23976580:1183dd6aab9:-7fe0"/>
</con:body>
</con:attachment>
</con:attachments>
これは添付のコンテンツ・タイプに関係なく実行されます。つまり、たとえばtext/xml添付は、image/jpeg添付と同じように、バイナリ・コンテンツ要素を含む不透明なバイナリ・データとして扱われます。
このスタイルのメッセージ処理は、添付がストリーミングされない場合とは異なります。添付がストリーミングされない場合は、text/xmlやtext/plainなどの特定のファイル・タイプが認識されて、添付のXML body要素(XMLコンテンツを格納するため)またはテキスト・コンテンツの初期化に使用されます。
A.3.8.2 アウトバウンド・レスポンス・メッセージの処理
Service Busがアウトバウンド・メッセージを処理するとき、添付をストリーミングするように構成されている場合は、各MIME添付のコンテンツはディスク上の別々のファイルに保存されます。Service Busは、インバウンド・リクエストの場合と同様に$attachmentsメッセージ・コンテキスト変数を初期化します(「インバウンド・メッセージの処理」を参照してください)。
A.3.9 XOP/MTOMサポート
Service Busでは、XOP/MTOM形式のインバウンド・メッセージをデコードして解析し、必要に応じてXOP/MTOM形式を使用してレスポンスを送信するように、パイプラインを構成できます。また、アウトバウンド・メッセージをXOP/MTOM形式でエンコードするようにビジネス・サービスを構成できます。
Service Busは、着信XOP/MTOMペイロードを受け入れてデコードするために、次のバインディング・タイプを持つパイプラインをサポートしています。
-
任意のXML
-
メッセージング(XML)
-
任意のSOAP
-
WSDLベース
XOP/MTOMペイロードを受信するその他のサービス・バインディング・タイプのパイプラインは、MIMEマルチ・パート・リクエストと同じようにペイロードを処理し、MTOM固有の処理は行いません。
また、次のService BusトランスポートはXOP/MTOMをサポートします。
-
HTTP/S
-
ローカル
-
SB (連鎖しているService Busドメインなど、適用可能な場合)
Service Busは、次のアウトバウンド・メッセージをディスパッチできるすべての既存アクションをサポートします。
-
ルート、動的ルーティング、およびルート表
-
パブリッシュ、動的パブリッシュ、およびパブリッシュ表
-
サービス・コールアウト
Service Busでは、MTOMおよび添付付きのSOAP (SwA)の組合せはサポートされません。
A.3.9.1 パイプラインのXOP/MTOM
パイプラインでXOP/MTOM形式のインバウンド・メッセージをデコードして解析し、必要に応じてXOP/MTOM形式を使用してレスポンスを送信できます。「XOP/MTOMサポート」が有効になっている場合は、$bodyメッセージ・コンテキスト変数のバイナリ・データを処理する方法を次のオプションからさらに選択します。
-
「参照によるバイナリ・データを含む」(デフォルト): 「参照によるバイナリ・オプション」を参照してください。
-
「値によるバイナリ・データを含む」: 「値によるバイナリ・オプション」を参照してください。
「XOP/MTOMサポート」がパイプラインに対して有効になっている場合は、すべてのインバウンド・メッセージがMTOM形式である必要はありません。かわりに、この設定では、MTOM形式のメッセージが到着したときに、パイプラインでそれを適宜処理する必要があることを指定します。「XOP/MTOMサポート」が有効になっていないパイプラインがMTOM形式のメッセージを受信すると、サービスはメッセージを拒否して実行時エラーを発行します。
A.3.9.1.1 参照によるバイナリ・オプション
バイナリ・データに直接アクセスする必要がある場合、たとえばJavaコールアウトまたはMessage Format Language (MFL)変換にデータを渡す場合は、「参照によるバイナリ・データを含む」を使用します。
参照によるバイナリ・オプションが選択されている場合は、Service Busはインバウンド・メッセージのルートを解析してxop:Includeタグの存在をチェックします。これらのタグが検出された場合、タグはバイナリ・リポジトリ内の対応するソースへの参照を含むctx:binary-content要素に変換されます。結果としてのドキュメントは$bodyメッセージ・コンテキスト変数によって表されます。対照的に、$attachmentsメッセージ・コンテキスト変数は情報を含みません(nullです)。
つまり、パイプライン・アクションが$bodyメッセージ・コンテキスト変数のコンテンツにアクセスした場合、アクションはxop:Include要素を検出しないかわりに、ctx:binary-content要素を使用して動作します。
パイプラインがレスポンスを返信する必要がある場合、バインディング・レイヤーはctx:binary-content参照をメッセージのルートにあるxop:Includeタグに置換し、対応する各バイナリ・コンテンツ参照に別々のMIME部分を追加して、XOP/MTOMパッケージ・レスポンスを作成します。
A.3.9.1.2 値によるバイナリ・オプション
「値によるバイナリ・データを含む」は次の場合に使用します。
-
MTOMとMTOM以外のサービスの間にブリッジを作成する場合。たとえば、MTOM対応でないサービスにルーティングされるリクエストを受信するMTOM対応のパイプラインについて考えます。このオプションを使用して、XML内のバイナリ・データをBase64エンコード形式で送信するために既存の標準に準拠できます。
-
バイナリ・データの代わりにbase64binary要素の使用を必要とするXMLスキーマに照らしてメッセージのコンテンツを検証する場合。
「値によるバイナリ・データを含む」オプションが選択されている場合は、Service BusがインバウンドMIMEメッセージのルートを解析してxop:Includeタグの有無をチェックします。該当するタグが検出された場合、対応するMIME部分の本体(バイナリ・データ)はBase64でエンコードされ、結果としてのテキストが$bodyメッセージ・コンテキスト変数のxop:Includeタグを置換します。
対照的に、$attachmentsメッセージ・コンテキスト変数は情報を含みません(nullです)。
A.3.9.2 ビジネス・サービスのXOP/MTOM
ビジネス・サービスを有効にすると、アウトバウンド・メッセージをXOP/MTOM形式でエンコードできます。「XOP/MTOMサポート」が有効になっている場合は、$headerおよび$bodyメッセージ・コンテキスト変数のバイナリ・データを処理する方法を次のオプションからさらに選択します。
-
参照によるバイナリ・データを含む: (デフォルト)アウトバウンド・レスポンス・メッセージでの
$bodyメッセージ・コンテキスト変数の設定時に、xop:Include要素をctx:binary-content要素に置換します。 -
値によるバイナリ・データを含む: アウトバウンド・レスポンス・メッセージで、
$bodyメッセージ・コンテキスト変数の設定時にxop:Include要素を対応するバイナリ・データのBase64エンコード・テキスト・バージョンで置換します。
「XOP/MTOMサポート」がビジネス・サービスに対して有効になっている場合は、すべてのアウトバウンド・メッセージがMTOM形式である必要はありません。かわりに、この設定はビジネス・サービスがMTOMペイロードを処理できることを指定します。
A.3.9.2.1 アウトバウンド・メッセージのXOP/MTOM
ビジネス・サービスで「XOP/MTOMサポート」が有効になっている場合、Service Busは$bodyメッセージ・コンテキスト変数のコンテンツを調べてctx:binary-content要素を検索します。要素がある場合、Service Busはctx:binary-contentをxop:Include要素およびペイロードの対応するMIME部分に置換して、XOP/MTOM MIMEパッケージを作成します。
XOP/MTOMが有効で本体にバイナリ・コンテンツが含まれている場合、コンテンツのサイズに関係なく(たとえば、1KBより小さい場合でも) Service Busは常にXOP/MTOMを使用します。Service BusはMTOMとSwAの組合せをサポートしないため、ビジネス・サービスへのアウトバウンド・リクエストをディスパッチする必要があり、次の条件に該当する場合、システムはランタイム例外をスローします。
-
ビジネス・サービスのXOP/MTOMが有効になっています。
-
$attachmentsメッセージ・コンテキスト変数がnullではありません。
A.3.9.3 XOP/MTOM添付のストリーミング
サービスでXOP/MTOMが有効になっている場合、前の説明に示すように、Service Busはメッセージの$headerと$body内の要素を自動的に変更します。XOP/MTOMメッセージを変更する必要があるため、Service Busはメッセージ$headerとメッセージ$bodyのストリーミングをサポートしません。
ただし、添付が大きいためにメモリー不足のエラーを発生させるような場合、XOP/MTOMメッセージのバイナリ添付を、Service Busヒープ(デフォルト)ではなく、ディスクに直接ストリーミングする必要があります。
ノート:
XOP/MTOM添付は、メッセージの$attachments変数では送信されません。前述のとおり、それらはメッセージ$body内に含まれるかまたは$bodyメッセージから参照されます。
XOP/MTOMメッセージの添付を直接ディスクにストリーミングするには、サービス構成で次の設定を使用します。
-
XOP/MTOMの「参照によるバイナリ・データを含む」オプションを使用します。このオプションでは、
$body内にバイナリ・データが直接含まれ、XOP/MTOMのサポートにはストリーミングできません。 -
「参照によるバイナリ・データを含む」が選択されている場合は、「添付のディスクへのページング」オプション(HTTPトランスポートのみ)も選択できます。「添付のディスクへのページング」が選択されている場合は、Service Busはメモリーではなくディスク上のバイナリ添付を参照するXOP/MTOMメッセージを生成します。
ノート:
最適なパフォーマンスを得るためにはメモリー内の添付を参照する方法が推奨されるので、メモリー不足のエラーを発生させるようなサイズの大きい添付を送信する特別な必要性がある場合のみ「添付のディスクへのページング」オプションを使用します。
A.3.10 カスタムMIMEヘッダー
Service Busは、インバウンド・リクエスト/アウトバウンド・レスポンスおよびアウトバウンド・リクエスト/インバウンド・レスポンスのメッセージ・パターンの両方のカスタムMIMEヘッダーをサポートしています。インバウンド・メッセージにカスタム・ヘッダーが含まれ、メッセージがパイプラインに読み込まれると、次の例に示すようにカスタム・ヘッダー情報がXMLのuser-headers要素に表示されます。
<con:user-headers>
<con:user-header name="MyCustomHeader" value="Custom Header Value" />
</con:user-headers>
アウトバウンド・リクエストとインバウンド・レスポンスの場合、Service Busはアウトバウンド・リクエスト・メッセージの作成時に任意のuser-header要素を対応するMIMEパートのカスタム・ヘッダーに変換します。user-header要素は、(解凍済)インバウンド・リクエストの結果にでき、挿入、置換または割当てアクションなどの明示的パイプライン・アクションに手動で追加できます。
A.4 inbound変数とoutbound変数
$inboundコンテキスト変数と$outboundコンテキスト変数には、インバウンド・エンドポイントとアウトバウンド・エンドポイントに関する情報が格納されます。
$inbound変数にはリクエスト・メッセージを受信したプロキシ・サービスに関する情報が格納され、$outbound変数にはメッセージの送信先であるターゲット・ビジネス・サービスに関する情報が格納されます。
$outbound変数は、ルート・ノードのルート・アクションとパブリッシュ・アクションで設定されます。$outboundを変更するには、ルート・ノードでリクエスト・アクションとレスポンス・アクションを構成し、パブリッシュ・アクションでリクエスト・アクションを構成します。
注意:
$inboundコンテキスト変数および$outboundコンテキスト変数に行う変更の一部は、実行時に保持されません。つまり、特定のヘッダーおよびメタデータは、Service Busランタイムによって上書きまたは無視されます。トランスポート・ヘッダーとサービス・コールアウト・アクションを使用してトランスポート・ヘッダーとメタデータを設定する場合や、テスト・コンソールを使用してサービスをテストする場合にもこの制限は当てはまります。
制限のあるヘッダーとメタデータの詳細は、「テスト・コンソールでのランタイムによるトランスポート設定の使用方法」を参照してください。ルート・ノードのリクエスト・アクションまたはレスポンス・アクションおよびパブリッシュ・アクション以外でメッセージ・フローの$outboundに行う変更は無視されることにも注意してください。つまりルート・ノードおよびパブリッシュ・アクションで$outboundが初期化される際、、それらの変更は上書きされるということです。
サービス・コールアウト・アクションで$outbound変数を変更することはできません。
$inbound変数と$outbound変数の特性は次のとおりです。
-
同じXMLスキーマを持ちます。
$inboundコンテキスト変数と$outboundコンテキスト変数は、「メッセージ・コンテキスト・スキーマ」で説明されているようにendpoint要素のインスタンスです。 -
サービス・ディレクトリに登録されているエンドポイントの名前を指定する単一の
name属性を含みます。name属性は、$inbound、$outboundいずれの場合も読取り専用として扱う必要があります。注意:
この読取り専用ルールは強制されません。読取り専用の要素を変更すると予期できない動作が生じることがあります。
-
「Inbound変数とOutbound変数の下位要素」で説明する下位要素
service、transportおよびsecurityを含みます。
A.4.1 Inbound変数とOutbound変数の下位要素
この項では、コンテキスト変数$inboundおよび$outboundの下位要素について説明します。また、どの下位要素が実行時に初期化されるかについての情報も示します。コンテキスト変数が初期化される方法について学習するには、「コンテキスト変数の初期化」を参照してください。次の下位要素があります。
A.4.1.1 service
service要素は、$inbound、$outboundいずれの場合も読取り専用です。下位要素としてはproviderName、operationがあります。
ノート:
メッセージ・コンテキスト・スキーマは、メッセージ・コンテキスト変数の要素の型を指定します。
表A-4 service要素の下位要素
| サブ要素 | 説明 |
|---|---|
|
providerName |
サービス・キー・プロバイダの名前。パブリッシュ・アクションおよびルーティング・アクションの構成に基づいて初期化されます。 |
|
operation (outboundのみ) |
対象のビジネス・サービスで呼び出される操作の名前。 ノート: この要素は |
A.4.1.2 transport
transport要素はinboundの場合は読取り専用です。ただし例外として、response要素ではこの要素を変更してレスポンス・トランスポート・ヘッダーを設定できます。transport要素の下位要素を表A-5に示します。
ノート:
メッセージ・コンテキスト・スキーマは、メッセージ・コンテキスト変数の要素の型を指定します。
表A-5 transport要素の下位要素
| サブ要素 | 説明 |
|---|---|
|
uri |
エンドポイントのURI。
初期化 URI要素は次のように初期化されます。
|
|
request |
リクエストに関するトランスポート固有のメタデータ(トランスポート・ヘッダーを含む)。この要素の値は転送プロトコルによって定義されます(具体的には、トランスポートSDKによって定義された
この要素のトランスポート固有の型について学習するには、Service Busインストールの次のディレクトリに用意された該当するトランスポート・スキーマを参照してください。 service_bus-home/config/plugins/
初期化 URI要素は次のように初期化されます。
ファイル・トランスポート・プロトコルを使用してアウトバウンド・メッセージのファイル名を設定するには、次で説明するように、ルート・ノード・リクエスト・アクションで
|
|
response |
レスポンスに関するトランスポート固有のメタデータ(トランスポート・ヘッダーを含む)。この要素の値は転送プロトコルによって定義されます(具体的には、トランスポートSDKによって定義された この要素は、 この要素のトランスポート固有の型について学習するには、Service Busインストールの次のディレクトリに用意された該当するトランスポート・スキーマを参照してください。 service_bus-home/config/plugins/
初期化
標準HTTPヘッダーの説明については、 標準JMSヘッダーの詳細は、『Oracle WebLogic Server JMSアプリケーションの開発』のJMSパブリックAPIの付加価値拡張機能に関する項を参照してください。 ノート: MQヘッダー |
|
mode |
通信スタイルが 初期化
|
|
qualityOfService この要素は、inbound変数の場合は読取り専用です。 outbound(パブリッシュ・アクションまたはルーティング・アクションのアウトバウンド・リクエスト・アクション)の場合は変更可能です。 |
メッセージ送信時または受信時に使用するサービスの品質。有効な値は
初期化
|
|
retryCount (outboundのみ) |
Service Busからメッセージを送信するときの再試行回数。
|
A.4.1.3 security
表A-6 security要素の下位要素
| サブ要素 | 説明 |
|---|---|
|
transportClient inboundのみ) |
認証されたトランスポート・レベル・ユーザー情報。ユーザー情報にはユーザー名とオプションのprincipalsが含まれます。principalsには0個以上のgroupを含めて、subjectが属するgroupごとに1つの要素を含めることができます。 この変数は、Service Busによって初期化されます。inboundの |
|
messageLevelClient inboundのみ) |
認証されたメッセージ・レベル・ユーザー情報を指定します。ユーザー情報にはユーザー名とオプションのprincipalsが含まれます。principalsには0個以上のgroupを含めて、subjectが属するgroupごとに1つの要素を含めることができます。 この変数は、Service Busによって初期化されます。inboundの |
|
doOutboundWss (outboundのみ) |
Service Busは、ルーティング時またはパブリッシュ時にこの要素の値を設定します。使用頻度の低いデザイン・パターンには、この値を 詳細は、「アウトバウンドWS-Securityの無効化」の下を参照してください。 ノート: あるプロキシ・サービスがOracle Web Services Managerサービス・ポリシーを含む別のプロキシ・サービス(ローカル・プロキシなど)を呼び出す場合は、アウトバウンドWS-Security処理は行われません。Service Busはその動作を自動的に処理して、 |
A.4.2 関連トピック
Oracle Service Busコンソールでのパイプライン・アクションの操作
標準HTTPヘッダーの説明については、http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.htmlを参照してください。
標準JMSヘッダーの詳細は、『Oracle WebLogic Server JMSアプリケーションの開発』のWebLogic JMSの理解に関する項を参照してください。
A.5 operation変数
$operation変数は、読取り専用の変数です。この変数には、パイプラインで呼び出される操作を指定する文字列が格納されます。
操作が定義されていない場合は、$operation変数が設定されず、nullと等価の値が返されます。
Service Busは、パフォーマンスの最適化のために、$operation変数を、$inbound変数の下位要素としてではなく、スタンドアロン変数として提供します。操作の計算は、$inbound変数がアクセスされた場合に常に行われるのではなく、$operation変数が明示的にアクセスされるまで保留される場合があります。
A.6 fault変数
fault変数は、メッセージ処理中に発生したすべてのエラーに関する情報を保持します。
エラーが発生すると、この変数に情報が格納されてから、適切なエラー・ハンドラが呼び出されます。この変数はエラー・ハンドラ・パイプラインでのみ定義され、リクエスト・パイプラインやレスポンス・パイプライン、ルート・ノードやブランチ・ノードでは設定されません。
fault変数には、表A-7に示す下位要素が含まれます。
ノート:
メッセージ・コンテキスト・スキーマは、メッセージ・コンテキスト変数の要素の型を指定します。
表A-7 fault変数の下位要素
| fault変数の要素 | 説明 |
|---|---|
|
errorCode |
文字列値によるエラー・コード。 |
|
reason |
テキストによるエラーの説明。 |
|
details |
|
|
location |
エラーが発生したノード、パイプライン、およびステージを指定します。また、エラーがエラー・ハンドラ内で発生したかどうかも指定します。次の下位要素があります。
|
|
java-exception |
例外インスタンス参照についての情報。これには、それぞれが単一インスタンスを定義する複数の |
|
stack-trace |
フォルトに追加される任意のスタック・トレース。 |
A.6.1 エラー・コード
fault変数のコンテンツは、SOAPベースのサービスからの返信時にフォルトを生成しやすいよう、SOAPフォルトに基づいてモデル化されています。Service Busによって生成されるエラー・コードの値は、他の方法で構成されていなければ、システム・エラー・コードに対応し、エラー・コードの先頭にはOSBという文字列が付加されます。エラーに関連付けられたエラー・コードは、faultコンテキスト変数の要素内に表示されます。値にアクセスするには、次のXQuery文を使用します。
$fault/ctx:errorCode/text()
Service Busでは、考えられる4つのクラスのエラーに対応する汎用エラー・コードが定義されています。汎用コードの形式はOSB-xxx000 (xxxは汎用カテゴリを次のように表します)です。
-
380トランスポートとプロキシ
-
382パイプライン
-
386セキュリティ
-
394 UDDI
これにより、次のように汎用コードが生成されます。
-
OSB–380000—OSB–380999
トランスポートまたはプロキシ・サービスのエラーを示します(メッセージのディスパッチの失敗など)。
-
OSB–382000—OSB–382499
パイプラインの実行時エラーを示します(ステージの例外など)。
-
OSB–382500—OSB–382999
パイプライン・アクション内のエラーを示します。
-
OSB–386000—OSB–386999
WS-Securityエラーを示します(認可エラーなど)。
-
OSB–394500—OSB–394999
UDDIサブシステム内のエラーを示します。
Service Busでは、特定のエラーを示す一意のコードが定義されています。たとえば:
-
OSB-382030: メッセージ解析エラーを示します(SOAPサービスが非SOAPメッセージを受信したなど)。
-
OSB-382500: サービス・コールアウト・アクションがSOAPフォルト・レスポンスを受信した場合に備えて予約されています。
A.6.2 エラーの詳細
fault変数のdetails要素には、フォルトのタイプとその関連情報が表示されます。エラー・タイプを示す、次のいずれかの要素が含まれます。
-
ErrorResponseDetail: サービス・コールアウト・アクションがトランスポート・プロバイダからエラー・レスポンスを受信したことを示します。
-
InvalidEnvelope: SOAPサービスが予期しないSOAPエンベロープの整形式XMLドキュメントを受信したことを示します。
-
PayloadDetail: XMLとしてペイロードのすべてまたは一部を解析中に、エラーが発生したことを示します。
-
ReceivedFaultDetail: サービス・コールアウト・アクションがSOAPフォルトを受信したことを示します。
-
UnrecognizedResponseDetail: サービス・コールアウト・アクションがトランスポート・プロバイダから認識できないレスポンスを受信したことを示します。
-
ValidatonFailureDetail: 検証アクションでエラーが発生したことを示します。
-
WebServiceSecurityFault: Webサービス・セキュリティ処理関連のエラーが発生したことを示します。
-
StackTrace: 前述されていない場合の例外スタック・トレース。
エラー・スキーマ・ファイルについては、「エラー・スキーマ」を参照してください。
A.6.3 XML解析エラー(PayloadDetail)
「エラーの詳細」で説明するように、XML解析エラーの場合は不正なXMLテキストがエラー・スキーマのPayloadDetail要素に含まれます。解析エラーは、パイプラインへのインバウンド・リクエスト・メッセージおよびビジネス・サービスへのアウトバウンド・レスポンス・メッセージの解析中にのみ検出されます。割当てアクションなど、不正なXMLにつながるペイロードを明示的に変更するアクションは、このエラーの詳細に含まれません。
XMLパーサーが読み取るペイロードの一部のみがfault変数に含まれるため、PayloadDetail要素にはXMLテキスト全体は含まれない場合があります。デフォルトでは、エラーの詳細に含まれる文字数に制限はありません。fault変数のペイロード詳細に含まれるXMLテキストのサイズを制限するには、システム・プロパティのcom.bea.wli.sb.FaultPayloadDetailMaxSizeを、含めるテキストのサイズに設定します(バイト単位)。このプロパティを0 (ゼロ)に設定すると、この機能が無効になり、フォルトはPayloadDetail要素に含まれません。
パイプラインでコンテンツのストリーミングを有効にすると、PayloadDetail要素内のテキストは、10KBまたは設定した最大サイズ(10KB未満の場合)のいずれかに切り捨てられます。ペイロードにバイナリ文字が含まれる場合、そのペイロードはbase64エンコード形式でPayloadDetail要素のbase64子要素に配置されます(最大ペイロード詳細サイズまで)。
A.8 コンテキスト変数の初期化
メッセージ・コンテキストとその変数は、メッセージ受信時およびメッセージ処理の開始前にバインディング・レイヤーで初期化されます
。コンテキスト変数を初期化する方法を表A-8に示します。
表A-8 コンテキスト変数の初期化
| コンテキスト変数 | 初期化方法 |
|---|---|
|
outbound |
ルーティングが行われていないか、エラーが発生していないため、nullに初期化されます。 |
|
fault |
|
|
inbound |
登録されたプロキシ・サービスに関するService Busメタデータと、特定の受信リクエストに関するトランスポート・レベル・メタデータ(トランスポート・ヘッダー、認証されたユーザー情報など)から取得したサービス、トランスポート、およびセキュリティの情報で初期化されます。
|
|
header body attachments operation |
インバウンド・メッセージのコンテンツを使用して初期化されます。初期化の実行方法は、この項の以降のトピックで説明するようにサービスのタイプによって異なります。
|
A.8.1 Attachmentsコンテキスト変数の初期化
$attachmentsコンテキスト変数は、メッセージに含まれるすべてのMIME添付で初期化されますが、メイン・メッセージを表す部分は含まれません(SOAP、XML、MFLなど形式を問わず)。各<attachment>要素は、MIMEパッケージの各部分に伴うMIMEヘッダーを使用して初期化されます。
<attachment>の<body>要素のコンテンツは、添付のContent-Typeに応じて次のいずれかになります。
-
XML
-
text
-
添付コンテンツを参照する参照XMLスニペット(「body変数とattachments変数内のバイナリ・コンテンツ」を参照)。
A.8.2 HeaderおよびBodyコンテキスト変数の初期化
この項では、コンテキスト変数$headerおよび$bodyの初期化方法について説明しますが、これらの変数の初期化方法は、サービスのタイプが「SOAPサービス」、「XMLサービス(非SOAP)」、「メッセージング・サービス」のいずれであるかによって異なります。
A.8.2.1 SOAPサービス
SOAPベースのサービスへのメッセージは、<soap:Envelope>要素に含まれるXMLを含むSOAPメッセージです。添付を含むメッセージの場合、インバウンド・メッセージのコンテンツは、SOAPエンベロープをその一部として(通常は最初の部分、または最上位のContent-Typeヘッダーで指定される部分)含むMIMEパッケージです。コンテキスト変数は次のように初期化されます。
-
$header: SOAPメッセージの<soap:Header>要素で初期化されます。 -
$body: SOAPメッセージの<soap:Body>要素で初期化されます。
A.8.2.2 XMLサービス(非SOAP)
XMLベースのサービスへのメッセージはXMLですが、サービス構成で許可された型を使用できます。添付を含むメッセージの場合、インバウンド・メッセージのコンテンツは、プライマリXMLペイロードをその一部として(通常は最初の部分、または最上位のContent-Typeヘッダーで指定される部分)含むMIMEパッケージです。
コンテキスト変数は次のように初期化されます。
-
$header: 空の<soap:Header/>要素で初期化されます。 -
$body: XMLペイロード全体をラップする<soap:Body>要素で初期化されます。
A.8.2.3 メッセージ・サービス
メッセージング・サービスは、あるデータ型のメッセージを受信し、応答として別のデータ型のメッセージを返すことができるサービスです。サポートされるデータ型は、XML、MFL、テキスト、または型なしバイナリです。コンテキスト変数は次のように初期化されます。
-
$header: 空の<soap:Header/>要素で初期化されます。 -
$body: ペイロード全体をラップする<soap:Body>要素で初期化されます。-
XML、MFL、およびテキスト・コンテンツの場合は、
<soap:Body>要素内に直接挿入されます。 -
バイナリ・コンテンツの場合は、参照XMLコードが作成され
<soap:Body>要素内に挿入されます(「body変数とattachments変数内のバイナリ・コンテンツ」を参照)。バイナリ・コンテンツに対してアクセスまたは変更を行うことはできませんが、参照XMLを検証および変更し、インライン・コンテンツと置き換えることができます。
-
A.9 コンテキスト変数に対する操作の実行
メッセージ・コンテキストに対する対話および操作は、パイプラインを定義するパイプライン・ペア、ブランチまたはルート・ノードでのアクションを通じて行います。
ほとんどのアクションについては、それを実行するためのXQuery言語が公開されています。各コンテキスト変数は、同じ名前のXQuery変数として表されます。たとえば、$header変数は、XQueryでは$headerとしてアクセスでき、$body変数は$bodyとしてアクセスできます。この項の例では、XQueryを使用してコンテキスト変数に対するチェックおよび操作を行っています。
A.9.1 $body
$body変数は<soap-env:Body>...</soap-env:Body>要素を含みます。(サービスがSOAP 1.2の場合、$body変数にはSOAP 1.2 Body要素が格納されます。)たとえば、割当てアクションを使用して$bodyコンテキスト変数にデータを割り当てた場合、<soap-env:Body>要素でデータをラップする必要があります。つまり、コンテキスト変数内に<soap-env:Body>要素を含めることによってSOAPパッケージを構築します。
サービス・コールアウト・アクションのリクエスト・ドキュメント変数を作成する場合は、例外です。この場合、サービス・コールアウト・アクションはコアのペイロード(RPCパラメータ、ドキュメントなど)を処理の対象とし、Service Busはコアのペイロードに基づいてSOAPパッケージを構築します。つまり、サービス・コールアウト・アクションのリクエスト・ドキュメント変数を構成するときには、入力ドキュメントを<soap-env:Body>...</soap-env:Body>でラップしません。
サービス・コールアウト・アクションの構成については、「コンソールでのサービス・コールアウト・アクションの追加」を参照してください。
A.9.2 $header
$header変数は<soap-env:Header>...</soap-env:Header>要素を含みます。(プロキシ・サービスがSOAP 1.2の場合、$header変数にはSOAP 1.2 Header要素が格納されます。)たとえば、割当てアクションを使用して $headerコンテキスト変数にデータを割り当てた場合、<soap-env:Header>要素でデータをラップする必要があります。つまり、コンテキスト変数内に<soap-env:Header>要素を含めることによってSOAPパッケージを構築します。これは、サービス・コールアウト・リクエストの1つまたは複数のSOAPヘッダーを設定できる場合を含め、$headerのすべての操作に該当します。サービス・コールアウト・アクションのSOAPヘッダーの構成の詳細は「コンソールのサービス・コールアウト・アクションの追加」を参照してください。
WS-Addressingヘッダー(From)の抽出: $header/wsa:From
非SOAPメッセージからのペイロードの抽出: $body/*
アウトバウンド・レスポンス・メッセージからのuser-headerの抽出: $outbound/ctx:transport/ctx:response/tp:user-header[@name='myheader']/@value
SOAPサービスへのサービス・コールアウト内のリクエスト・パラメータに使用する$body入力変数を作成する場合、soap-env:Bodyラッパーを削除するために、$body/*を使用してその変数のコンテンツを定義します($bodyを使用すると、soap-env:Bodyラッパーが保持されます)。
サービス コールアウト内のリクエスト・パラメータの変数コンテンツの割当て: $body/*
A.10 ディスパッチするメッセージの作成
Service Busによってメッセージがパブリッシュまたはルーティングされるときに、メッセージ・コンテキストの変数の値を使用してメッセージのコンテンツが作成されます。
たとえば、トランスポート・ヘッダーとトランスポート固有のメタデータは、$outbound/transport/requestから取得されます。コンテキストの初期化と同様に、アウトバウンド・メッセージのメッセージ・コンテンツはターゲット・サービスのタイプに応じて異なって処理されます。次のトピックで説明されているように、アウトバウンド・メッセージ・コンテンツの作成方法はターゲット・サービスのタイプによって異なります。
A.10.1 SOAPサービス
送信SOAPメッセージは、$header変数と$body変数のコンテンツを<soap:Envelope>要素でラップして作成します。呼び出されたサービスがSOAP 1.2サービスの場合、作成されるエンベロープはSOAP 1.2エンベロープです。呼び出されたサービスがSOAP 1.1サービスの場合、作成されるエンベロープはSOAP 1.1エンベロープです。$body変数に参照XMLコードが格納されている場合、メッセージは現状のまま送信されます。つまり、参照されているコンテンツはメッセージに追加されません。
$attachments変数で添付が定義されている場合は、メイン・メッセージと添付データからMIMEパッケージが作成されます。各添付部分のコンテンツの処理方法は、メッセージング・サービスのコンテンツの処理方法に類似しています。
A.10.2 XMLサービス(非SOAP)
Service BusのXMLベースのサービスへのメッセージは、$body変数のコンテンツから作成されます。
-
$body変数が空の場合は、サイズがゼロのメッセージが送信されます。 -
$body変数に複数のXMLスニペットが含まれる場合は、最初のスニペットのみがアウトバウンド・メッセージで使用されます。たとえば、<soap:Body>に<abc/><xyz/>が含まれる場合は、<abc/>のみが送信されます。 -
$body変数のコンテンツがXMLではなくテキストである場合は、エラーがスローされます。 -
$body変数に参照XMLコードが格納されている場合、メッセージは現状のまま送信されます。つまり、参照されているコンテンツはメッセージに追加されません。 -
$attachments変数で添付が定義されている場合は、XMLメッセージと添付データからMIMEパッケージが作成されます。XMLメッセージがnullの場合は、対応するMIME本文部分は空になります。各添付部分のコンテンツの処理方法は、メッセージング・サービスのコンテンツの処理方法に類似しています。
含まれているデータのタイプにかかわらず、$header変数はアウトバウンド・メッセージにコンテンツを提供しません。サービス・コールアウト・アクションに対するメッセージの作成の例については、「Oracle Service Busコンソールでのパイプライン・アクションの操作」を参照してください。
A.10.3 メッセージ・サービス
Service Busのメッセージ・サービスへのメッセージは、$body変数のコンテンツから作成されます。
-
送信メッセージのタイプに関係なく、
$body変数が空の場合、サイズがゼロのメッセージが送信されます。 -
送信メッセージのタイプがXMLの場合、メッセージは「XMLサービス(非SOAP)」で示されているのと同じ方法で作成されます。
-
送信メッセージのタイプがMFLの場合は、抽出されたXMLがMFLに変換される点を除きXMLメッセージの場合と同様に処理されます。XMLからMFLへの変換が実行できない場合はエラーが発生します。
-
ターゲット・サービスでテキスト・メッセージが要求される場合は、
$body変数のコンテンツがテキストとして解釈され送信されます。このため、Service Busでは、ターゲット・サービスにテキストとして配信する必要がある着信XMLメッセージを処理できます。つまり、このようなメッセージを処理するためにメッセージ・フローを構成する必要はありません。 -
バイナリ・メッセージを受信するターゲット・サービスの場合は、
$body変数に参照XMLコードを格納する必要があります。参照URIは、Service Busのメモリー内ハッシュ表に格納されたバイナリ・データを参照します。参照先コンテンツはターゲット・サービスに送信されます。クライアント、トランスポートまたはサービスの設計者によって参照URIが指定される場合、参照されるデータはService Busに格納されないため、アウトバウンド・メッセージに含めることはできません。したがって、参照XMLがメッセージで送信されます。
$body変数に参照XMLコードが含まれ、ターゲット・サービスでバイナリ以外のメッセージが要求される場合は、$body変数内の参照XMLはコンテンツとして処理されます。つまり、メッセージはXMLとして送信されるか、テキストに変換されるか、またはMFLに変換されます。これは、参照XMLのURIに関係なく当てはまります。
含まれているデータのタイプにかかわらず、$header変数はアウトバウンド・メッセージにコンテンツを提供しません。
サービス・コールアウト・アクションに対するメッセージの作成の例については、「Oracle Service Busコンソールでのパイプライン・アクションの操作」を参照してください。
A.10.3.1 電子メール・メッセージでのバイナリ・コンテンツの送信について
バイナリ・メッセージの場合、Service Busでは$body変数にメッセージ・コンテンツは挿入されません。かわりに、<binary-content/>参照要素が作成され<SOAP:Body>要素に挿入されます(「メッセージ関連の変数」を参照)。ただし、電子メール規格では、バイナリ・コンテンツ・タイプをメッセージの主要な部分として送信することがサポートされていません。テキストまたはXMLのドキュメントと任意の添付を受信するメッセージ・サービスに、電子メールでバイナリ・メッセージを送信する場合は、次の手順に従います。
-
バイナリ・コンテンツ参照XMLを
$bodyから$attachmentsに変更します。 -
$bodyのコンテンツを<SOAP:Body>要素でラップされたテキストまたはXMLに置き換えます。
送信メッセージのタイプがMFLの場合は、$bodyのコンテンツが、MFLトランスフォーメーションに基づいてXMLからテキストまたはバイナリに変換されます。
-
ターゲット・サービスでテキスト・メッセージを受信する場合は、
$outboundでcontent-type(MFLメッセージ・タイプのデフォルトはバイナリ)をtext/plainとして設定できます。 -
ターゲット・サービスでバイナリ・メッセージを受信する場合は、電子メール・トランスポートを使用してMFLコンテンツを送信することはできません。
バイナリ・コンテンツの処理方法についてさらに学習するには、「body変数とattachments変数内のバイナリ・コンテンツ」を参照してください。
A.11 メッセージ・コンテキスト・スキーマ
この例は、メッセージ・コンテキスト変数の要素の型を指定するメッセージ・コンテキスト・スキーマ(MessageContext.xsd)を示します。
メッセージ・コンテキスト変数を操作する場合、JARファイル(OSB_ORACLE_HOME/lib/servicebus-schemas.jar)に用意されたMessageContext.xsdと、OSB_ORACLE_HOME/config/plugins/にあるトランスポート固有のスキーマを参照する必要があります。
例 - MessageContext.xsd
<schema targetNamespace="http://www.bea.com/wli/sb/context"
xmlns:mc="http://www.bea.com/wli/sb/context"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<!-- =========================================================================== -->
<!-- The context variable 'fault' is an instance of this element -->
<element name="fault" type="mc:FaultType"/>
<!-- The context variables 'inbound' and 'outbound' are instances of this
element -->
<element name="endpoint" type="mc:EndpointType"/>
<!-- The three sub-elements within the 'inbound' and 'outbound' variables -->
<element name="service" type="mc:ServiceType"/>
<element name="transport" type="mc:TransportType"/>
<element name="security" type="mc:SecurityType"/>
<!-- The context variable 'attachments' is an instance of this element -->
<element name="attachments" type="mc:AttachmentsType"/>
<!-- Each attachment in the 'attachments' variable is represented by an
instance of this element -->
<element name="attachment" type="mc:AttachmentType"/>
<!-- Used to represent binary payloads and pass-by reference content -->
<element name="binary-content" type="mc:BinaryContentType"/>
<!-- Element used to represent POJOs stored in object repository -->
<element name="java-content" type="mc:JavaContentType"/>
<!-- =========================================================================== -->
<!-- The schema type for -->
<complexType name="AttachmentsType">
<sequence>
<!-- the 'attachments' variable is just a series of attachment
elements -->
<element ref="mc:attachment" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="AttachmentType">
<all>
<!-- Set of MIME headers associated with attachment -->
<element name="Content-ID" type="string" minOccurs="0"/>
<element name="Content-Type" type="string" minOccurs="0"/>
<element name="Content-Transfer-Encoding" type="string"
minOccurs="0"/>
<element name="Content-Description" type="string" minOccurs="0"/>
<element name="Content-Location" type="string" minOccurs="0"/>
<element name="Content-Disposition" type="string" minOccurs="0"/>
<!-- any (custom) headers not specified above will be here -->
<element name="user-headers" minOccurs="0">
<complexType>
<sequence>
<element name="user-header" maxOccurs="unbounded">
<complexType>
<attribute name="name" type="string"/>
<attribute name="value" type="string"/>
</complexType>
</element>
</sequence>
</complexType>
</element>
<!-- Contains the attachment content itself, either in-lined or as <binary-content/> -->
<element name="body" type="anyType"/>
</all>
</complexType>
<complexType name="BinaryContentType">
<!-- URI reference to the binary or pass-by-reference payload -->
<attribute name="ref" type="anyURI" use="required"/>
</complexType>
<complexType name="JavaContentType">
<!-- URI reference to POJOs in object repository -->
<attribute name="ref" type="anyURI" use="required"/>
</complexType>
<!-- =========================================================================== -->
<complexType name="EndpointType">
<all>
<!-- Sub-elements holding service, transport and security details for
the endpoint -->
<element ref="mc:service" minOccurs="0" />
<element ref="mc:transport" minOccurs="0" />
<element ref="mc:security" minOccurs="0" />
</all>
<!-- Fully-qualified name of the service represented by this endpoint -->
<attribute name="name" type="string" use="required"/>
</complexType>
<!-- =========================================================================== -->
<complexType name="ServiceType">
<all >
<!-- name of service provider -->
<element name="providerName" type="string" minOccurs="0"/>
<!-- the service operation being invoked -->
<element name="operation" type="string" minOccurs="0"/>
</all>
</complexType>
<!-- =========================================================================== -->
<complexType name="TransportType">
<all>
<!-- URI of endpoint -->
<element name="uri" type="anyURI" minOccurs="0" />
<!-- Transport-specific metadata for request and response (includes
transport headers) -->
<element name="request" type="anyType" minOccurs="0"/>
<element name="response" type="anyType" minOccurs="0" />
<!-- Indicates one-way (request only) or bi-directional
(request/response) communication -->
<element name="mode" type="mc:ModeType" minOccurs="0" />
<!-- Specifies the quality of service -->
<element name="qualityOfService" type="mc:QoSType" minOccurs="0" />
<!-- Retry values (outbound only) -->
<element name="retryInterval" type="integer" minOccurs="0" />
<element name="retryCount" type="integer" minOccurs="0" />
<!-- Throttling priority (outbound only) -->
<element name="priority" type="positiveInteger" minOccurs="0" />
</all>
</complexType>
<simpleType name="ModeType">
<restriction base="string">
<enumeration value="request"/>
<enumeration value="request-response"/>
</restriction>
</simpleType>
<simpleType name="QoSType">
<restriction base="string">
<enumeration value="best-effort"/>
<enumeration value="exactly-once"/>
</restriction>
</simpleType>
<!-- =========================================================================== -->
<complexType name="SecurityType">
<all>
<!-- Transport-level client information (inbound only) -->
<element name="transportClient" type="mc:SubjectType" minOccurs="0"/>
<!-- Message-level client information (inbound only) -->
<element name="messageLevelClient" type="mc:SubjectType"
minOccurs="0"/>
<!-- Boolean flag used to disable outbound WSS processing (outbound
only) -->
<element name="doOutboundWss" type="boolean" minOccurs="0"/>
</all>
</complexType>
<complexType name="SubjectType">
<sequence>
<!-- User name associated with this tranport- or message-level subject -->
<element name="username" type="string"/>
<element name="principals" minOccurs="0">
<complexType>
<sequence>
<!-- There is an element for each group this subject
belongs to, as determined by the authentication
providers -->
<element name="group" type="string" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="subject-properties" minOccurs="0" maxOccurs="1">
<complexType>
<sequence>
<element name="property" minOccurs="0"
maxOccurs="unbounded"
type="mc:SubjectPropertyType"/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
<complexType name="SubjectPropertyType" mixed="true">
<sequence>
<any minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</sequence>
<attribute name="name" type="string" use="required"/>
<anyAttribute processContents="lax"/>
</complexType>
<!-- =========================================================================== -->
<complexType name="FaultType">
<all>
<!-- A short string identifying the error (e.g. BEA38229) -->
<element name="errorCode" type="string"/>
<!-- Descriptive text explaining the reason for the error -->
<element name="reason" type="string" minOccurs="0" />
<!-- Any additional details about the error -->
<element name="details" type="anyType" minOccurs="0" />
<!-- Information about where the error occured in the proxy -->
<element name="location" type="mc:LocationType" minOccurs="0" />
<!-- Information about the exception instance reference stored in the
object repository -->
<element name="java-exception" minOccurs="0">
<complexType>
<sequence>
<element ref="mc:java-content" />
</sequence>
</complexType>
</element>
</all>
</complexType>
<simpleType name="PipelinePathType">
<restriction base="string">
<enumeration value="request-pipeline"/>
<enumeration value="response-pipeline"/>
</restriction>
</simpleType>
<complexType name="LocationType">
<all>
<!-- Name of the Pipeline/Branch/Route node where error occured -->
<element name="node" type="string" minOccurs="0" />
<!-- Name of the Pipeline where error occured (if applicable) -->
<element name="pipeline" type="string" minOccurs="0" />
<!-- Name of the Stage where error occured (if applicable) -->
<element name="stage" type="string" minOccurs="0" />
<!-- Indicates if error occured from inside an error handler -->
<element name="error-handler" type="boolean" minOccurs="0" />
<!-- Indicates whether or not error occured in request or
response path -->
<element name="path" type="mc:PipelinePathType" minOccurs="0" />
</all>
</complexType>
<!-- Encapsulates any stack-traces that may be added to a fault <details> -->
<element name="stack-trace" type="string"/>
</schema>
A.12 エラー・スキーマ
この例は、エラーの構造を指定するエラー・スキーマ(Errors.xsd)を示します。
このファイルは、JARファイルOSB_ORACLE_HOME/lib/servicebus-schemas.jarにあります。
例 - Errors.xsd
<schema targetNamespace="http://www.bea.com/wli/sb/errors"
xmlns:err="http://www.bea.com/wli/sb/errors"
xmlns:tc="http://www.bea.com/wli/sb/transports"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<import namespace="http://www.bea.com/wli/sb/transports"
schemaLocation="TransportCommon.xsd" />
<element name="InvalidEnvelope">
<complexType>
<sequence>
<element name="localpart" type="NCName"/>
<element name="namespace" type="anyURI" minOccurs="0"/>
</sequence>
</complexType>
</element>
<element name="WebServiceSecurityFault">
<complexType>
<sequence>
<element name="faultcode" type="QName"/>
<element name="faultstring" type="string"/>
<element name="detail" minOccurs="0">
<complexType mixed="true">
<sequence>
<any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</sequence>
<anyAttribute namespace="##any" processContents="lax"/>
</complexType>
</element>
</sequence>
</complexType>
</element>
<!-- Publish error details -->
<element name="ErrorResponseDetail" type="err:ErrorResponseDetail"/>
<complexType name="ErrorResponseDetail">
<sequence>
<!-- Response metadata -->
<element name="response-metadata" type="tc:ResponseMetaDataXML" minOccurs="0" />
</sequence>
</complexType>
<!-- payload information in $fault details when parsing message into XML raises an error -->
<element name="PayloadDetail" type="err:PayloadDetail"/>
<complexType name="PayloadDetail">
<choice>
<element name="text" minOccurs="0" type="string" />
<element name="base64" minOccurs="0" type="base64Binary" />
</choice>
</complexType>
<!-- REST default (system) faults -->
<element name="RestError" type="err:RestErrorType"/>
<complexType name="RestErrorType">
<sequence>
<element name="errorMessage" minOccurs="0" type="string" />
<element name="errorCode" minOccurs="0" type="string" />
</sequence>
</complexType>
</schema>