|
|
転送 SDK は、転送プロトコルと Oracle Service Bus ランタイム システムとの間に抽象のレイヤを提供します。この抽象のレイヤでは、新しい転送プロバイダを開発して Oracle Service Bus にプラグインできます。転送 SDK インタフェースは、HTTP などの転送プロトコルと Oracle Service Bus ランタイムの間を橋渡しします。
| ヒント : | この章を始める前に、必ず「設計上の考慮事項」を確認してください。 |
この章では、カスタム転送プロバイダの開発に必要な基本手順について説明します。この章の内容は以下のとおりです。
カスタム転送プロバイダを設計および構築するプロセスは複雑です。この節では、転送プロバイダを開発する際の推奨事項について説明します。カスタム転送プロバイダの開発は、以下の基本的な手順に分類されます。
「開発の基本手順」では、スキーマのコンフィグレーション、インタフェースの実装を含め、転送プロバイダを開発する際に必要な手順について説明します。
「開発の重要トピック」では、開発サイクルで参照する必要がある、いくつかのトピックについて詳細に説明します。ここでは、「メッセージの処理」、「メッセージの変換」、「エラー処理」などのトピックについて詳細に説明します。
転送プロバイダのパッケージ化およびデプロイの詳細については、「転送プロバイダのデプロイ」を参照してください。
カスタム転送プロバイダを開発する前に、以下のような設計上の問題について、検討および確認する必要があります。
カスタム転送プロバイダを開発する際に従う基本手順は以下のとおりです。
3. 転送固有のアーティファクトの XML スキーマ ファイルの作成
5. XMLBean TransportProviderConfiguration の定義
図 3-1 は、カスタム転送プロバイダを作成する際に、実装およびコンフィグレーションする必要があるコンポーネントを示しています。転送マネージャは、転送プロバイダの登録を制御および管理し、Oracle Service Bus との通信を処理します。転送プロバイダは、転送エンドポイント (メッセージの送信元または送信先となるリソース) のライフサイクルおよび実行時の動作を管理します。カスタム転送プロバイダを開発するには、転送 SDK を使用します。転送 SDK を使用してカスタム転送プロバイダを開発することが、この章のテーマです。
実装およびコンフィグレーションする必要がある転送サブシステムには、以下のものがあります。
新しい転送プロバイダを開発する前に、プロジェクトの適切なディレクトリ構造をセットアップします。サンプル ソケット転送プロバイダに使用されているディレクトリ構造をコピーすることをお勧めします。この構造の詳細については、「サンプルの場所とディレクトリ構造」を参照してください。
XML スキーマ (xsd) ファイルを作成し、転送固有の定義を記述します。このファイルは、サンプル ソケット転送プロバイダ用に開発されたスキーマ ファイルを基に作成できます。
ALSB_HOME/samples/servicebus/sample-transport/schemas/
SocketTransport.xsd
| 注意 : | SocketTransport.xsd ファイルにより、TransportCommon.xsd ファイルがインポートされます。このファイルは、サービス エンドポイントのコンフィグレーション用の基本となるスキーマ定義ファイルです。このファイルは、BEA_HOME/ALSB_HOME/lib/sb-schemas.jar にあります。続行する前に、このファイルのコンテンツを確認しておきます。 |
前の節「3. 転送固有のアーティファクトの XML スキーマ ファイルの作成」で説明した XML スキーマ ファイルに、次の転送固有のアーティファクトの XML スキーマを定義します。
| 注意 : | 転送プロバイダ固有のメタデータおよびヘッダを定義する場合は、単純な XML タイプのみサポートされています。たとえば、ネストされた要素を持つ複雑なタイプはサポートされていません。さらに、特定の名前を持つヘッダは最大 1 つしか使用できないという制限もあります。 |
| ヒント : | これらの各スキーマ定義は、対応する Java ファイルに変換された後、コンパイルされます。サンプル ソケット転送プロバイダの変換済み Java ソース ファイルは、次のディレクトリにあります。sample-transport/build/classes/com/bea/alsb/transports/sock/impl |
EndPointConfiguration は、エンドポイント コンフィグレーションの基本型で、着信エンドポイントおよび発信エンドポイントのデプロイメントと操作に必要なパラメータの完全なセットを表します。このコンフィグレーションは、汎用的な部分とプロバイダ固有の部分で構成されます。EndPointConfiguration スキーマ定義の詳細については、TransportCommon.xsd ファイルのドキュメント要素を参照してください。
プロバイダ固有のエンドポイント コンフィグレーションをスキーマ ファイルに指定する必要があります。コード リスト 3-1 に、SocketTransport.xsd の抜粋を示します。
<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 のメッセージ メタデータを Oracle Service Bus ランタイムに配信する必要があります。「要求/応答のメタデータの処理」も参照してください。
RequestMetaDataXML は、同じ RequestMetaData POJO を XML で表現したものです。この XML 表現では、Apache XML Bean テクノロジを使用します。発信要求のメタデータ全体を特定の XML フラグメントに設定するなど、メッセージを処理するときにメタデータの XML 表現を必要とするパイプラインでの操作を伴う場合のみ、Oracle Service Bus ランタイムで必要になります。
要求メタデータのコンフィグレーションをスキーマ ファイルに指定する必要があります。コード リスト 3-2 に、SocketTransport.xsd の抜粋を示します。
<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 のコンフィグレーションをスキーマ ファイルに指定する必要があります。コード リスト 3-2 に、SocketTransport.xsd の抜粋を示します。
<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 のコンフィグレーションをスキーマ ファイルに指定する必要があります。コード リスト 3-2 に、SocketTransport.xsd の抜粋を示します。
<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 end point 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 end point connection.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
ResponseHeadersXML は、一連の応答ヘッダの基本型です。ResponseHeadersXML のコンフィグレーションをスキーマ ファイルに指定する必要があります。コード リスト 3-2 に、SocketTransport.xsd の抜粋を示します。
<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 ファイルは、転送プロバイダ ルート ディレクトリの config ディレクトリにあります。サンプル ソケット転送プロバイダを実装する場合、このファイル (SocketConfig.xml) の場所については、「サンプルの場所とディレクトリ構造」を参照してください。
inbound-direction-supported 要素を true に設定する。 outbound-direction-supported 要素を true に設定する。 self-described 要素の値を true に設定する。自己記述転送では、そのサービスがエンドポイント コンフィグレーションに基づいて形式 (スキーマまたは WSDL) を記述します。UDDI 要素を含める。詳細については、「UDDI レジストリへのプロキシ サービスのパブリッシュ」を参照してください。| ヒント : | TransportProviderConfiguration のスキーマは、BEA_HOME/ALSB_HOME/lib/sb-schemas.jar にある TransportCommon.xsd に定義されています。詳細については、スキーマ ファイルを参照してください。 |
Oracle Service Bus Console を使用してビジネス サービスまたはプロキシ サービスを追加する場合、サービスの作成ウィザードのメニューから、転送プロバイダを選択します。このメニューには、Oracle Service Bus で用意されている転送プロバイダ、および転送 SDK で開発されたカスタム転送プロバイダが表示されます。
この節では、カスタム転送プロバイダを Oracle Service Bus Console のユーザ インタフェースにバインドする、転送 SDK API コンポーネントについて説明します。プロバイダをユーザ インタフェースに接続するには、これらの API を実装する必要があります。
| ヒント : | この節では、サービスの作成ウィザードに慣れていることを前提としています。詳細な例については、「ソケット転送のコンフィグレーションのサンプル」を参照してください。 |
public boolean isServiceTypeSupported(BindingTypeInfo binding)
このメソッドにより、転送プロバイダが、選択したサービスの種類に適しているかどうかが判定されます。
public TransportUIError[] validateMainForm(TransportEditField[] fields)
public TransportEditField[] getEditPage(EndPointConfiguration config, BindingTypeInfo binding) throws TransportException
転送 SDK は、コンフィグレーション ページにフィールドを表示する、TransportUIObjects のセットを提供します。たとえば、テキスト ボックス、チェックボックス、およびその他のタイプの UI 要素を追加できます。これらを作成するには、TransportUIFactory を使用します。作成したら、同じファクトリを使用して追加のプロパティを指定して、サービスの作成ウィザードで表示可能な TransportEditField オブジェクトを取得します。
使用可能な TransportUIObjects の詳細なリストについては、Javadoc を参照してください。
| ヒント : | イベントを大部分の UI フィールドに関連付けることができます。イベントは、TransportUIBinding クラスのコールバック メカニズムのように動作するため、コンフィグレーション ページをリフレッシュ、検証、および更新することができます。イベントがトリガされると、ウィザードにより次のメソッドが呼び出されます。updateEditPage(TransportEditField[] fields, String name) throws TransportException |
TransportUIError[] validateProviderSpecificForm(TransportEditField[] fields)
public TransportViewField[] getViewPage(EndPointConfiguration config) throws TransportException
void validateEndPointConfiguration(TransportValidationContext context)
エラーが報告されない場合は、新しいエンドポイントが作成されます。次に、転送マネージャにより次のメソッドが呼び出されます。
TransportEndPoint createEndPoint(EndPointOperations.Create context) throws TransportException
このメソッドが正常に返されると、新しいサービスが Oracle Service Bus Console にリストされ、基底の転送コンフィグレーションが TransportProvider のエンドポイントに関連付けられます。
| 注意·:· | エンドポイント コンフィグレーションは、Oracle Service Bus セッションに格納されます。サーバを再起動するときに、転送プロバイダで保持したり復元したりする必要はありません。 |
| ヒント : | サンプル ソケット転送プロバイダの場合、これらのインタフェースの実装は sample-transport/src ディレクトリにあります。 |
新しいカスタム転送プロバイダでは、以下のランタイム インタフェースを実装している必要があります。転送 SDK インタフェースの概要、および関連するクラスについては、「転送 SDK のインタフェースおよびクラス」を参照してください。インタフェースとクラスの詳細については、Oracle Service Bus の Javadoc の説明を参照してください。
| ヒント : | サンプル ソケット転送プロバイダの場合、これらのインタフェースの実装は sample-transport/src ディレクトリにあります。 |
| 注意·:· | 転送プロバイダで、エンドポイントの作成時に WebLogic Server 変更リストに記載される、WebLogic Server 関連のアーティファクト (EAR/WAR/JAR ファイルなど) をデプロイする必要がある場合は、TransportWLSArtifactDeployer インタフェースのみを実装してください。詳細については、「TransportWLSArtifactDeployer の実装が適している場合」を参照してください。 |
| 注意 : | 転送プロバイダで、非標準の、つまり、ストリーム、DOM、SAX、XMLBean などではないペイロード バインディングを使用する必要がある場合は、転送インタフェースのみを実装してください。詳細については、「メッセージの変換」を参照してください。 |
デプロイメントの詳細については、「転送プロバイダのデプロイ」を参照してください。
この節では、カスタム転送プロバイダの開発時に経験することがある、いくつかのトピックについて説明します。次のようなトピックがあります。
この節では、転送プロバイダでのメッセージ処理について説明します。以下のトピックがあります。
転送 SDK は、メッセージ ペイロードを柔軟に表現できる点に特徴があります。ペイロードを処理するすべての転送 SDK API が、Source インタフェースを使用してメッセージ コンテンツを表示します。
転送 SDK に用意されている Source 派生のメッセージ タイプには、以下のものがあります。
| 注意 : | StreamSource は、1 度しか使用できないソースです。つまり、マーカ インタフェース SingleUseSource を実装しています。他の Source の場合は、ソースから入力ストリームを何度でも取得できます。Source オブジェクトでは、毎回、入力ストリームを最初から取得します。SingleUseSource の場合は、入力ストリームは 1 度しか取得できません。入力は、1 度使用すると削除されます (ネットワーク ソケットからのストリームなど)。ただし、Oracle Service Bus では、SingleUseSource からの入力をバッファに入れ、基本的には、そのデータのすべてのコピーを保持します。 |
| 注意 : | 転送プロバイダに Source クラスを実装する場合、入力ストリームを最初から再取得できるかどうかを判断する必要があります。入力ストリームが、その性質上 1 度しか使用できないものである場合は、Source クラスでマーカ インタフェース SingleUseStream を実装することをお勧めします。 |
転送 SDK には、Source オブジェクト間で変換するための、一連のトランスフォーマが用意されています。一連の標準表現との変換をサポートするものであれば、必要に応じて、新しいトランスフォーマを実装できます。詳細については、「メッセージの変換」を参照してください。また、「メッセージ コンテンツの設計」も参照してください。
着信エンドポイントを実装して、着信メッセージを Oracle Service Bus ランタイムに配信する場合、TransportManager.receiveMessage() を呼び出す必要があります。転送プロバイダは、ストリーム、DOM、SAX などの標準の Source 派生オブジェクトやカスタム オブジェクトのいずれかで、着信メッセージ ペイロードを自由にエクスポーズします。
Oracle Service Bus では、要求を送信したクライアントに対して応答メッセージを返信する必要がある場合、InboundTransportMessageContext でメソッド setResponseMetaData()、setResponsePayload()、および close() を呼び出して、応答の返信準備ができていることを示します。Oracle Service Bus ランタイムが着信転送メッセージ コンテキスト close() メソッドを呼び出す場合、これは、着信要求メッセージを受信したスレッドとは異なるスレッドから行われます。トランザクションのセマンティクスに影響する可能性があるため、転送プロバイダでは、このことを認識している必要があります。また、close() メソッドが呼び出されるまで、転送プロバイダは、応答ペイロードおよびメタデータへのアクセスを試行できません。
各転送プロバイダでは、メタデータおよびヘッダを POJO (Plain Old Java Object) に格納し、パイプラインに渡す必要があります。Oracle Service Bus で XMLBean が必要となる場合もあります。このような場合は、API を使用して、POJO から XMLBean への変換を実装する必要があります。
POJO から XML に変換するために、実装する必要があるメソッドを以下に示します。
逆方向 (XML から POJO) の場合は、以下のメソッドを実装する必要があります。
各転送プロバイダは、Oracle Service Bus に対して、着信メッセージ ペイロードの文字セット エンコーディングを指定します。送信メッセージ (発信要求と着信応答) の場合、Oracle Service Bus に対して、送信ペイロードに使用する文字セット エンコーディングを指定します。文字セット エンコーディングは、要求と応答のメタデータに指定されます。
ほとんどの場合、転送がメタデータに挿入する文字コード エンコーディングは、サービス コンフィグレーションで静的に指定されているエンコードです。数少ない例外の 1 つが HTTP 転送です。HTTP 転送では、「charset」パラメータがあるかどうか Content-Type を検査し、サービスにコンフィグレーションされているすべてのエンコーディングをオーバーライドします。この処理は、HTTP 仕様に準拠する上で必要です。他の転送プロトコルでも、同様な問題を処理する必要がある場合があります。
| ヒント : | 通常、サービスのエンコーディングは固定です。SHIFT_JIS に指定されているプロキシに対して、UTF-16 でエンコードされたメッセージを送信すると、通常、エラーと見なされます。転送プロバイダは、単にエンコーディングを確認する目的で、メッセージを検査する必要はありません。 |
送信メッセージの場合、転送プロバイダが Oracle Service Bus に対して発信要求に必要なエンコーディングを指定し、Oracle Service Bus が必要に応じて変換を実行します。
発信メッセージの場合、転送は常にこのエンコーディングに基づいている必要があります。また、このエンコーディングは、サービス コンフィグレーションに指定されているエンコーディングと同じであるとは限りません。不一致がある場合、転送では不一致を許可できますが、転送以外の部分がエラーとみなして例外を送出する可能性があります。また、転送には、エンコーディング要素を空白のままにする、追加オプションがあります。これにより、パイプラインでは、自由にエンコーディングを指定できます (パススルーを使用する場合など)。
特定の転送プロバイダがプロキシ サービス エンドポイントをサポートしている場合、ルーティング手順でそのプロバイダのプロキシ サービスにルーティングするように、要求パイプラインをコンフィグレーションできます。さらに、パブリッシュ アクション、またはビジネス サービスではなくプロキシ サービスに対してメッセージを送信するサービス コールアウト アクションが発生する場合があります。この使用例は、同じ場所に配置された呼び出しと呼ばれます。
転送プロバイダは、同じ場所に配置された呼び出しを認識し、それに従って処理する必要があります。プロキシ サービス エンドポイントの実装の性質によって、転送プロバイダは、このような、転送通信スタック全体およびすべての着信認可/認証を経由しないように呼び出しを最適化して、直ちに TransportManager.receiveMessage() を効率的に呼び出す、直接呼び出しを選択できます。
| ヒント : | Oracle Service Bus は、この最適化を HTTP、ファイル、電子メール、および FTP 転送プロバイダで実装しています。JMS プロバイダでは、送信操作と受信操作のトランザクション セマンティクスを分離する必要があるため、この最適化は使用されません。 |
カスタム転送プロバイダでこの最適化を使用する場合は、CoLocatedTransportMessageContext クラスを拡張して、TransportProvider.sendMessageAsync() が呼び出されたときに send() メソッドを呼び出す必要があります。
Oracle Service Bus ランタイムが発信エンドポイントにメッセージを送信し、応答メッセージが返される場合、転送プロバイダは、この応答を非同期で返す必要があります。TransportSendListener.onReceiveResponse() メソッドまたは TransportSendListener.onError() メソッドは、TransportProvider.sendMessageAsync() が呼び出されたスレッドとは異なるスレッドから呼び出される必要があるということです。
転送プロバイダで、非同期応答オプションの使用時に、JMS 要求や HTTP 要求への応答など、応答を非同期で取得する組み込みのメカニズムがある場合、これは自然に行われます。ただし、転送プロバイダで、応答を非同期で取得する組み込みのメカニズムがない場合は、ブロック方式で発信要求を実行し、TransportManagerHelper.schedule() メソッドを使用して、新しいワーカ スレッドをスケジュールできます。この場合、応答は TransportSendListener にポストされます。
Oracle 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 つのオプションがあります。
multipart/related を持つ、転送プロバイダに事前定義されたヘッダである。添付ファイルのサポートでは、HTTP 転送と電子メール転送はいずれも、この 3 つ目のオプションに基づいています。
TransportOptions オブジェクトは、メッセージを送受信する際のオプションを指定するために使用されます。TransportOptions オブジェクトは、着信メッセージの場合、転送プロバイダから転送マネージャに渡されます。発信メッセージの場合は、TransportOptions オブジェクトは、Oracle Service Bus ランタイムから転送マネージャに渡され、最後に転送プロバイダに渡されます。
転送プロバイダは、TransportManager.receiveMessage() に以下のパラメータを提供します。
TransportManager.receiveMessage() の呼ばれた側に対して、例外が送出されます。例外送出のオプションには、着信メッセージに対して例外を返したり、エラーから応答メッセージを生成して、その応答メッセージで着信メッセージに通知するものがあります。通常、QOS が exactly-once (トランザクション対応のメッセージ) の場合は、THROW_ON_ERROR を true に設定します。
たとえば、JMS/XA ではこのフラグを true に設定し、同じ要求スレッドで例外を送出するため、例外をロールバックするようにマークできます。HTTP では再試行のメカニズムがないため、このフラグを false に設定します。エラーがステータス コードに変換され、応答メッセージが返されます。
発信処理の場合、Oracle Service Bus ランタイムは、転送マネージャに以下のパラメータを指定します。転送マネージャは、これらのパラメータのいくつかを内部的に使用し、TransportProvider.sendMessageAsync() に伝播します。パラメータには次のものが含まれます。
要求モードは、REQUEST_ONLY (「一方向」とも呼ばれる) および REQUEST_RESPONSE の 2 つの値を持つ列挙値として定義されます。これらのモードは、要求および応答について次のように解釈されます。
実行時例外がトランザクション対応モデルに与える影響については、3 つの異なるケースがあります。これらのケースには、以下のようなものがあります。
図 3-2 に示すように、ビジネス サービスの発信呼び出しの前に、例外が要求パイプラインで発生します。たとえば、要求メッセージのコンテンツに対して特定の XQuery を実行すると、例外が生成されます。
要求パイプラインにユーザ コンフィグレーション エラー ハンドラをコンフィグレーションしている場合、ユーザ コンフィグレーションに従ってエラーが処理されます。それ以外の場合は、引数として receiveMessage() 呼び出しに渡される転送オプションに従って、プロキシ サービスが TransportManager.receiveMessage() の呼び出し時に例外を捕捉するか、応答メタデータを介してエラーの InboundTransportMessageContext.close() メソッドで通知されます。プロキシ サービスが、例外を送出する必要があることを示している場合は、try/catch 句で receiveMessage() を囲み、トランザクションをロールバックするようにマークします。
図 3-3 に示すように、ビジネス サービスの呼び出し中に、例外が発生します。発信転送プロバイダでは、次の処理のいずれかが行われます。
TransportProvider.sendMessageAsync() から例外を送出する。たとえば、外部サービスへのソケット接続を確立している最中にエラーが発生した場合、発信プロバイダは例外を送出します。このような状況は、誤った URL や接続障害などのために、ビジネス サービスを呼び出すことができない場合に発生します。この場合、転送プロバイダが例外を生成する必要があります。 TransportSendListener.onError() を介して、リスナに通知する。たとえば、ビジネス サービスを呼び出したときに、呼び出しがエラーになった場合 (SOAP 障害など)、転送プロバイダは、例外を生成する代わりに TransportSendListener.onError() を呼び出す必要があります。
最初の例では、ケース 1 で説明したものと同じ例外処理が行われます。2 つ目の例では、応答パイプラインにエラー ハンドラをコンフィグレーションしている場合、ユーザ コンフィグレーションに従ってエラーが処理されます。それ以外の場合は、InboundTransportMessageContext.close() の応答メタデータを介して、例外がプロキシ サービス エンドポイントに逆に伝播されます。
図 3-4 に示すように、ビジネス サービスを呼び出した後、応答パイプラインで例外が発生します。応答パイプラインにユーザ定義のエラー ハンドラがない場合、適切な応答メタデータを持つ InboundTransportMessageContext.close() メソッドを使用して、エラーがプロキシ サービス エンドポイントに通知されます。着信転送エンドポイントが同期トランザクション エンドポイントの場合、要求を受信したときにアクティブであったトランザクションがまだなおアクティブで、ロールバックできることが保証されます。着信エンドポイントがトランザクション対応でも同期型でもない場合、ロールバックする着信トランザクション コンテキストがないため、他のアクションを実行する必要があります。
ビジネス サービスが外部サービスへのアクセスを試行した時に、外部サービス アプリケーションに SOAP 障害などのエラーが発生する場合、アプリケーションが修正されるまで、サービスによる後続の再試行によってエラーが発生します。
Oracle Service Bus によって、アプリケーション エラーの識別が可能になり、転送を使用するときにアプリケーション エラーの再試行を回避するオプションが提供されます。
この節では、転送内のアプリケーション エラーを捕捉して、アプリケーション エラーの再試行を回避できるように転送をコンフィグレーションする方法について説明します。
転送プロバイダのコードでは、アプリケーション エラーが発生した条件を識別する必要があります。
たとえば、Oracle Service Bus HTTP 転送において、アプリケーション エラーとは、HTTP 応答に 500 ステータス コードがあり、空でないペイロードがあり、サービス タイプと一致するコンテンツ タイプ (SOAP 用 XML など) を持つエラーです。
エラーが定義されたアプリケーション エラー条件を満たしている場合、以下のメソッドの 1 つを用いて、[TRANSPORT_ERROR_APPLICATION] タイプを返します。
転送 SDK は、発生したアプリケーション エラーを識別して、それに応じて処理することができます。
転送 SDK は、アプリケーション エラーをパイプラインの $fault 変数に送信することもできます。
<Transport>Config.xml ファイルでは、 /osb_10.3/lib/sb-schemas.jar の TransportCommon.xsd スキーマに準拠して <ProviderConfiguration> 要素の子として次の要素を入力します。
<declare-application-errors>true</declare-application-errors>
ユーザが転送を選択する場合、このエントリはビジネス サービスの [メイン転送のコンフィグレーション] ページの [アプリケーション エラーの再試行] オプションを提供します。この要素を入力しないと、デフォルト値は false で、アプリケーション エラーを捕捉できず、アプリケーション エラーの再試行オプションが提供されません。
Oracle Service Bus は転送にある接続エラーを識別することができます。これにより、アクセスできないエンドポイント URI を自動オフラインにするように、転送 SDK をトリガします。たとえば、管理対象サーバで実行される Oracle Service Bus のあるクラスタに、サービス要求に対して接続エラーが発生される管理対象サーバは、自動的にエンドポイント URI をオフラインとしてマークすることができます。
以下の方法でエンドポイント URI を再有効化することができます。
詳細については、『Oracle Service Bus オペレーション ガイド』の「ビジネス サービスのエンドポイント URI の管理」を参照してください。
この節では、転送における接続エラーを識別する方法について説明します。エラーが送出された後、接続エラーは、自動で影響を受けるエンドポイント URI をオフラインにするように転送 SDK を設定します。
転送プロバイダのコードでは、接続エラーが発生した条件を識別する必要があります。
たとえば、Oracle Service Bus HTTP 転送において、接続エラーとは、エンドポイント URI で接続しようとするとき、HTTP 応答に 404 ステータス コードがあり、または IOException が発生するかを識別します。
例外が定義された接続エラー条件を満たしている場合、以下のメソッドの 1 つを用いて、[TRANSPORT_ERROR_CONNECTION] タイプを返します。
これにより、転送 SDK は、接続エラーが発生した時にそのエラーを識別し、それに応じて処理できるようになります。
また、転送 SDK は、接続エラーをパイプラインの $fault 変数に送信し、それを応答に追加します。
この節では、転送の実装に使用するカスタム環境の値タイプを定義する方法について説明します。TransportProvider.getEnvValues() メソッドを使用してエンドポイントに対する環境値を返す際に、これらのカスタム タイプの環境値を宣言できます。
転送を使用した場合、コンフィグレーションをインポートした後、値をカスタマイズするか、検索して置き換えるか、保存するために Oracle Service Bus で使用される標準な環境値と同じようにカスタム環境の値タイプを使用できます。たとえば、転送コンフィグレーションにあるサービス アカウントまたは JMS キューにリファレンスを定義して保持することができます。
環境値のタイプは環境、操作、およびセキュリティの 3 つのカテゴリに分けられます。
カスタム変数は <Transport>Config.xml ファイルに追加します。XML 構造を決定するスキーマは TransportCommon.xsd で、/osb_10.3/lib/sb-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>
カスタム環境の値タイプに関する主要な要素の説明は、次のとおりです。
UDDI (Universal Description, Discovery, and Integration) は、インターネット上の Web サービスを記述および検索するための標準メカニズムです。カスタム転送プロバイダに基づいて、プロキシ サービスを UDDI レジストリにパブリッシュできます。これにより、ビジネス サービスをホストするサービスとして、プロキシ サービスを異なるドメインの Oracle Service Bus サーバにインポートできます。
プロキシ サービスをパブリッシュするには、転送プロバイダは、TransportProviderConfiguration XML スキーマ定義の「UDDI」セクションで、転送のタイプを表す tModel を定義する必要があります (スキーマで生成されるインタフェースの詳細については、「スキーマで生成されるインタフェース」を参照してください)。
この tModel には、CategoryBag および keyedReference が含まれている必要があります。また、keyedReference では、tModelKey が UDDI タイプのカテゴリ システムに設定され、keyValue が「transport」になっている必要があります。この tModel では、UDDI V3 tModel キーのみ指定する必要があります。
UDDI がこの転送のタイプに tModel を定義している場合は、定義をコピーして、UDDI セクションに貼り付けることをお勧めします。
コード リスト 3-6 に、このような 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 を定義していない場合、Oracle Service Bus は、コンフィグレーションされたレジストリに、ここで定義する tModel をパブリッシュできます。Oracle Service Bus に UDDI レジストリをコンフィグレーションしている場合、[tModel をレジストリにロード] オプションを指定できます。このオプションにより、カスタム転送プロバイダの tModel を含め、Oracle Service Bus のすべての tModel が、UDDI レジストリにパブリッシュされます。転送プロバイダをデプロイすると、UDDI レジストリのコンフィグレーションを更新して、tModel をパブリッシュできます。
UDDI のエクスポート中に、TransportProvider.getBusinessServicePropertiesForProxy(Ref) が呼び出され、生成されたマップが UDDI レジストリにパブリッシュされます。UDDI のインポート処理中に、情報が失われることなくビジネス サービスの定義を正確に作成できるよう、プロバイダは、ビジネス サービスの重要なプロパティすべてをマップ内に確実に保持します。
UDDI のインポート中に、TransportProvider.getProviderSpecificConfiguration(Map) が呼び出され、プロバイダ固有のエンドポイント コンフィグレーション スキーマに準拠する XmlObject が生成されて、サービス定義に含められます。
| ヒント : | OASIS (Organization for the Advancement of Structured Information Standards) では、UDDI 標準を作成しています。完全な技術仕様を含め、UDDI の詳細については、以下のサイトを参照してください。 http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=uddi-spec |
個々のサービス登録を処理する、2 セットの転送プロバイダ インタフェースが用意されています。TransportProvider には、作成、更新、削除、サスペンド、再開などのメソッドがあります。また、TransportWLSArtifactDeployer にも同じメソッドがあります。この節では、これら 2 つの実装について説明します。また、TransportWLSArtifactDeployer を実装する必要がある場合についても説明します。
TransportWLSArtifactDeployer を実装するのは、プロバイダが、Oracle Service Bus ドメインの WebLogic Server アーティファクトを変更する必要がある場合だけです。TransportWLSArtifactDeployer のメソッドは、管理サーバでのみ呼び出すことができます。この場合、渡された DomainMBean 引数を使用して変更が行われ、クラスタ全体に変更が伝播されます。
TransportProvider メソッドは、ドメインのすべてのサーバ (管理サーバおよび管理対象サーバ) で呼び出されます。管理対象サーバで Oracle Service Bus ドメインのアーティファクトは変更できないため、TransportProvider のメソッドを呼び出すのは、内部データ構造を更新する場合だけです。
特定の転送プロバイダが TransportWLSArtifactDeployer インタフェースを実装する場合、TransportProvider の対応するメソッドが呼び出される前に、TransportWLSArtifactDeployer のメソッドが呼び出されます。たとえば、TransportProvider.createEndPoint() が呼び出される前に、TransportWLSArtifactDeployer.onCreate() が呼び出されます。
TransportWLSArtifactDeployer の詳細については、「汎用インタフェースの概要」を参照してください。
設計環境 (Workshop for WebLogic) および実行時環境 (Oracle Service Bus Console) でカスタム転送のオンライン ヘルプを提供することができます。ヘルプの提供は省略可能です。しかし、ヘルプを提供することで、サービスの作成者に転送のコンフィグレーション プロセスを説明する際に非常に役立つ場合があります。
図 3-5 は、開発環境および実行時環境での、カスタム転送に付属するヘルプを示しています。
この節では、Workshop for WebLogic および Oracle Service Bus Console でカスタム転送のヘルプを提供するために使用できるさまざまなオプションについて説明します。
| 注意·:· | Workshop for WebLogic と Oracle Service Bus Console では、転送のコンフィグレーションにおいてユーザ インタフェースおよび機能の点で異なる可能性があるため、両方の環境で個別のヘルプ トピックを作成することを検討してください。 |
Workshop for WebLogic ヘルプは、Eclipse ヘルプ フレームワークに基づいています。Workshop for WebLogic でカスタム転送のヘルプを実装する場合、以下の選択肢があります。
Workshop for WebLogic で〔F1〕を押すと起動する状況依存ヘルプは、ヘルプ システム全体を表示する個別のヘルプ ウィンドウを表示するのではなく、Workshop for WebLogic 内でヘルプ トピックを表示します。図 3-6 は、Workshop for WebLogic で状況依存ヘルプがどのように表示されるかを示しています。
すべてのネイティブな Oracle Service Bus 転送は、それぞれの転送コンフィグレーション ウィザードおよびエディタから、状況依存ヘルプを提供します。
状況依存ヘルプの利点は、ユーザが Workshop for WebLogic を離れずに、対象のヘルプ トピックに迅速にアクセスできることです。これは、カスタム転送のヘルプで特に役立ちます。
Workshop for WebLogic の [ヘルプ] メニューからアクセスできる、Workshop for WebLogic ヘルプ システムで、カスタム転送のヘルプ コンテンツを提供できます。Workshop for WebLogic ヘルプを起動すると、個別のウィンドウがヘルプ システム全体の目次を表示します。
図 3-7 は、Workshop for WebLogic ヘルプ システムでの転送のオンライン ヘルプを示しています。
図 3-7 に示すように、カスタム転送のパッケージ化およびコンフィグレーション方法に応じて、ヘルプ トピックを、ヘルプ システムの目次の別の場所に表示させることができます。たとえば、転送のヘルプを Oracle Service Bus ヘルプ トピックの転送のセクションと結合したり、転送のヘルプをヘルプ システムの最上位で提供したりすることができます。
Oracle Service Bus Console で、実行時に転送コンフィグレーションのヘルプを提供することもできます。Oracle Service Bus Console は、独自の統合されたヘルプ システムを提供しますが、Oracle Service Bus は、図 3-8 に示すように、カスタム転送のヘルプを、そのブラウザ ウィンドウで独立して表示します。カスタム転送のヘルプは、転送コンフィグレーション ページで [ヘルプ] をクリックすると表示されます。
以降の節では、Workshop for WebLogic および Oracle Service Bus Console の両方で、カスタム転送のオンライン ヘルプを提供する方法を示します。
Workshop for WebLogic で、カスタム転送をサービスのコンフィグレーションで使用できるようにする場合、Workshop for WebLogic の状況依存ヘルプまたは Workshop for WebLogic ヘルプ システムのいずれか、あるいはその両方として表示されるヘルプ コンテンツを提供することができます。この節では、その方法を示します。
サンプル ソケット転送および Oracle Service Bus のネイティブな転送は、Workshop for WebLogic ヘルプのベストプラクティスの参照実装を提供します。この節では、これらを例として使用します。
転送のヘルプは、転送用に作成する Workshop for WebLogic プラグインの一部です。プラグインの作成の詳細については、「Workshop for WebLogic 用の Oracle Service Bus 転送の開発」を参照してください。
状況依存ヘルプを提供することで、ユーザが転送をコンフィグレーションしている Workshop for WebLogic で、転送コンフィグレーションに関する情報が直接提供されます。
Workshop for WebLogic のサービス コンフィグレーション ウィザードおよびサービス エディタの両方の転送コンフィグレーション ページで状況依存ヘルプを提供できます。
状況依存ヘルプを提供するには、以下の手順を実行する必要があります。
org.eclipse.help.contexts の例を参照してください。
このエントリは、context.xml ファイルを見つける場所をプラグインに示します。context.xml ファイルへのパスは、プラグインのルートからの相対パスです。
メインの Workshop for WebLogic ヘルプ システムに転送のヘルプを追加できます。図 3-7 に示すように、ヘルプ トピックが目次に表示されます。
primary 属性を設定します。primary="true" を設定します。primary="false" を設定します。
プラグインのパッケージ化の詳細については、「Workshop for WebLogic 用の Oracle Service Bus 転送の開発」を参照してください。
Eclipse ヘルプ フレームワークを基盤とする Workshop for WebLogic ヘルプは、この節で説明するリソースを必要とします。
このリファレンスの節を前の手順と共に使用して、Workshop for WebLogic での転送のヘルプの実装を行ってください。
| 注意·:· | Oracle Service Bus は、ALSB_HOME/samples/servicebus/sample-transport にあるサンプル ソケット転送で、サンプルのヘルプ実装を提供しています。サンプル転送は、独自のカスタム転送およびヘルプを開発する上で良い参考となる実装です。サンプルの plugin.xml は/eclipse サブディレクトリに、ヘルプ リソースは /help サブディレクトリにあります。 |
| 注意 : | ALSB_HOME/eclipse/plugins/com.bea.alsb.transports.<transport>_<version> にある Oracle Service Bus 転送プラグインも、カスタム転送と同様に、ヘルプを実装します。 |
この節では、以下の Workshop for WebLogic のヘルプ リソースについて説明します。
plugin.xml ファイルは、転送および転送のヘルプ ファイルを Workshop for WebLogic 環境に追加するための鍵となるファイルです。plugin.xml に、ヘルプの目次 (toc.xml) および状況依存ヘルプ (context.xml) のエントリを追加する必要があります。
コード リスト 3-1 は、ALSB_HOME/samples/servicebus/sample-transport/eclipse ディレクトリにあるサンプル ソケット転送の plugin.xml ファイルでの toc.xml および context.xml (contexts_socketTransport.xml) エントリを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
...
<extension
point="org.eclipse.help.toc">
<toc file="/help/en/toc.xml" primary="true"/>
</extension>
<extension
point="org.eclipse.help.contexts">
<contexts
file="/help/en/contexts_socketTransport.xml"
plugin="Socket_Transport"/>
</extension>
</plugin>
org.eclipse.help.toc 拡張ポイントは、Workshop for WebLogic ヘルプ システムの左側のナビゲーション領域への接続を作成します。
<toc file...> エントリは、転送のヘルプ用に作成したヘルプ トピックの階層を含む toc.xml ファイルを参照します。
primary="true" 属性は重要です。true に設定した場合、転送の目次が Workshop for WebLogic ヘルプ システムの最上位に表示されます。カスタム転送プラグインを JAR ファイルとしてパッケージ化する場合は、true に設定してください。
false に設定した場合、Workshop for WebLogic で、toc.xml が、メインの Oracle Service Bus ヘルプ システムなどの既存の toc.xml 階層に結合されます。詳細については、以下の toc.xml の節を参照してください。
org.eclipse.help.contexts のエントリにより、転送の Eclipse ベースの状況依存 (F1) ヘルプを実装できます。状況依存のヘルプ トピックのリンクは、Workshop for WebLogic の [ヘルプ] ビューの [関連トピック] 領域に表示されます。
プラグインのパッケージ化の詳細については、「Workshop for WebLogic 用の Oracle Service Bus 転送の開発」を参照してください。
toc.xml ファイルは、カスタム転送のヘルプが、Workshop for WebLogic ヘルプ システムの左側のナビゲーション領域にどのように表示されるかを決定します。転送のヘルプを、Workshop for WebLogic ヘルプ システムの目次の最上位に提供するか (コード リスト 3-2)、Oracle Service Bus 転送のヘルプ トピックに結合する (コード リスト 3-3) ことができます。
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Socket Transport Sample">
<topic label="Socket Transport Configuration Page (Business
Services)" href="help/en/tpSOCKETTransportBizService.html"/>
<topic label="Socket Transport Configuration Page (Proxy Services)"
href="help/en/tpSOCKETTransportProxyService.html"/>
<topic label="Configuring the Socket Transport Sample (Service
Bus Console)" href="help/en/example.html"/>
</toc>
転送のヘルプを Workshop for WebLogic ヘルプ システムの目次の最上位エントリとして追加する場合は、必ず plugin.xml の org.eclipse.help.toc 拡張ポイントで primary="true" を設定してください。
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc link_to="../com.bea.alsb.docs/toc.xml#alsbTransports"
label="Socket Transport Sample">
<topic label="Socket Transport Configuration Page (Business
Services)" href="help/en/tpSOCKETTransportBizService.html"/>
<topic label="Socket Transport Configuration Page (Proxy Services)"
href="help/en/tpSOCKETTransportProxyService.html"/>
<topic label="Configuring the Socket Transport Sample (Service Bus
Console)" href="help/en/example.html"/>
</toc>
コード リスト 3-3 に示されている toc.xml の結合は、alsbTransports というアンカーを含むメインの Oracle Service Bus ヘルプの toc.xml のその場所で目次を結合するように、Workshop for WebLogic ヘルプ フレームワークに指示します。
primary="false" を設定してください。
別のプラグインへの相対参照を使用するこの toc.xml の結合は、転送プラグインを展開ディレクトリとしてパッケージ化する場合にのみ可能です。
コード リスト 3-4 で示されている context.xml ファイルは、転送コンフィグレーション ウィザードおよびエディタ ページのコンテキスト ID をヘルプ トピックにマップします。ユーザが転送コンフィグレーション ページで〔F1〕を押すと、図 3-6 に示すように、Workshop for WebLogic が [ヘルプ] ビューにヘルプ リンクを表示します。
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.contexts"?>
<contexts>
<!-- デフォルトのソケット転送のヘルプ -->
<context id="tpSOCKETTransportBizService"
title="Socket Transport Configuration page (Business Service)">
<description>The Sample socket transport illustrates Transport SDK
concepts.</description>
<topic href="help/en/tpSOCKETTransportBizService.html"
label="Socket Transport Configuration Page (Business Services)"/>
</context>
<context id="tpSOCKETTransportBizWizard"
title="Socket Transport Configuration page (Business Service)">
<description>The Sample socket transport illustrates Transport SDK
concepts.</description>
<topic href="help/en/tpSOCKETTransportBizService.html"
label="Socket Transport Configuration Page (Business Services)"/>
</context>
<context id="tpSOCKETTransportProxyService"
title="Socket Transport Configuration page (Proxy Service)">
<description>The Sample socket transport illustrates Transport SDK
concepts.</description>
<topic href="help/en/tpSOCKETTransportProxyService.html"
label="Socket Transport Configuration Page (Proxy Services)"/>
</context>
<context id="tpSOCKETTransportProxyWizard"
title="Socket Transport Configuration page (Proxy Service)">
<description>The Sample socket transport illustrates Transport SDK
concepts.</description>
<topic href="help/en/tpSOCKETTransportProxyService.html"
label="Socket Transport Configuration Page (Proxy Services)"/>
</context>
</contexts>
<context> エントリがある点に注意してください。context id 属性の値は、ウィザードまたはエディタのユーザ インタフェースのコンテキスト ID です。topic href 属性は、ユーザが〔F1〕を押したときにリンクするヘルプ トピックを Workshop for WebLogic に示します。topic label 属性は、Workshop for WebLogic の [ヘルプ] ビューの [関連トピック] 領域に表示されるリンク テキストを決定します。description 要素は、ユーザが〔F1〕を押したときに、表示されたリンクの上にテキストを提供します。context id 属性のパターンを、正確なテキストで、大文字と小文字を区別して使用してください。id の値が正しくない場合、転送の状況依存ヘルプが機能しません。
<TRANSPORT_ID> の値は、転送の文字列 ID を設定する TransportProvider クラスの実装によって得られます。転送 ID に小文字を使用して名前を付けた場合でも、<TRANSPORT_ID> はすべて大文字である必要がある点に注意してください。
グラフィックスを含まない 1 つの単純なテキスト ページから、多数のグラフィックス、PDF ファイル、埋め込みのビデオなどを含む複数のページまで、提供するヘルプ コンテンツのタイプを非常に柔軟に決定できます。
たとえば、単一の HTML ファイルを作成し、そのファイルを toc.xml および context.xml ファイルから参照したり、ビジネス サービスおよびプロキシ サービスの転送コンフィグレーションのフィールドについて説明するヘルプ ファイルや、概要を示すヘルプ ファイルも個別に作成して、toc.xml および context.xml から、異なる組み合わせで 3 つのヘルプ ファイルを指し示すこともできます。
ヘルプ トピックとリソースは、toc.xml および context.xml でそれらを正確に参照しさえすれば、転送プラグインの任意の場所に格納することができます。
カスタム転送のヘルプの外観を Oracle Service Bus 転送のヘルプと同じにするには、既存の Oracle Service Bus 転送プラグインの HTML ファイルと CSS を使用します。転送のヘルプ ファイルは ALSB_HOME/eclipse/plugins/com.bea.alsb.transports.<transport>_<version>/help/en にあります。
Workshop for WebLogic と Oracle Service Bus Console では、転送のコンフィグレーションにおいてユーザ インタフェースおよび機能の点で異なる可能性があるため、両方の環境で個別のヘルプ トピックを作成することを検討してください。
転送プラグインのパッケージ化を JAR として行うか、展開ディレクトリとして行うかにかかわらず、転送のヘルプとその他のリソースの関係については、以下のパッケージ化構造が推奨されます。
/en ディレクトリを使用して、ローカライゼーションをサポートするようにヘルプがパッケージ化される点に注意してください。ローカライゼーションを行うには、Eclipse ドキュメントの説明に従って、各ロケールのプラグインを作成する必要があります。
| 注意 : | ヘルプ ファイルを doc.zip ファイルにパッケージ化することもできます。詳細については、『Eclipse Platform Plug-In Development Guide』の「Help server and file locations (英文)」を参照してください。 |
Eclipse ヘルプ フレームワークの詳細については、http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/guide/ua_help.htm にある Eclipse ヘルプ システムを参照してください。
プラグインのパッケージ化の詳細については、「Workshop for WebLogic 用の Oracle Service Bus 転送の開発」を参照してください。
この節では、Oracle Service Bus Console で実行時にカスタム転送のヘルプを提供する方法を示します。Oracle Service Bus は、図 3-8 に示されているように、カスタム転送のヘルプを、ブラウザで独立したヘルプ ページとして表示します。
図 3-9 は、カスタム転送の Oracle Service Bus Console ヘルプ フレームワークの概要を示しています。
特定の Oracle Service Bus インタフェースを実装し、getHelpPage() メソッドを使用すると、ユーザ インタフェースにフォーカスがある場合に、Oracle Service Bus Console でユーザが [ヘルプ] をクリックすると、単一の HTML ページが起動します。HTML ファイルには、以下を含めることができます。
ほとんどの場合、カスタム転送のすべてのヘルプにテキストおよびインライン形式を含めることができます。
ただし、グラフィックスおよびその他の外部リソースを含むすべての機能を備えた Web ベースのヘルプを提供する場合は、それらのリソースが Web アプリケーションまたは外部 Web サイトでホストされている必要があります。それらの外部リソースを HTML ファイルで参照するか、または、HTML ファイルから外部の場所へのリンクを提供する必要があります。たとえば、サンプル ソケット転送のヘルプでは、最初の HTML ファイルから、カスタム Web アプリケーションで実行されているグラフィックスを含むヘルプ トピックへのリンクを提供しています。埋め込みの JavaScript 呼び出しを使用して、希望する拡張されたヘルプの URL に自動的にリダイレクトするように HTML ファイルをセットアップすることもできます。
Oracle Service Bus Console でのカスタム転送のヘルプの作成には、以下のタスクが含まれます。
カスタム転送のコンフィグレーションのユーザ インタフェースを開発するには、TransportUIBinding インタフェースをカスタム クラスに実装します。Oracle Service Bus Console で転送コンフィグレーションのユーザ インタフェースのヘルプを提供するには、CustomHelpProvider インタフェースも実装する必要があります。CustomHelpProvider には、Oracle Service Bus Console で転送コンフィグレーション ページのヘルプを起動するために必要な getHelpPage() メソッドが含まれます。
サンプル ソケット転送では、ALSB_HOME/samples/servicebus/sample-transport/src/com/bea/alsb/transports/sock にある SocketTransportUIBinding.java クラスで CustomHelpProvider を実装します。
コード リスト 3-5 には、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(SocketTransportMessagesLogger.noHelpPageAvailableLoggable().
getMessage(uiContext.getLocale()));
return helpReader;
}}
コード リスト 3-5 では、Reader getHelpPage() が、Oracle Service Bus Console がブラウザに HTML ページを送信するために使用する Reader ストリームを返します。helpFile のパスは、転送 JAR 内のルートからの相対パスです。
複数の言語でヘルプを提供する場合は、TransportUIContext.getLocale() を使用して、ローカライズされたコンテンツへの適切なパスを提供します。この場合は、/help/<ロケール>/your.html のロケールの値を提供します。
コード リスト 3-5 の help/en/contexts_socketTransport.html で示されているように、getHelpPage() メソッドが起動する HTML ファイルを作成します。
ヘルプの実装を簡潔に維持する場合は、テキスト、インライン CSS 定義、およびインライン JavaScript 関数を使用する HTML ファイルを作成してください。こうすることで、グラフィックスまたはその他の外部リソースをホストする個別の Web アプリケーションを作成する必要がなくなります。
ただし、グラフィックスおよびその他のリソースを含む拡張されたヘルプを提供する場合は、img src="/help_socket/help/en/wwimages/addProject.gif" または href="http://www.yoursite.com" のように、HTML ファイルでそれらの外部リソースを参照してください。
コード リスト 3-7 で示されているように、埋め込みの JavaScript 呼び出しを使用して、拡張されたヘルプに自動的にリダイレクトするように HTML ファイルをセットアップすることもできます。このコード リストでは、サンプル ソケット転送の HTML ページから、拡張された help_socket Web アプリケーションのヘルプ コンテンツにリダイレクトしています。
<script language="JavaScript" type="text/javascript">
<!-- 開始
window.location="/help_socket/help/en/example.html";
// 終了 -->
</script>
サンプル ソケット転送の HTML ファイルが、拡張されたヘルプへのリンクを提供しています。HTML ファイル contexts_socketTransport.html は、ALSB_HOME/samples/servicebus/sample-transport/help/en/ にあります。
転送のヘルプで基本的なテキストの HTML ファイル以上のものが必要な場合は、以下のさまざまな方法を使用して、グラフィックスやその他のリソースを含めた拡張ヘルプを提供することができます。
application.xml で、Web アプリケーションのルート URL に使用されるコンテキスト ルートを Web アプリケーションに提供します。たとえば、コード リスト 3-6 は、サンプル ソケット転送の Web アプリケーションのコンテキスト ルートを示しています。
<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 ファイルは ALSB_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 アプリケーションの表示名および説明を入力します。これは、標準のデプロイメント記述子情報です。たとえば、コード リスト 3-7 は、サンプル ソケット転送の Web アプリケーションの名前および説明を示しています。
<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 ファイルは ALSB_HOME/samples/servicebus/sample-transport/webapp/WEB-INF/ にあります。
拡張されたヘルプ ファイルを作成し、Web アプリケーション ディレクトリ内にパッケージ化します。サンプル ソケット転送では、ヘルプ ファイルは ALSB_HOME/samples/servicebus/sample-transport/help/en に格納されています。
| 注意 : | ソケット転送のヘルプ ファイルが /webapp ディレクトリに格納されてないのは、help ディレクトリに Workshop for WebLogic プラグインと Oracle Service Bus Console の両方のヘルプ ファイルとリソースが格納されているためです。サンプル ソケットの ANT ビルドが、転送 JAR、転送 EAR、および WorkShop Studio プラグインを作成する場合は、ヘルプは別の方法でパッケージ化されます。転送 EAR のビルドの場合、ヘルプ ファイルは /webapp ディレクトリの下に移動します。 |
Workshop for WebLogic と Oracle Service Bus Console では、転送のコンフィグレーションにおいてユーザ インタフェースおよび機能の点で異なる可能性があるため、両方の環境で個別のヘルプ トピックを作成することを検討してください。
|