| Oracle® Fusion Middleware Oracle Service Busでのサービスの開発 12c (12.1.3) E53004-06 |
|
 前 |
 次 |
ヒント:
この章を始める前に、「カスタム・トランスポート・プロバイダについて」を確認してください。
この章の内容は次のとおりです。
カスタム・トランスポート・プロバイダを設計および構築するプロセスは複雑です。この項では、トランスポート・プロバイダを開発する際の推奨事項について説明します。カスタム・トランスポート・プロバイダの開発は、計画、開発およびパッケージ化とデプロイの3つの基本的な手順に分類されます。
カスタム・トランスポート・プロバイダを開発する前に、次の計画手順を実行します。
カスタム・トランスポートの開発手順には、XMLスキーマ・ファイル、構成コンポーネント、ユーザー・インタフェースなどの必要なアーティファクトの作成が含まれます。「基本的な開発手順」では、トランスポート・プロバイダを開発するために実行する必要がある手順について説明します。カスタム・トランスポートを開発する前に、開発サイクル中に参照する必要があるメッセージ、エラー処理、メッセージの変換など、いくつかのトピックを説明している「開発に関する重要事項」を確認してください。
カスタム・トランスポート・プロバイダの開発を始める前に、考慮する必要がある設計時に考慮事項のいくつかを次に示します。
カスタム・トランスポート・プロバイダを開発する必要があるかどうかを判断します。「カスタム・トランスポート・プロバイダの開発の必要性」を参照してください。
メッセージ・エンドポイントをトランザクション対応にするかまたはトランザクション非対応にするかを判断します。「トランザクション対応のエンドポイントとトランザクション非対応のエンドポイント」を参照してください。
メッセージ・エンドポイントを一方向、同期、非同期のいずれにするかを判断します。「サポートされているメッセージ・パターン」および「同期トランザクションのサポート」を参照してください。
送信メッセージと着信メッセージのセキュリティ要件を決定します。「トランスポートSDKセキュリティ・モデル」を参照してください。
Service Busで使用されるスレッド・モデルについて理解します。「トランスポートSDKおよびスレッド・モデル」を参照してください。
トランスポート・プロバイダで同期アウトバウンド呼出しと非同期アウトバウンド呼出しのどちらがサポートされるかを判断します。「非同期のサポート」を参照してください。
トランスポートSDKに用意されているインタフェースとクラスについて確認し、トランスポート・プロバイダの設計時部分および実行時部分にどのように適合するのかを理解します。「トランスポートSDKのインタフェースおよびクラス」を参照してください。
カスタム・トランスポート・プロバイダをパッケージ化およびデプロイする方法について理解します。「カスタム・トランスポート・プロバイダのパッケージ化とデプロイ」を参照してください。
トランスポート・フレームワークを介したメソッド呼出しのフローを確認します。「トランスポートSDK UMLシーケンス・ダイアグラム」を参照してください。
カスタム・トランスポート・プロバイダを開発する際に従う基本手順は次のとおりです。
ステップ1. トランスポート・フレームワーク・コンポーネントの確認
ステップ2. トランスポート・プロジェクトのディレクトリ構造の作成
ステップ3. トランスポート固有のアーティファクトのXMLスキーマ・ファイルの作成
ステップ5. TransportProviderConfiguration XMLBeanの定義
図40-1は、カスタム・トランスポート・プロバイダを作成する際に、実装および構成する必要があるコンポーネントを示しています。トランスポート・マネージャは、トランスポート・プロバイダの登録を制御および管理し、Service Busとの通信を処理します。トランスポート・プロバイダは、トランスポート・エンドポイント(メッセージの送信元または送信先となるリソース)のライフ・サイクルおよび実行時の動作を管理します。カスタム・トランスポート・プロバイダを開発するには、トランスポートSDKを使用します。
実装および構成する必要があるトランスポート・サブシステムには、次のものがあります。
トランスポートUIバインディング: トランスポート・プロバイダのユーザー・インタフェース・コンポーネント。関連するインタフェースの概要は、「ユーザー・インタフェースの構成」を参照してください。
トランスポート・エンドポイント: メッセージの送受信を行います。関連するインタフェースの概要は、「汎用クラスおよびインタフェース」を参照してください。
エンドポイント構成: エンドポイント構成を格納します。関連するインタフェースの概要は、「スキーマで生成されるインタフェース」を参照してください。
トランスポート・メッセージ・コンテキスト: メッセージ(インバウンドおよびアウトバウンド)のリクエスト・ヘッダー、レスポンス・ヘッダーおよびその他の部分のメタデータが含まれています。詳細は、「SourceおよびTransformerクラスとインタフェース」および「リクエストおよびレスポンス・メッセージのメタデータおよびヘッダーの表現」を参照してください。
WLSアーティファクト・デプロイヤ: (オプション)メッセージを送受信するサーブレットなどの、アーティファクトをデプロイします。
トランスポートの送信者: アウトバウンド・メッセージおよびペイロードのメタデータを取得します。関連するインタフェースのサマリーは、「汎用インタフェースのサマリー」を参照してください。
トランスポートのリスナー: アウトバウンド・エンドポイントがService Busの残りの部分にアウトバウンド・リクエストの結果をポストできるようにします。「リクエストおよびレスポンス・メッセージのメタデータおよびヘッダーの表現」も参照してください。
リクエスト/レスポンスのメタデータ: 関連するインタフェースの概要については、「リクエストおよびレスポンス・メッセージのメタデータおよびヘッダーの表現」を参照してください。
新しいトランスポート・プロバイダを開発する前に、プロジェクトの適切なディレクトリ構造をセットアップします。サンプル・ソケット・トランスポート・プロバイダに使用されているディレクトリ構造をコピーすることをお薦めします。この構造の詳細は、「サンプルの場所とディレクトリ構造」を参照してください。
XMLスキーマ(XSD)ファイルを作成し、トランスポート固有の定義を記述します。このファイルは、サンプル・ソケット・トランスポート・プロバイダ用に開発されたスキーマ・ファイル(OSB_ORACLE_HOME/samples/servicebus/sample-transport/schemas/SocketTransport.xsd)を基に作成できます。
注意:
SocketTransport.xsdファイルにより、TransportCommon.xsdファイルがインポートされます。このファイルは、サービス・エンドポイントの構成用の基本となるスキーマ定義ファイルです。このファイルは、OSB_ORACLE_HOME/lib/modules/oracle.servicebus.kernel-api.jarにあります。続行する前に、このファイルのコンテンツを確認しておきます。
前項の「ステップ3. トランスポート固有のアーティファクトのXMLスキーマ・ファイルの作成」で説明されているXMLスキーマ・ファイルで、次のトランスポート固有のアーティファクトのXMLスキーマを定義します。
EndpointConfiguration
RequestMetaDataXML
ResponseMetaDataXML
これらの各スキーマ定義は、対応するJavaファイルに変換された後、コンパイルされます。サンプル・ソケット・トランスポート・プロバイダを作成すると、OSB_ORACLE_HOME/samples/servicebus/sample-transport/build/classes/com/bea/alsb/transports/sock/implで、これらの変換されたJavaソース・ファイルの例を検出できます。トランスポート・プロバイダ固有のメタデータおよびヘッダーを定義する場合は、単純なXMLタイプのみサポートされています。たとえば、ネストされた要素を持つ複雑なタイプはサポートされていません。また、指定の名前のヘッダーは最大でも1つのみです。
EndPointConfigurationは、エンドポイント構成のベース・タイプで、インバウンド・エンドポイントおよびアウトバウンド・エンドポイントのデプロイメントと操作に必要なパラメータの完全なセットを表します。この構成は、汎用的な部分とプロバイダ固有の部分で成り立ちます。EndPointConfigurationスキーマ定義の詳細は、TransportCommon.xsdファイルのドキュメント要素を参照してください。
プロバイダ固有のエンドポイント構成をスキーマ・ファイルに指定する必要があります。次の例はSocketTransport.xsdからの抜粋を示します。
例 - SocketEndPointConfiguration定義のサンプル
<xs:complexType name="SocketEndpointConfiguration">
<xs:annotation>
<xs:documentation>
SocketTransport - specific configuration
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:choice>
<xs:element name="outbound-properties"
type="SocketOutboundPropertiesType"/>
<xs:element name="inbound-properties"
type="SocketInboundPropertiesType"/>
</xs:choice>
<xs:element name="request-response" type="xs:boolean">
<xs:annotation>
<xs:documentation>
Whether the message pattern is synchronous
request-response or one-way.
</xs:documentation>
</xs:annotation>
</xs:element>
...
各トランスポート・プロバイダは、メタデータ(メッセージ・ヘッダー)をPOJO (Plain Old Java Object)に格納し、パイプラインに渡す必要があります。メタデータとして送信できる情報の例には、Content-Typeヘッダー、セキュリティ情報、ロケール情報などがあります。RequestMetaData POJOは、RequestMetaData抽象クラスを拡張する汎用オブジェクトで、インバウンド・リクエストやアウトバウンド・リクエストのメッセージ・メタデータを表します。トランスポート・プロバイダでは、メッセージ・メタデータをRequestMetaData POJOのService Busランタイムに配信する必要があります。詳細は、「リクエストとレスポンスのメタデータの処理」を参照してください。
RequestMetaDataXMLは、同じRequestMetaData POJOをXMLで表現したものです。このXML表現では、Apache XML Beanテクノロジを使用します。アウトバウンド・リクエストのメタデータ全体を特定のXMLフラグメントに設定するなど、メッセージを処理するときにメタデータのXML表現を必要とするパイプラインでの操作を伴う場合のみ、Service Busランタイムで必要になります。
リクエスト・メタデータの構成をスキーマ・ファイルに指定する必要があります。次の例はSocketTransport.xsdからの抜粋を示します。
例 - SocketRequestMetaDataXML定義のサンプル
<xs:complexType name="SocketRequestMetaDataXML">
<xs:annotation>
<xs:documentation/>
</xs:annotation>
<xs:complexContent>
<xs:extension base="ts:RequestMetaDataXML">
<xs:sequence>
<xs:element name="client-host"
type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation>
Client host name
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="client-port" type="xs:int" minOccurs="0">
<xs:annotation>
<xs:documentation>Client port</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
RequestHeadersXMLは、一連のインバウンド・リクエスト・ヘッダーまたはアウトバウンド・リクエスト・ヘッダーのベース・タイプです。RequestHeadersXMLの構成をスキーマ・ファイルに指定する必要があります。次の例はSocketTransport.xsdからの抜粋を示します。
例 - SocketRequestHeadersXML定義のサンプル
<xs:complexType name="SocketRequestHeadersXML">
<xs:annotation>
<xs:documentation/>
</xs:annotation>
<xs:complexContent>
<xs:extension base="ts:RequestHeadersXML">
<xs:sequence>
<xs:element name="message-count" type="xs:long" minOccurs="0">
<xs:annotation>
<xs:documentation>
Number of messages passed till now.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
ResponseMetaDataXMLは、インバウンド・メッセージまたはアウトバウンド・メッセージに対するレスポンスのメタデータのベース・タイプです。ResponseMetaDataXMLの構成をスキーマ・ファイルに指定する必要があります。次の例はSocketTransport.xsdからの抜粋を示します。
例 - SocketResponseMetaDataXML定義のサンプル
<xs:complexType name="SocketResponseMetaDataXML">
<xs:complexContent>
<xs:extension base="ts:ResponseMetaDataXML">
<xs:sequence>
<xs:element name="service-endpoint-host"
type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation>
Host name of the service endpoint connection.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="service-endpoint-ip"
type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation>
IP address of the service endpoint connection.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
ResponseHeadersXMLは、一連のレスポンス・ヘッダーのベース・タイプです。ResponseHeadersXMLの構成をスキーマ・ファイルに指定する必要があります。次の例はSocketTransport.xsdからの抜粋を示します。
例 - SocketResponseHeadersXML定義のサンプル
<xs:complexType name="SocketResponseHeadersXML">
<xs:annotation>
<xs:documentation/>
</xs:annotation>
<xs:complexContent>
<xs:extension base="ts:ResponseHeadersXML"/>
</xs:complexContent>
</xs:complexType>
TransportProviderConfiguration XML Beanを構成するには、トランスポート・プロバイダの構成ファイルを編集します。このXMLファイルは、sample-transportディレクトリのresourcesディレクトリにあります。次のガイドラインに従ってこのファイルを構成します。
プロキシ・サービスでトランスポートを使用できるようにする場合、inbound-direction-supported要素をtrueに設定します。
ビジネス・サービスでトランスポートを使用できるようにする場合、outbound-direction-supported要素をtrueに設定します。
トランスポートが自己記述型の場合、self-described要素の値をtrueに設定します。自己記述トランスポートでは、そのサービスがエンドポイント構成に基づいて形式(スキーマまたはWSDLファイル)を記述します。
トランスポートのtModelをUDDIレジストリにパブリッシュする場合、UDDI要素を含めます。詳細は、「UDDIレジストリへのプロキシ・サービスのパブリッシュについて」を参照してください。
ヒント:
TransportProviderConfigurationのスキーマは、OSB_ORACLE_HOME/lib/sb-schemas.jarにあるTransportCommon.xsdに定義されています。詳細は、スキーマ・ファイルを参照してください。
Oracle Service Busコンソールを使用してビジネス・サービスまたはプロキシ・サービスを追加する場合、サービス作成ウィザードでトランスポート・プロバイダを選択します。ウィザードには、Service Busで用意されているトランスポート・プロバイダおよびトランスポートSDKで開発されたカスタム・トランスポート・プロバイダが表示されます。ビジネス・サービスまたはプロキシ・サービスを構成すると、使用するトランスポート固有のプロパティがエディタに表示されます。これらは、カスタム・トランスポート・プロバイダ用に開発する必要があるすべてのユーザー・インタフェースです。
この項では、カスタム・トランスポート・プロバイダをOracle Service Busコンソールのユーザー・インタフェースにバインドする、トランスポートSDK APIコンポーネントについて説明します。プロバイダをユーザー・インタフェースに接続するには、これらのAPIを実装する必要があります。
ヒント:
ここでは、サービスの作成ウィザードおよびサービス定義エディタに慣れていることを前提としています。詳細な例は、「ソケット・トランスポートのサンプル・プロジェクトの作成」を参照してください。
トランスポート構成の処理フロー
新しいカスタム・トランスポート・プロバイダでは、特定の実行時インタフェースを実装している必要があります。トランスポートSDKインタフェースの概要、および関連するクラスは、「トランスポートSDKのインタフェースおよびクラス」を参照してください。インタフェースとクラスの詳細は、Oracle Service Bus Java APIリファレンスを参照してください。
ヒント:
サンプル・ソケット・トランスポート・プロバイダの場合、これらのインタフェースの実装はsample-transport/srcディレクトリにあります。
カスタム・トランスポート・プロバイダを開発するときに、次のインタフェースを実装する必要があります。
TransportProvider
TransportWLSArtifactDeployer
TransportEndPoint
InboundTransportMessageContext
OutboundTransportMessageContext
Transformer
注意:
トランスポート・プロバイダで、エンドポイントの作成時にWebLogic Server変更リストに記載される、WebLogic Server関連のアーティファクト(EAR、WAR、JARファイルなど)をデプロイする必要がある場合は、TransportWLSArtifactDeployerインタフェースのみを実装してください。詳細は、「TransportWLSArtifactDeployerの実装が適している場合」を参照してください。
トランスポート・プロバイダで、非標準のペイロード・バインディング(ストリーム、DOM、SAXまたはXMLBean以外)を使用する必要がある場合のみ、Transformerインタフェースを実装してください。詳細は、「メッセージの変換」を参照してください。
ここでは、メッセージとエラーの処理、メッセージの変換、トランスポート・オプション、環境値、UDDIレジストリなど、カスタム・トランスポート・プロバイダを開発する際に考慮する必要があるいくつかのトピックについて説明します。
トランスポートSDKは、メッセージ・ペイロードを柔軟に表現できる点に特徴があります。ペイロードを処理するすべてのトランスポートSDK APIが、Sourceインタフェースを使用してメッセージ・コンテンツを表示します。
トランスポートSDKに用意されているSource派生のメッセージ・タイプには、次のものがあります。
StreamSource
ByteArraySource
StringSource
XmlObjectSource
DOMSource
MFLSource
SAAJSource
MimeSource
注意:
StreamSourceは、1度しか使用できないソースです。つまり、マーカー・インタフェースSingleUseSourceを実装しています。他のSourceの場合は、ソースから入力ストリームを何度でも取得できます。Sourceオブジェクトでは、毎回、入力ストリームを最初から取得します。SingleUseSourceの場合は、入力ストリームは1度しか取得できません。入力は、1度使用すると削除されます(ネットワーク・ソケットからのストリームなど)。ただし、Service Busでは、SingleUseSourceからの入力をバッファに入れ、基本的には、そのデータのすべてのコピーを保持します。
転送プロバイダにSourceクラスを実装する場合、入力ストリームを最初から再取得できるかどうかを判断する必要があります。入力ストリームが、その性質上1度しか使用できないものである場合は、Sourceクラスでマーカー・インタフェースSingleUseStreamを実装してください。
トランスポートSDKには、ソース・オブジェクト間で変換するための、一連のトランスフォーマが用意されています。一連の標準表現との変換をサポートするものであれば、必要に応じて、新しいトランスフォーマを実装できます。詳細は、「メッセージの変換」および「メッセージ・コンテンツの設計」を参照してください。
インバウンド・エンドポイントを実装して、インバウンド・メッセージをService Busランタイムに配信する場合、TransportManager.receiveMessage()をコールする必要があります。トランスポート・プロバイダは、ストリーム、DOM、SAXなどの標準のソース派生オブジェクトやカスタム・オブジェクトのいずれかで、着信メッセージ・ペイロードを自由に公開します。
Service Busでは、リクエストを送信したクライアントに対してレスポンス・メッセージを返信する必要がある場合、InboundTransportMessageContextでメソッドsetResponseMetaData()、setResponsePayload()およびclose()を呼び出して、レスポンスの返信準備ができていることを示します。Service Busランタイムがインバウンド・トランスポート・メッセージ・コンテキストのclose()メソッドをコールする場合、これは、インバウンド・リクエスト・メッセージを受信したスレッドとは異なるスレッドから行われます。トランザクションのセマンティクスに影響する可能性があるため、トランスポート・プロバイダでは、このことを認識している必要があります。また、close()が呼び出されるまで、トランスポート・プロバイダは、レスポンス・ペイロードまたはメタデータへのアクセスを試行できません。
各トランスポート・プロバイダは、メタデータおよびヘッダーをPOJO (Plain Old Java Object)に格納し、パイプラインに渡す必要があります。Service BusでXMLBeanが必要となる場合もあります。このような場合は、APIを使用して、POJOからXMLBeanへの変換を実装する必要があります。
POJOからXMLに変換するために、実装する必要があるメソッドを次に示します。
RequestHeaders.toXML() RequestMetaData<T>.toXML() ResponseHeaders.toXML() ResponseMetaData<T>.toXML()
逆方向(XMLからPOJO)の場合は、次のメソッドを実装する必要があります。
TransportEndPoint.createRequestMetaData(RequestMetaDataXML) InboundTransportMessageContext.createResponseMetaData(ResponseMetaDataXML)
各トランスポート・プロバイダは、Service Busに対して、着信メッセージ・ペイロードの文字セット・エンコーディングを指定します。送信メッセージ(アウトバウンド・リクエストとインバウンド・レスポンス)の場合、Service Busに対して、送信ペイロードに使用する文字セット・エンコーディングを指定します。文字セット・エンコーディングは、リクエストとレスポンスのメタデータに指定されます。
ほとんどの場合、トランスポートがメタデータに挿入する文字コード・エンコーディングは、サービス構成で静的に指定されているエンコードです。数少ない例外の1つがHTTPトランスポートです。HTTPトランスポートでは、charsetパラメータがあるかどうかContent-Typeを検査し、サービスに構成されているすべてのエンコーディングをオーバーライドします。この処理は、HTTP仕様に準拠する上で必要です。他の転送プロトコルでも、同様な問題を処理する必要がある場合があります。
ヒント:
通常、サービスのエンコーディングは固定です。SHIFT_JISに指定されているプロキシに対して、UTF-16でエンコードされたメッセージを送信すると、通常、エラーと見なされます。トランスポート・プロバイダは、単にエンコーディングを確認する目的で、メッセージを検査する必要はありません。
送信メッセージの場合、トランスポート・プロバイダがService Busに対してアウトバウンド・リクエストに必要なエンコーディングを指定し、Service Busが必要に応じて変換を実行します。
発信メッセージの場合、トランスポートは常にこのエンコーディングに基づいている必要があります。また、このエンコーディングは、サービス構成に指定されているエンコーディングと同じであるとはかぎりません。不一致がある場合、転送では不一致を許可できますが、転送以外の部分がエラーとみなして例外をスローする可能性があります。また、転送には、エンコーディング要素を空白のままにする、追加オプションがあります。これにより、パイプラインでは、自由にエンコーディングを指定できます(パススルーを使用する場合など)。
特定のトランスポート・プロバイダがプロキシ・サービス・エンドポイントをサポートしている場合、ルーティング手順でそのプロバイダのプロキシ・サービスにルーティングするように、リクエスト・パイプラインを構成できます。さらに、パブリッシュ・アクション、またはビジネス・サービスではなくプロキシ・サービスに対してメッセージを送信するサービス・コールアウト・アクションが発生する場合があります。この使用例は、同じ場所に配置された呼出しと呼ばれます。
トランスポート・プロバイダは、同じ場所に配置された呼出しを認識し、それに応じて呼出しを処理する必要があります。プロキシ・サービス・エンドポイントの実装の性質によって異なりますが、トランスポート・プロバイダは呼出しの最適化を選択できます。その場合、呼出しは、トランスポート通信スタック全体およびすべてのインバウンド認可および認証を経由せずに、すぐにTransportManager.receiveMessage()を実質的に呼び出す直接呼出しになります。
ヒント:
Service Busは、この最適化をHTTP、ファイル、電子メールおよびFTPトランスポート・プロバイダで実装しています。JMSプロバイダでは、送信操作と受信操作のトランザクション・セマンティクスを分離する必要があるため、この最適化は使用されません。
カスタム・トランスポート・プロバイダでこの最適化を使用する場合は、CoLocatedMessageContextクラスを拡張して、TransportProvider.sendMessageAsync()が呼び出されたときにsend()メソッドをコールする必要があります。
Service Busランタイムがアウトバウンド・エンドポイントにメッセージを送信し、レスポンス・メッセージが返される場合、トランスポート・プロバイダは、このレスポンスを非同期で返す必要があります。TransportSendListener.onReceiveResponse()メソッドまたはTransportSendListener.onError()メソッドは、TransportProvider.sendMessageAsync()が呼び出されたスレッドとは異なるスレッドから呼び出される必要があるということです。
トランスポート・プロバイダで、非同期レスポンス・オプションの使用時に、JMSリクエストやHTTPリクエストへのレスポンスなど、レスポンスを非同期で取得する組込みのメカニズムがある場合、これは自然に行われます。ただし、トランスポート・プロバイダで、レスポンスを非同期で取得する組込みのメカニズムがない場合は、ブロック方式でアウトバウンド・リクエストを実行し、TransportManagerHelper.schedule()メソッドを使用して、新しいワーカー・スレッドをスケジュールできます。この場合、レスポンスはTransportSendListenerにポストされます。
Service Busで、リクエスト・ペイロードをアウトバウンド・メッセージに設定するかまたはレスポンス・ペイロードをインバウンド・メッセージに設定する必要がある場合、Sourceインタフェースから派生したオブジェクトを介して設定を行うようにトランスポート・プロバイダに依頼します。トランスポート・プロバイダでは、基底のトランスポート・レイヤーで必要な表現を決定し、Transformer.transform()メソッドを使用して、Sourceオブジェクトを目的のソースに変換する必要があります。
ヒント:
メッセージ変換の詳細は、「メッセージ・コンテンツの設計」を参照してください。組込み変換のリストは、「組込みのトランスフォーメーション」および「SourceおよびTransformerクラスとインタフェース」を参照してください。
カスタム・トランスポート・プロバイダでは、新しい種類のトランスフォーメーションをサポートできます。アウトバウンド・メッセージを送信するために、トランスポート・プロバイダがDOMオブジェクトを使用する必要があるとします。setRequestPayload(Source src)で呼び出された場合、トランスポート・プロバイダは、次のメソッドを呼び出す必要があります。
TransportManagerHelper.getTransportManager().getTransformer(). transform(src, DOMSource.class, transformOptions)
メソッドの戻り値はDOMSourceで、DOMノードを取得する際に使用されます。
注意:
トランスポート・プロバイダでストリームが必要な場合は、簡単な方法を使用できます。各Sourceオブジェクトでは、ストリームへのトランスフォーメーションをネイティブにサポートしています。
新しいトランスフォーメーションをカスタム・トランスポート・プロバイダに追加できます。たとえば、XYZSourceと呼ばれる、新しい種類のSource派生クラスを追加するとします。パフォーマンス上の理由から、トランスポート・プロバイダではXYZSourceから2つの標準SourceオブジェクトXmlObjectSourceおよびStreamSourceのいずれかへの変換を提供することをお薦めします。このような変換を行わない場合は、XYZSourceのStreamSource表現に基づいた汎用トランスフォーマが使用されます。もちろん、XYZSourceが内部構造を持たない単純なバイト・ベースのSourceである場合は、通常は、汎用トランスフォーマで十分です。TransportManagerに登録されているカスタム・トランスフォーマは、スレッド・セーフかつステートレスであることが前提です。
添付ファイルをサポートする場合、トランスポート・プロバイダには次の3つのオプションがあります。
TransportMessageContextが返すSourceは、MessageContextSourceのインスタンスである必要があります。このオプションには、MessageContextSourceでは、コンテンツがすでにコア・メッセージSourceと添付ファイルSourceに区分されている必要があるという制約があります。
SourceはMimeSourceのインスタンスで、Headersオブジェクトにはマルチ・パートContent-Typeヘッダーが含まれています。
Content-Typeは、固有の値multipart/relatedを持つ、トランスポート・プロバイダに事前定義されたヘッダーです。HTTPトランスポートと電子メール・トランスポートはいずれも、この3つ目のオプションに基づいて添付ファイルをサポートします。
TransportOptionsオブジェクトは、メッセージを送受信する際のオプションを指定するために使用されます。TransportOptionsオブジェクトは、インバウンド・メッセージの場合、トランスポート・プロバイダからトランスポート・マネージャに渡されます。アウトバウンド・メッセージの場合は、TransportOptionsオブジェクトは、Service Busランタイムからトランスポート・マネージャに渡され、最後にトランスポート・プロバイダに渡されます。
トランスポート・プロバイダは、TransportManager.receiveMessage()に次のパラメータを提供します。
QOS: exactly-onceまたはbest-effortのサービス品質を指定します。exactly-onceのサービス品質は、着信メッセージがトランザクション対応の場合に指定されます。
エラー発生時にスロー: このフラグを設定すると、Service Busのパイプラインの処理中にエラーが発生した場合に、メソッドTransportManager.receiveMessage()の呼ばれた側に対して、例外がスローされます。例外スローのオプションには、インバウンド・メッセージに対して例外を返したり、エラーからレスポンス・メッセージを生成して、そのレスポンス・メッセージでインバウンド・メッセージに通知するものがあります。通常、QOSがexactly-once(トランザクション対応のメッセージ)の場合は、「エラー発生時にスロー」をtrueに設定します。
たとえば、JMS/XAではこのフラグをtrueに設定し、同じリクエスト・スレッドで例外をスローするため、例外をロールバックするようにマークできます。HTTPでは再試行のメカニズムがないため、このフラグをfalseに設定します。エラーがステータス・コードに変換され、レスポンス・メッセージが返されます。
トランスポート固有の不透明なデータ: 不透明なデータは、トランスポート・プロバイダによって設定された任意のデータで、パイプラインを介してアウトバウンド呼出しに渡されます。この方法を使用すると、インバウンドとアウトバウンドで同じトランスポートを使用する場合に、パフォーマンスを最適化できます。不透明なデータは、パイプラインを介して、インバウンド・トランスポートからアウトバウンド・トランスポートに直接渡されます。たとえば、HTTPトランスポート・プロバイダでは、IDのパススルー伝播を効率的にサポートするために、ユーザー名とパスワードをインバウンドからアウトバウンドに直接渡すことができます。
アウトバウンド処理の場合、Service Busランタイムは、トランスポート・マネージャにパラメータを指定します。トランスポート・マネージャは、これらのパラメータのいくつかを内部的に使用し、TransportProvider.sendMessageAsync()に伝播します。これらのパラメータには、以下が含まれます。
QOS: exactly-onceのサービス品質を実現可能かどうかを指定します。たとえば、HTTPでは、サービス品質をexactly-onceに設定している場合、HTTP呼出しはブロックされています。best-effortに設定している場合、HTTP呼出しはブロックされません。
モード: 一方向または双方向(リクエスト/レスポンス)を指定します。詳細は、「トランスポート・プロバイダのモード」を参照してください。
URI、再試行間隔、回数: トランスポート・プロバイダは、URIを使用してアウトバウンド・トランスポート接続を初期化します。たとえば、HTTPトランスポート・プロバイダは、新しいHttpURLConnectionをインストールする際にURIを使用します。トランスポート・プロバイダでは、再試行間隔および回数を使用する必要はありません。
OperationName: トランスポート・プロバイダは、使用されているアウトバウンドWebサービスを認識する必要がある場合にOperationNameを使用します。トランスポート・マネージャは、このパラメータを使用してモニター統計を追跡します。
トランスポート固有の不透明なデータ: トランスポート固有の不透明なデータの例としては、HTTPの認可ヘッダーの値があります。
リクエスト・モードは、REQUEST_ONLY(一方向とも呼ばれる)およびREQUEST_RESPONSEの2つの値を持つ列挙値として定義されます。これらのモードは、リクエストおよびレスポンスについて次のように解釈されます。
アウトバウンド・リクエストでは、パイプラインがTransportOptionsを介してモードを示し、トランスポート・プロバイダはそのモードを使用する必要があります。
インバウンド・リクエストでは、パイプラインがモードを認識し、REQUEST_ONLYモードを算出した場合は、インバウンド・リクエストを閉じてレスポンスを送信しません。
パイプラインがレスポンスを送信する場合は、レスポンスが空のときでもレスポンスが発生します。
本質的に一方向のトランスポートでは、トランスポートでレスポンス・メタデータを指定する必要はありません。
実行時例外がトランザクション対応モデルに与える影響については、3つの異なるケースがあります。発生例を次に示します。
ビジネス・サービスのアウトバウンド呼出しの前に、リクエスト・パイプラインで例外が発生します。
ビジネス・サービスの呼出し中に、例外が発生します。
ビジネス・サービスの呼出しの後に、レスポンス・パイプラインで例外が発生します。
この場合、図40-2に示すように、ビジネス・サービスのアウトバウンド呼出しの前に、例外がリクエスト・パイプラインで発生します。たとえば、リクエスト・メッセージのコンテンツに対して特定のXQueryを実行すると、例外が生成されます。
リクエスト・パイプラインにユーザー構成エラー・ハンドラを構成している場合、ユーザー構成に従ってエラーが処理されます。それ以外の場合は、引数としてreceiveMessage()呼出しに渡されるトランスポート・オプションに従って、プロキシ・サービスがTransportManager.receiveMessage()の呼出し時に例外を捕捉するか、レスポンス・メタデータを介してエラーのInboundTransportMessageContext.close()メソッドで通知されます。プロキシ・サービスが、例外をスローする必要があることを示している場合は、try/catch句でreceiveMessage()を囲み、トランザクションをロールバックするようにマークします。
この場合、図40-3に示すように、ビジネス・サービスの呼出し中に、例外が発生します。アウトバウンド・トランスポート・プロバイダでは、次の処理のいずれかが行われます。
TransportProvider.sendMessageAsync()から例外をスローします。たとえば、外部サービスへのソケット接続を確立している最中にエラーが発生した場合、アウトバウンド・プロバイダは例外をスローします。このような状況は、誤ったURLや接続障害などのために、ビジネス・サービスを呼び出すことができない場合に発生します。この場合、トランスポート・プロバイダが例外を生成する必要があります。
TransportSendListener.onError()を介して、リスナーに通知します。たとえば、ビジネス・サービスを呼び出したときに、呼出しがエラーになった場合(SOAPフォルトなど)、トランスポート・プロバイダは例外を生成するかわりにTransportSendListener.onError()を呼び出す必要があります。
最初の例では、「発生例1: アウトバウンド呼出し前に例外が発生」で説明したものと同じ例外処理が行われます。2つ目の例では、レスポンス・パイプラインにエラー・ハンドラを構成している場合、ユーザー構成に従ってエラーが処理されます。それ以外の場合は、InboundTransportMessageContext.close()のレスポンス・メタデータを介して、例外がプロキシ・サービス・エンドポイントに逆に伝播されます。
この場合、図40-4に示すように、ビジネス・サービスをコールした後、レスポンス・パイプラインで例外が発生します。レスポンス・パイプラインにユーザー定義のエラー・ハンドラがない場合、適切なレスポンス・メタデータを持つInboundTransportMessageContext.close()メソッドを使用して、エラーがプロキシ・サービス・エンドポイントに通知されます。インバウンド・トランスポート・エンドポイントが同期トランザクション・エンドポイントの場合、リクエストを受信したときにアクティブであったトランザクションがまだなおアクティブで、ロールバックできることが保証されます。インバウンド・エンドポイントがトランザクション対応でも同期型でもない場合、ロールバックするインバウンド・トランザクション・コンテキストがないため、他のアクションを実行する必要があります。
ビジネス・サービスが外部サービスへのアクセスを試行した時に、外部サービス・アプリケーションにSOAPフォルトなどのエラーが発生する場合、アプリケーションが修正されるまで、サービスによる後続の再試行によってエラーが発生します。Service Busによって、アプリケーション・エラーの識別が可能になり、トランスポートを使用するときにアプリケーション・エラーの再試行を回避するオプションが提供されます。
この項では、トランスポート内のアプリケーション・エラーを捕捉して、アプリケーション・エラーの再試行を回避できるようにトランスポートを構成する方法について説明します。
トランスポート・プロバイダのコードでは、アプリケーション・エラーが発生した条件を識別する必要があります。たとえば、HTTPトランスポートにおいて、アプリケーション・エラーとは、HTTPレスポンスに500ステータス・コードがあり、空でないペイロードがあり、サービス・タイプと一致するコンテンツ・タイプ(SOAP用XMLなど)を持つエラーです。エラーが定義されたアプリケーション・エラー条件を満たしている場合、次のメソッドの1つを用いて、「TRANSPORT_ERROR_APPLICATION」タイプを返します。
リクエストでエラーが発生する: TransportProvider.sendMessageAsync()においてTRANSPORT_ERROR_APPLICATIONエラー・コードでTransportExceptionをスローします。
レスポンスでエラーが発生する: TRANSPORT_ERROR_APPLICATIONエラー・コードを使用してTransportSendListener.onError()をスケジュールします。
トランスポートSDKは、発生したアプリケーション・エラーを識別して、それに応じて処理できます。トランスポートSDKは、アプリケーション・エラーをパイプラインの$fault変数に送信することもできます。
<Transport>Config.xmlファイルでは、/OSB_ORACLE_HOME/lib/modules/oracle.servicebus.kernel-api.jarのTransportCommon.xsdスキーマに準拠して、<ProviderConfiguration>要素の子として次の要素を入力します。
<declare-application-errors>true</declare-application-errors>
ユーザーがトランスポートを選択する場合、このエントリはビジネス・サービスのメインの「トランスポート構成」ページの「アプリケーション・エラーの再試行」オプションを提供します。この要素を入力しないと、デフォルト値はfalseで、アプリケーション・エラーを捕捉できず、アプリケーション・エラーの再試行オプションが提供されません。
Service Busはトランスポートにある接続エラーを識別できます。これにより、アクセスできないエンドポイントURIを自動オフラインにするように、トランスポートSDKをトリガーします。たとえば、Service Busが管理対象サーバーで実行されているクラスタで、サービス・リクエストに対して接続エラーが発生した管理対象サーバーは、自動的にエンドポイントURIをオフラインとしてマークできます。
次の方法でエンドポイントURIを再有効化することができます。
ビジネス・サービスを構成すると、接続エラー後に再試行の頻度と回数を決定するために再試行回数と再試行の反復間隔を設定できます。再試行により自動的にエンドポイントURIが再有効化された後の、サービスへの正常な接続。
再試行の反復間隔をゼロ(0)にすると、エンドポイントURIは無期限でオフラインになるため、手動で再有効化する必要があります。
ビジネスサービスのダッシュボード上のFusion Middleware Controlから、オフラインになっているエンドポイントURIを手動で再有効化できます。
自動化接続エラーの機能は次の状況に対して適用されません。
サービス・パイプラインはエンドポイントURIを動的に$outbound/ctx:transport/ctx:uriに設定すると、トランスポートSDKは、エンドポイントURIが サービス構成に設定されていないので、URIをオフラインにできません。
トランスポートSDKは接続ステータスを保持しません。サーバーを再起動すると、すべてのエンドポイントURIはオンラインと見なされます。
詳細は、『Oracle Service Busの管理』のビジネス・サービス用のエンドポイントURIの管理とモニターに関する項を参照してください。
エラーがスローされた後、接続エラーは、自動で影響を受けるエンドポイントURIをオフラインにするようにトランスポートSDKを設定します。トランスポート・プロバイダのコードでは、接続エラーが発生した条件を識別する必要があります。たとえば、Service Bus HTTPトランスポートにおいて、接続エラーとは、エンドポイントURIで接続しようとするとき、HTTPレスポンスに404ステータス・コードがありまたはIOExceptionが発生するかを識別します。
例外が定義された接続エラー条件を満たしている場合、次のメソッドの1つを用いて、「TRANSPORT_ERROR_CONNECTION」タイプを返します。
リクエストでエラーが発生する: TransportProvider.sendMessageAsync()においてTRANSPORT_ERROR_CONNECTIONエラー・コードでTransportExceptionをスローします。
レスポンスでエラーが発生する: TRANSPORT_ERROR_CONNECTIONエラー・コードを使用してTransportSendListener.onError()をスケジュールします。
これにより、トランスポートSDKは、接続エラーが発生したときにそのエラーを識別し、それに応じて処理できるようになります。また、トランスポートSDKは、接続エラーをパイプラインの$fault変数に送信し、それをレスポンスに追加します。
トランスポートの実装に使用するカスタム環境の値タイプを定義できます。TransportProvider.getEnvValues()メソッドを使用してエンドポイントに対する環境値を返す際に、これらのカスタム・タイプの環境値を宣言できます。
トランスポートを使用した場合、構成をインポートした後、値をカスタマイズするか、検索して置き換えるか、保存するためにService Busで使用される標準的な環境値と同じようにカスタム環境の値タイプを使用できます。たとえば、トランスポート構成にあるサービス・アカウントまたはJMSキューにリファレンスを定義して保持することができます。環境値のタイプは環境、操作、およびセキュリティの3つのカテゴリに分けられます。
カスタム変数は<Transport>Config.xmlファイルに追加します。XML構造を決定するスキーマはTransportCommon.xsdで、/OSB_ORACLE_HOME/lib/servicebus-schemas.jarにあります。
次に示すのは、JMSトランスポートのJmsConfig.xmlにあるカスタム・セキュリティ変数の例です。
<env-value-type>
<name>JMS Service Accounts</name>
<localized-display-name>
<localizer-class>com.bea.wli.sb.transports.messages.
TransportsTextLocalizer</localizer-class>
<message-id>JMS_SERVICE_ACCOUNTS</message-id>
</localized-display-name>
<localized-description>
<localizer-class>com.bea.wli.sb.transports.messages.
TransportsTextLocalizer</localizer-class>
<message-id>JMS_SERVICE_ACCOUNTS</message-id>
</localized-description>
<simple-value>true</simple-value>
<category>security</category>
</env-value-type>
カスタム環境の値タイプに関する主要な要素の説明は、次のとおりです。
name:トランスポートSDKで使用する変数名です。
display-name: Service Busユーザー・インタフェースに表示する変数名です。次に、ローカライゼーションの代替手段を示します。
localized-display-name: display-nameの代替のローカライズされたバージョン。
localizer-class:ローカライズされたdisplay-nameを含むローカライゼーション・プロパティのテキスト・ファイル。.properties拡張子は必須ではありません。
message-id: 表示名の値を提供するローカライゼーション・プロパティ・ファイルにあるプロパティ。
description: 環境値タイプの説明。ローカライゼーションでは、display-nameで説明されているlocalizer-classとmessage-idの子要素のかわりにlocalized-description要素を使用します。
simple-value: 環境値タイプが「環境」カテゴリである場合、simple-valueはService Busの検索と置換の機能を使用してこのタイプを検索できるかを決定します(trueまたはfalseの値)。
category: 環境、セキュリティまたは操作の任意の環境値のカテゴリ。カテゴリがセキュリティまたは操作である場合、構成をインポートするときに環境値のタイプを保持するかどうかを決定できます。カテゴリが環境である場合、環境値のタイプを、検索および置換に使用できます。
UDDI (Universal Description, Discovery, and Integration)は、インターネット全体にわたるWebサービスを説明および検索するための標準のメカニズムです。カスタム・トランスポート・プロバイダに基づいて、プロキシ・サービスをUDDIレジストリにパブリッシュできます。これにより、ビジネス・サービスをホストするサービスからプロキシ・サービスを異なるドメインのService Busサーバーにインポートできます。
プロキシ・サービスをパブリッシュするには、トランスポート・プロバイダは、TransportProviderConfiguration XMLスキーマ定義のUDDIセクションで、トランスポートのタイプを表すtModelを定義する必要があります。このtModelには、CategoryBagおよびkeyedReferenceが含まれている必要があります。また、keyedReferenceでは、tModelKeyがUDDIタイプのカテゴリ・システムに設定され、keyValueがtransportになっている必要があります。このtModelでは、UDDI V3 tModelキーのみ指定する必要があります。UDDIがこのトランスポートのタイプにtModelを定義している場合は、定義をコピーして、UDDIセクションに貼り付けてください。(スキーマで生成されるインタフェースの詳細は、「スキーマで生成されるインタフェース」を参照してください)。
次の例は、そのようなtModelの例を示します。
tModelの例
<?xml version="1.0" encoding="UTF-8"?>
<ProviderConfiguration xmlns="http://www.bea.com/wli/sb/transports">
. . .
. . .
<UDDI>
<TModelDefinition>
<tModel tModelKey="uddi:bea.uddi.org:transport:socket">
<name>uddi-org:socket</name>
<description>Socket transport based webservice</description>
<overviewDoc>
<overviewURL useType="text">
http://www.bea.com/wli/sb/UDDIMapping#socket
</overviewURL>
</overviewDoc>
<categoryBag>
<keyedReference keyName="uddi-org:types:transport"
keyValue="transport"
tModelKey="uddi:uddi.org:categorization:types"/>
</categoryBag>
</tModel>
</TModelDefinition>
</UDDI>
</ProviderConfiguration>
UDDIがこのトランスポートのタイプにtModelを定義していない場合、Service Busは、構成されたレジストリに、ここで定義するtModelをパブリッシュできます。Service BusにUDDIレジストリを構成している場合、「tModelsをレジストリにロード」オプションを指定できます。このオプションにより、カスタム・トランスポート・プロバイダのtModelを含め、Service BusのすべてのtModelが、UDDIレジストリにパブリッシュされます。トランスポート・プロバイダをデプロイすると、UDDIレジストリの構成を更新して、tModelをパブリッシュできます。
UDDIのエクスポート中に、TransportProvider.getBusinessServicePropertiesForProxy(Ref)が呼び出され、生成されたマップがUDDIレジストリにパブリッシュされます。UDDIのインポート処理中に、情報が失われることなくビジネス・サービスの定義を正確に作成できるよう、プロバイダは、ビジネス・サービスの重要なプロパティすべてをマップ内に確実に保持します。
UDDIのインポート中に、TransportProvider.getProviderSpecificConfiguration(Map)が呼び出され、プロバイダ固有のエンドポイント構成スキーマに準拠するXmlObjectが生成されて、サービス定義に含められます。
個々のサービス登録を処理する、2セットのトランスポート・プロバイダ・インタフェースが用意されています。TransportProviderには、作成、更新、削除、サスペンド、再開などのメソッドがあります。また、TransportWLSArtifactDeployerにも同じメソッドがあります。この項では、これら2つの実装について説明します。また、TransportWLSArtifactDeployerを実装する必要がある場合についても説明します。
TransportWLSArtifactDeployerを実装するのは、プロバイダが、Oracle Service BusドメインのOracle WebLogic Serverアーティファクトを変更する必要がある場合のみです。TransportWLSArtifactDeployerのメソッドは、管理サーバーでのみ呼び出すことができます。この場合、渡されたDomainMBean引数を使用して変更が行われ、クラスタ全体に変更が伝播されます。
TransportProviderメソッドは、ドメインのすべてのサーバー(管理サーバーおよび管理対象サーバー)で呼び出されます。管理対象サーバーでService Busドメインのアーティファクトは変更できないため、TransportProviderのメソッドを呼び出すのは、内部データ構造を更新する場合のみです。
特定のトランスポート・プロバイダがTransportWLSArtifactDeployerインタフェースを実装する場合、TransportProviderの対応するメソッドが呼び出される前に、TransportWLSArtifactDeployerのメソッドが呼び出されます。たとえば、TransportProvider.createEndPoint()が呼び出される前に、TransportWLSArtifactDeployer.onCreate()が呼び出されます。TransportWLSArtifactDeployerの詳細は、「汎用インタフェースのサマリー」を参照してください。
JDeveloperおよびOracle Service Busコンソールの両方で、カスタム・トランスポートのオンライン・ヘルプを提供できます。どちらの場合も、独自の統合ヘルプ・システムが用意されます。JDeveloperでは、ヘルプを既存のヘルプ・システムに組み込む必要があります。Oracle Service Busコンソールでは、図40-5に示すように、カスタム・トランスポートのヘルプ単体を独自のブラウザ・ウィンドウで表示します。カスタム・トランスポートのヘルプは、サービス定義エディタのトランスポート構成ページで「ヘルプ」アイコンをクリックすると表示されます。ヘルプの提供は省略可能です。しかし、ヘルプを提供することで、サービスの作成者に転送の構成プロセスを説明する際に非常に役立つ場合があります。
グラフィックスを含まない1つの単純なテキスト・ページから、多数のグラフィックス、PDFファイル、埋め込みのビデオなどを含む複数のページまで、提供するヘルプ・コンテンツのタイプを非常に柔軟に決定できます。たとえば、単一のHTMLファイルを作成し、そのファイルをヘルプ・リンクから参照できます。つまり、ビジネス・サービスおよびプロキシ・サービスのトランスポート構成フィールドについて説明し、さらに概要も示すヘルプ・ファイルを個別に作成できます。Oracle Service BusコンソールおよびJDeveloperに対して個別のヘルプ・トピックを作成するか、同じトピックを使用できます。
Service Busでは、サンプルのヘルプ実装をそのサンプル・ソケット・トランスポートに用意しています。これは、OSB_ORACLE_HOME/samples/servicebus/sample-transportにあります。サンプル・トランスポートは、独自のカスタム・トランスポートおよびヘルプを開発する上で良い参考となる実装です。
この項では、Oracle Service Busコンソールで実行時にカスタム・トランスポートのヘルプを提供する方法を示します。Service Busは、図40-5に示されているように、カスタム・トランスポートのヘルプを、ブラウザで独立したヘルプ・ページとして表示します。
図40-6は、カスタム・トランスポートのコンソール・ヘルプ・フレームワークの概要図を示しています。
特定のService Busインタフェースを実装することにより、ユーザーがコンソールでカスタム・トランスポート構成ページの「ヘルプ」アイコンをクリックすると、getHelpPage()メソッドを使用して単一のHTMLページが起動します。HTMLファイルには、次の内容を含めることができます。
テキスト、インラインCSS定義、インラインJavaScript関数
グラフィックスおよびその他のリソースへの参照。これは、これらのリソースがWebアプリケーションまたは外部Webサイトでホストされている場合に限ります。
ほとんどの場合、カスタム・トランスポートのすべてのヘルプにテキストおよびインライン形式を含めることができます。
ただし、グラフィックスおよびその他の外部リソースを含むすべての機能を備えたWebベースのヘルプを提供する場合は、それらのリソースがWebアプリケーションまたは外部Webサイトでホストされている必要があります。それらの外部リソースをHTMLファイルで参照するか、または、HTMLファイルから外部の場所へのリンクを提供する必要があります。たとえば、サンプル・ソケット・トランスポートのヘルプでは、最初のHTMLファイルから、カスタムWebアプリケーションで実行されているグラフィックスを含むヘルプ・トピックへのリンクを提供しています。埋め込みのJavaScript呼出しを使用して、希望する拡張されたヘルプのURLに自動的にリダイレクトするようにHTMLファイルをセット・アップすることもできます。
次のタスクを実行して、コンソールでオンライン・ヘルプを実装します。
ヘルプ・ファイルの作成が終了したら、「トランスポート・プラグインのヘルプのパッケージ化」の説明に従い、ファイルをパッケージ化します。
カスタム・トランスポートの構成ユーザー・インタフェースを開発するには、TransportUIBindingインタフェースをカスタム・クラスに実装します。Oracle Service Busコンソールでトランスポート構成のユーザー・インタフェースのヘルプを提供するには、CustomHelpProviderインタフェースも実装する必要があります。CustomHelpProviderには、Oracle Service Busコンソールでトランスポート構成ページのヘルプを起動するために必要なgetHelpPage()メソッドが含まれます。
サンプル・ソケット・トランスポートでは、OSB_ORACLE_HOME/samples/servicebus/sample-transport/src/com/bea/alsb/transports/sockにあるSocketTransportUIBindingクラスでCustomHelpProviderを実装します。
次の例には、CustomHelpProviderの実装を示すスニペットが含まれています。
例 - コンソール・オンライン・ヘルプを提供するCustomHelpProviderの実装
public class SocketTransportUIBinding
implements TransportUIBinding, CustomHelpProvider {
...
public Reader getHelpPage() {
String helpFile = "help/en/contexts_socketTransport.html";
ClassLoader clLoader = Thread.currentThread().getContextClassLoader();
InputStream is = clLoader.getResourceAsStream(helpFile);
InputStreamReader helpReader = null;
if(is!=null)
helpReader = new InputStreamReader(is);
else
SocketTransportUtil.logger
.warning(SocketTransportUtil.formatText(uiContext.getLocale(), "800138"));
return helpReader;
}
}
前述の例では、getHelpPage()によって、Oracle Service BusコンソールがブラウザにHTMLページを送信するために使用するReaderストリームが返されます。helpFileのパスは、トランスポートJAR内のルートからの相対パスです。
複数の言語でヘルプを提供する場合は、ローカライズされたコンテンツへの適切なパスの提供に役立つTransportUIContext.getLocale()を使用します。この場合は、/help/<locale>/<localized>.htmlにロケールの値を指定します。
CustomHelpProviderインタフェースの実装の例のhelp/en/contexts_socketTransport.htmlで示すように、起動するためのgetHelpPage()メソッドのHTMLファイルを作成できます。ヘルプの実装を簡潔に維持する場合は、テキスト、インラインCSS定義、およびインラインJavaScript関数を使用するHTMLファイルを作成してください。こうすることで、グラフィックスまたはその他の外部リソースをホストする個別のWebアプリケーションを作成する必要がなくなります。
ただし、グラフィックスやその他のリソースを含むように拡張したヘルプを作成する場合は、それらの外部リソースを次のようにHTMLファイルで参照してください。
img src="/help_socket/help/en/wwimages/addProject.gif"
または
a href="http://www.yoursite.com"
次の例で示されているように、埋込みのJavaScriptコールを使用して、拡張されたヘルプに自動的にリダイレクトするようにHTMLファイルを設定することもできます。この例では、サンプル・ソケット・トランスポートのHTMLページから、拡張されたhelp_socket Webアプリケーションのヘルプ・コンテンツにリダイレクトしています。
例 - リダイレクトを提供するJavaScript関数
<script language="JavaScript" type="text/javascript"> <!-- Begin window.location="/help_socket/help/en/example.html"; // End --> </script>
サンプル・ソケット・トランスポートのHTMLファイルが、拡張されたヘルプへのリンクを提供しています。HTMLファイルcontexts_socketTransport.htmlは、OSB_ORACLE_HOME/samples/servicebus/sample-transport/resources/help/en/にあります。
トランスポートのヘルプで基本的なテキストのHTMLファイル以上のものが必要な場合は、次の様々な方法を使用して、グラフィックスやその他のリソースを含めた拡張ヘルプを提供することができます。
自己完結型のHTMLファイルから既存のURLにリンクします(トランスポートに関するドキュメントを含む既存のWebサイトがある場合など)。必要な作業は、自己完結型のHTMLファイルからURLへのリンクの提供のみです。外部サイトでホストされているグラフィックスやその他のリソースへの参照を挿入することもできます。
拡張されたヘルプ用のWebアプリケーションを作成し、そのアプリケーションをトランスポートにバンドルしてそのリンクを設定するか、HTMLファイルからグラフィックスやその他のリソースを参照します。このトピックでは、トランスポートEARにバンドルして、拡張されたトランスポートのヘルプを表示するWebアプリケーションの作成手順について説明します。
Webアプリケーション用にMETA-INF/application.xmlおよびWEB-INF/web.xmlで説明したファイルを作成します。
application.xmlで、WebアプリケーションのルートURLに使用されるコンテキスト・ルートをWebアプリケーションに提供します。次の例は、ソケット・トランスポートWebアプリケーションの例のコンテキスト・ルートを示します。
例 - サンプル・ソケット・トランスポートのWebアプリケーションのapplication.xml
<application>
<display-name>Socket Transport</display-name>
<description>Socket Transport</description>
<module>
<web>
<web-uri>webapp</web-uri>
<context-root>help_socket</context-root>
</web>
</module>
</application>
サンプル・ソケット・トランスポートのapplication.xmlファイルは、OSB_ORACLE_HOME/samples/servicebus/sample-transport/META-INF/にあります。
このエントリは、ファイル・システムのディレクトリ/webappを別名のWebアプリケーションのルートURLにマップします。
http://server:port/help_socket/
ヘルプ・ファイルが、/help/en/などのディレクトリのWebアプリケーション内にある場合、拡張されたヘルプの完全なURLは次のようになります。
http://server:port/help_socket/help/en/index.html
ただし、ヘルプへの内部リンクの場合は、単に次のようになります。
/help_socket/help/en/index.html
ここで、index.htmlは、リンク先のHTMLページです。
web.xmlで、Webアプリケーションの表示名および説明を入力します。これは、標準のデプロイメント記述子情報です。次の例は、ソケット・トランスポートWebアプリケーションの例の名前および説明を示します。
例 - サンプル・ソケット・トランスポートのWebアプリケーションのweb.xml
<web-app>
<display-name>Sample Socket Transport Help WebApp</display-name>
<description>
This webapp implements the help webapp for the socket transport.
</description>
</web-app>
サンプル・ソケット・トランスポートのweb.xmlファイルは、OSB_ORACLE_HOME/samples/servicebus/sample-transport/webapp/WEB-INF/にあります。
拡張されたヘルプ・ファイルを作成し、Webアプリケーション・ディレクトリ内にパッケージ化します。サンプル・ソケット・トランスポートでは、ヘルプ・ファイルはOSB_ORACLE_HOME/samples/servicebus/sample-transport/resources/help/enに格納されています。
注意:
ソケット・トランスポートのヘルプ・ファイルが/webappディレクトリに格納されてない理由は、helpディレクトリにJDeveloperとOracle Service Busコンソールの両方のヘルプ・ファイルとリソースが格納されているためです。サンプル・ソケットのANTビルドが、トランスポートJARおよびトランスポートEARを作成する場合は、ヘルプは別の方法でパッケージ化されます。トランスポートEARのビルドの場合、ヘルプ・ファイルは/webappディレクトリの下に移動します。
カスタム・トランスポートをJDeveloperのサービス構成で使用できるようにする場合、サービス定義エディタに表示されるページのヘルプ・トピックを組み込むことができます。このためには、既存のヘルプJARファイルにヘルプ・ファイルを追加します。
JDeveloperでオンライン・ヘルプを提供するには:
トランスポート・プラグインには、次のものが含まれている必要があります。
トランスポート・クラスおよびサポート・ファイルを含むトランスポートJARファイル。JARファイルには、/help/enディレクトリのヘルプ・リソースが含まれます。
/webapp/help/enディレクトリのヘルプ・リソースなどの実行時コンポーネントを含むトランスポートEARファイル。
/enディレクトリを使用して、ローカライゼーションをサポートするようにヘルプがパッケージ化される点に注意してください。ローカライズを提供するには、ロケールごとにプラグインを作成する必要があります。トランスポートおよびヘルプのパッケージ化の詳細は、「カスタム・トランスポート・プロバイダのパッケージ化とデプロイ」を参照してください。
