2.9.3. JCAバインディング

JCA BC は、WebOTX ESBシステムとEISとを連携する機能を提供しています。EISとの通信は、JCA(J2EE Connector Architecture)準拠のリソースアダプタを使用します。
JCA BC 動作概要


図2.9.3-1

2.9.3.1. サービスユニットのファイル構成

JCA BC のサービスユニットのフォルダ構成は下図の通りです。


図2.9.3.1-1

JCA BC のサービスユニットに含まれるファイルについて以下に説明します。
表2.9.3.1-1
項目
説明
/META-INF/jbi.xml
サービスユニットの配備記述子です。
endpoints.xml
JCA BCのエンドポイントの設定が記述されます。
*.su
サービスユニットの管理ファイルです(編集不可)。

2.9.3.2. エンドポイントの設定

SUエディタを使用してJCA BCの基本的な設定をする方法を説明します。


図2.9.3.2-1

Memo
 エンドポイントを追加する方法については、 2.7.1. エンドポイントの追加 をご覧下さい。

基本設定項目
表2.9.3.2-1
項目
説明

エンドポイント一覧
SUで定義されたエンドポイントの一覧を表示します。
 
基本設定
エンドポイントロール
リソースアダプタからリクエストを受け取る場合(Inbound)はコンシューマを設定します。
リソースアダプタを呼び出す場合(Outbound)はプロバイダを設定します。
“プロバイダ”、“コンシューマ”から選択[必須]
サービス名
エンドポイントロールがプロバイダの場合、エンドポイントが提供するサービス名を指定します。
エンドポイントロールがコンシューマの場合、呼び出し先となるエンドポイントのサービス名を指定します。
QName(名前空間、ローカル名) [必須]
インタフェース名
エンドポイントロールがプロバイダの場合、エンドポイントが提供するインタフェース名を設定します。
コンシューマの場合、呼び出し先となるエンドポイントのインタフェース名を指定します。
QName(名前空間、ローカル名)[必須]
ESBインスタンス名
分散ESB機能を使用する場合にのみESBインスタンス名を指定します。 その他の場合は空欄にします。
文字(A-Z、a-z)、数字(0-9)、ハイフン(-)、点(.)、下線(_)の組み合わせ [任意]
オペレーション一覧
オペレーションを設定します。
 
メッセージエクスチェンジハンドラ
メッセージエクスチェンジハンドラを指定します。
 
共通設定
共通項目(セキュリティ認証、トランザクション、メッセージ送信優先度、エラーリトライ)を設定します。
 
オプション一覧
オプションを設定します。
 
JCAに関する設定項目
表2.9.3.2-2
項目
説明

JCA BCの設定
リソースアダプタ名 配備した rar ファイルから拡張子を除いた文字列を設定します。
文字列[必須]
ConnectionFactoryのJNDI名 コネクタリソース登録時に設定したJNDI名を設定します。
文字列[必須]
メッセージ交換時の
   送信タイムアウト時間
コンシューマとして動作する場合、入力メッセージに対するプロバイダからの応答を待ち合わせる時間をミリ秒で設定します。0を設定した場合は無限に待ち合わせます。
数値(0以上)[任意]
デフォルト値:70000
※コンシューマの場合のみ
NMRからのレスポンス コンシューマとして動作し、かつメッセージ交換方式(MEP)が In-Only の場合に、入力メッセージに対するプロバイダからの応答を待ち合わせるかどうかを設定します。 その他のメッセージ交換方式の場合は、本指定に関わらず“待ち合わせる”で動作します。
また、メッセージ交換方式(MEP)が In-Only でエラーリトライ機能、エラー通知機能を利用する場合は、“待ち合わせる”を設定してください。
“待ち合わせる”、“待ち合わせない”から選択[任意]
デフォルトは”待ち合わせない”
※コンシューマ動作でメッセージ交換方式(MEP)が In-Onlyの場合のみ
ActivationConfig
   (活性化構成)情報
コンシューマとして動作する場合のActivationConfig(活性化構成)プロパティを設定します。

文字列[必須]
※コンシューマの場合のみ
ConnectionSpecの
   実装クラス名
ConnectionSpecの実装クラス名を設定します。
文字列[任意]
Config-property設定 ConnecitonSpecに設定するプロパティを設定します。
メッセージコンテント内に同じプロパティが設定されている場合は、メッセージコンテント内の設定値が有効になります。
文字列[任意]
InteractionSpec
   実装クラス名
InteractionSpecの実装クラス名を設定します。
文字列[任意]
Config-property設定 InteractionSpecに設定するプロパティを設定します。
メッセージコンテント内に同じプロパティが設定されている場合は、メッセージコンテント内の設定値が有効になります。
文字列[任意]
※ artifact.xml定義時、妥当性チェックにより、問題のある項目名が赤色となり、正しく修正すると、項目名が黒くなります。 詳細は、2.8. 妥当性チェック を参照してください。
※ コンシューマでエンドポイントロールを設定した場合、参照をクリックすると、SU-エンドポイント一覧ダイアログが表示されます。このダイアログを利用して、カレントサービスアセンブリプロジェクトに存在しているサービスユニットに関するサービス名やインタフェース名などの情報を利用できます。


図2.9.3.2-2

2.9.3.3. オペレーション設定

SUエディタを使用してオペレーションの設定をする方法について説明します。
 オペレーション一覧追加をクリックし、オペレーションを追加します。
 SUエディタにおける参照をクリックして、SU-エンドポイント一覧ダイアログからサービスユニットとエンドポイントを設定する場合、オペレーション一覧にそれらの設定情報が表示されます。オペレーションリストから、1つのオペレーションを選択してオペレーション設定情報を再利用できます。


図2.9.3.3-1


表2.9.3.3-1 オペレーションの設定項目
項目
説明
オペレーション名
エンドポイントロールがプロバイダの場合、JCA BCが提供するオペレーション名と名前空間を設定します。
エンドポイントロールがコンシューマの場合呼び出し先のオペレーション名と名前空間を設定します。
メッセージ交換方式
プロバイダの場合、in-only、robust-in-only、in-out、in-opt-outが設定可能です。コンシューマの場合、プロバイダのメッセージ交換方式と同じ値を設定してください。
スキーマファイル インプット/アウトプット 対象SUフォルダのMETA-INFフォルダのschemaフォルダ配下にあるスキーマファイルの相対パスを指定します。
指定したスキーマファイルは、XSLT SE による変換の定義の際のインプット/アウトプットスキーマとして利用することができます。    [メッセージ交換方式を指定した場合のみ設定可能]
参照(B)
(インプット/アウトプット)
スキーマファイルの選択ダイアログを開きます。
スキーマファイルを選択すると、その相対パスがインプットおよびアウトプット のファイルのテキストボックスに表示されます。
利用方法については、[2.7.7. スキーマファイルの設定] を参照して下さい。
オペレーション一覧で、編集をクリック、または選択したオペレーションをダブルクリックすると、オペレーション詳細設定ダイアログが表示されます。


図2.9.3.3-2


図2.9.3.3-3


表2.9.3.3-2 config-property
項目
説明
config-propertyの名前
プロパティ名を設定します
config-propertyの型
プロパティの型を設定します。
config-propertyの値
プロパティの値を設定します。
config-propertyの設定で編集をクリック、または選択したconfig-propertyをダブルクリックすると、config-property設定ダイアログが表示されます。


図2.9.3.3-4

2.9.3.4. セキュリティ認証の設定

セキュリティ認証を ON にし、設定 をクリックすると、セキュリティ認証詳細設定ダイアログが表示されます。


図2.9.3.4-1

表2.9.3.4-1
項目
説明

エンドポイント名のURL表記
エンドポイントをURL表記した値。リソース管理に用いられます。
http://webotxesb/<BC名>/エンドポイント名
省略した場合、ESB内部で自動生成されます。
エンドポイントの認証の設定
ONするとエンドポイントの認証の設定ができます。
 
エンドポイントのID
認証に利用するIDを設定します。
文字列[必須]
パスワード
認証に利用するパスワードを設定します。
文字列[任意]
ログインモジュールの設定を行う
ログインモジュールの設定を行います。
任意の文字列[任意]
SECUREMASTER と連携する場合は ESBSECUREMASTERRealm を設定してください。カスタム認証を行う場合は ESBDefaultCustomRealm を設定してください。
デフォルト値:ESBSECUREMASTERRealm
エンドポイントの認可の設定
ONにするとエンドポイントの認可の設定ができます。
 
認可に用いる認証情報
認可に利用する認証情報を設定します。
コンシューマの場合

"consumer"を設定するとエンドポイントの認証処理で認証したコンシューマ側の認証情報を利用します。


プロバイダの場合

"consumer"を設定するとエンドポイントの認証処理で認証したコンシューマ側の認証情報を利用します。
"provider"を設定するとエンドポイントの認証処理で認証したプロバイダ側の認証情報を利用します。
Principalの識別子
Principalの識別子を設定します。
任意の文字列[任意]

2.9.3.5. トランザクションの設定

[2.7.2. トランザクションの設定] を参照して下さい。

2.9.3.6. メッセージ送信優先度の設定

[2.7.3. メッセージ送信優先度の設定] を参照して下さい。

2.9.3.7. エラーリトライの設定

[2.7.4. エラーリトライの設定] を参照して下さい。

2.9.3.8. オプション一覧の設定

[2.7.5. オプション一覧の設定] を参照して下さい。

2.9.3.9. メッセージエクスチェンジハンドラの設定

[2.7.6. メッセージハンドラの設定] を参照して下さい。

2.9.3.10. 活性化構成情報の設定

ActivationConfig(活性化構成)情報追加をクリックし、活性化構成情報を設定します。


図2.9.3.10-1


表2.9.3.10-1 活性化構成情報の設定項目
項目
説明
ActivationConfigプロパティの名前
OLF/TP Adapter と連携して Inbound 通信を行う場合は RecordType を設定してください。
ActivationConfigプロパティの値
MappedRecord/IndexedRecord/CustomRecord のいずれかを設定してください。
ActivationConfigプロパティで、編集をクリック、または選択したActivationConfigプロパティをダブルクリックすると、ActivationConfig(活性化構成)プロパティダイアログが表示されます。


図2.9.3.10-2

2.9.3.11. メッセージ交換方式(MEP)

Outbound
Outboundでは、次のMEPをサポートしています。各MEPにおけるJCA BCの動作は下表のようになります。
JCA BC OutboundのMEPと動作の対応
表2.9.3.11-1
MEP
動作の説明
In-Only
NMRから渡ってきたメッセージエクスチェンジ中の送信データをRecordに変換し、Interactionのexecuteメソッドを呼び出してリソースアダプタにRecordを渡します。executeメソッドの呼び出しが終了するとNMRにDoneを通知します。 リソースアダプタと連携中にResourceExceptionがスローされた場合はNMRにErrorを返却します。
リソースアダプタとの連携時に利用するInteractionVerbはSYNC_SENDのみ設定できます。その他の値(SYNC_SEND_RECEIVE、SYNC_RECEIVE)を設定した場合は、NMRにErrorを返却します。
Robust In-Only
NMRから渡ってきたメッセージエクスチェンジ中の送信データをRecordに変換し、Interactionのexecuteメソッドを呼び出してリソースアダプタにRecordを渡します。executeメソッドの呼び出しが終了するとNMRにDoneを通知します。 リソースアダプタと連携中にResourceExceptionがスローされた場合はNMRにError/Faultを返却します。
リソースアダプタとの連携時に利用するInteractionVerbはSYNC_SENDのみ設定できます。その他の値(SYNC_SEND_RECEIVE、SYNC_RECEIVE)を設定した場合は、NMRにErrorを返却します。
In-Out
NMRから渡ってきたメッセージエクスチェンジ中の送信データをRecordに変換し、Interactionのexecuteメソッドを呼び出してリソースアダプタにRecordを渡します。executeメソッドの呼び出しが終了するとリソースアダプタから返却されたRecord中の受信データをメッセージエクスチェンジに変換しNMRに渡します。 リソースアダプタと連携中にResourceExceptionがスローされた場合はNMRにError/Faultを返却します
リソースアダプタとの連携時に利用するInteractionVerbはSYNC_SEND、SYNC_SEND_RECEIVEを設定できます。SYNC_RECEIVEを設定した場合は、NMRにErrorを返却します。
In Optional-Out
NMRから渡ってきたメッセージエクスチェンジ中の送信データをRecordに変換し、Interactionのexecuteメソッドを呼び出してリソースアダプタにRecordを渡します。executeメソッドの呼び出しが終了するとリソースアダプタから返却されたRecord中の受信データをメッセージエクスチェンジに変換しNMRに渡します。返却Recordがなければ、NMRにDoneを通知します。 リソースアダプタと連携中にResourceExceptionがスローされた場合はNMRにError/Faultを返却します。
リソースアダプタとの連携時に利用するInteractionVerbはSYNC_SEND、SYNC_SEND_RECEIVE、SYNC_RECEIVEを設定できます。
Inbound
Inboundでは、次のMEPをサポートしています。各MEPにおけるJCA BCの動作は下表のようになります。
JCA BC InboundのMEPと動作の対応
表2.9.3.11-2
MEP
動作の説明
In-Only
リソースアダプタからのRecordを受信するとメッセージエクスチェンジに受信データを変換しNMRに渡します。 「NMRからのレスポンス」で"待ち合わせない"が選択されている場合は、即座にリソースアダプタにnullを返却します。「NMRからのレスポンス」で"待ち合わせる"が選択されている場合、NMRからのレスポンスを待ち合わせた後、リソースアダプタにnullを返却します。
Robust In-Only
リソースアダプタからのRecordを受信するとメッセージエクスチェンジに受信データを変換しNMRに渡します。 NMRからFaultが返却された場合にはリソースアダプタにResourceExceptionをスローします。 本 MEP では、「NMRからのレスポンス」で選択されている値に関わらず "待ち合わせる" で動作します。この場合、NMRからのレスポンスを待ち合わせた後、リソースアダプタにnullを返却します。
In-Out
リソースアダプタからのRecordを受信するとメッセージエクスチェンジに受信データを変換しNMRに渡します。NMRからの返却データはRecordに変換してリソースアダプタに渡します。 本 MEP では、「NMRからのレスポンス」で選択されている値に関わらず "待ち合わせる" で動作します。この場合、NMRからのレスポンスを待ち合わせた後、リソースアダプタにRecordを返却します。
In Optional-Out
リソースアダプタからのRecordを受信するとメッセージエクスチェンジに受信データを変換しNMRに渡します。NMRからの返却データがあればRecordに変換しリソースアダプタに返却します。返却データがなければリソースアダプタにnullを返却します。 NMRからFaultが返却された場合にはリソースアダプタにResourceExceptionをスローします。 本 MEP では、「NMRからのレスポンス」で選択されている値に関わらず "待ち合わせる" で動作します。この場合、NMRからのレスポンスを待ち合わせた後、リソースアダプタにRecordを返却します。

2.9.3.12. ノーマライズ規則

JCA BCがNMRから受け取ったメッセージエクスチェンジをリソースアダプタに渡す電文に変換することをデノーマライズといいます。また、リソースアダプタから渡された電文をNMRに送信するメッセージエクスチェンジに変換することをノーマライズといいます。


図2.9.3.12-1 デノーマライズ規則

JCA BCはメッセージコンテントをリソースアダプタが解析する電文に変換しリソースアダプタ呼び出し時の引数に設定します。


図2.9.3.12-2 ノーマライズ規則

JCA BCはリソースアダプタから渡された電文をメッセージコンテントに変換しメッセージエクスチェンジに設定します。

2.9.3.13. ノーマライズメッセージ

ここでは、JCA BC がリソースアダプタと送受信したメッセージを NMR とやりとりするためのノーマライズメッセージ形式へ変換する方法について説明します。
JCA BC ではリソースアダプタから受信したメッセージをノーマライズメッセージに変換して NMR に渡す操作が「ノーマライズ」、 NMR からノーマライズメッセージを受け取りリソースアダプタに渡すメッセージに変換する操作が「デノーマライズ」です。


図2.9.3.13-1

(1) ノーマライズ(正常系メッセージ)

ノーマライズでは、リソースアダプタから受信したメッセージをノーマライズメッセージへ格納します。
リソースアダプタからの受信データは、JCA BC がコンシューマ動作の場合、<record-definition>の<record pattern="in">の中に設定されます。
JCA BC がプロバイダ動作の場合、<record-definition>の<record pattern="out">の中に設定されます。
以下に、JCA BC がコンシューマ動作時に NMR に渡すノーマライズメッセージの例を示します。

<jca-bc>
  <record-definition>
    <record pattern="in">
      <mappedrecord name="TX01">
        <mappedrecord-property>
          <key-type>java.lang.String</key-type>
          <key>NAME</key>
          <type>java.lang.String</type>
          <value>CustomerName</value>
        </mappedrecord-property>
      </mappedrecord>
    </record>
    <record pattern="out"/>
  </record-definition>
</jca-bc>

(2) デノーマライズ(正常系メッセージ)

デノーマライズでは、ノーマライズメッセージから取り出した値を元にリソースアダプタに渡すメッセージを構築します。
JCA BC がコンシューマ動作の場合、<record-definition>の<record pattern="out">の中に設定されているデータが、 リソースアダプタに渡されます。
JCA BC がプロバイダ動作の場合、<record-definition>の<record pattern="in">の中に設定されているデータが、 リソースアダプタに渡されます。
以下に、JCA BC がプロバイダ動作時のノーマライズメッセージの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<jca-bc>
  <connectionspec-definition>
    <connectionspec-impl-class>
      jp.co.nec.WebOTX.connector.olftp.cci.ConnectionSpecImpl
    </connectionspec-impl-class>
  </connectionspec-definition>
  <interactionspec-definition>
    <interactionspec-impl-class>
      jp.co.nec.WebOTX.connector.olftp.cci.InteractionSpecImpl
    </interactionspec-impl-class>
    <config-property>
      <config-property-name>TXID</config-property-name>
      <config-property-type>java.lang.String</config-property-type>
      <config-property-value>TX01</config-property-value>
    </config-property>
  </interactionspec-definition>
  <record-definition>
    <record pattern="in">
      <mappedrecord name="TX01">
      <mappedrecord-property>
      <key-typegt;java.lang.String</key-type>
      <key>NAME</key>
      <type>java.lang.String</type>
      <value>CustomerName</value>
      </mappedrecord-property>
      </mappedrecord>
    </record>
    <record pattern="out">
      <mappedrecord name="">
      </mappedrecord>
    </record>
  </record-definition>
</jca-bc>

(3) ノーマライズ(異常系メッセージ)

JCA BC がプロバイダ動作時に、JCA BC 内部で異常が発生した場合や JCA BC が連携しているリソースアダプタから異常が返却された場合、 異常を表すメッセージを元に Fault/Error を作成し、作成した Fault/Error を NMR に返却します。

以下に、NMR に返却する Fault の例を示します。

<esb-fault xmlns="http://www.nec.com/WebOTX/jbi/fault/">
    <exchangeid>1339467478562-00000002</exchangeid>
    <date>2012-06-12T11:18:01.234+09:00</date>
    <component>JCABinding</component>
    <service-assembly>SA_JCAProvider</service-assembly>
    <service-unit>JCASU_SA_JCAProvider_002</service-unit>
    <service-name xmlns:ns2="http://nec.com/testengine.wsdl">ns2:ep_SA_JCAProvider_002</service-name>
    <endpoint>ep_SA_JCAProvider_002</endpoint>
    <role>PROVIDER</role>
    <string>OTX21344610: In-out メッセージの処理中にExceptionが発生しました。理由 : ResourceException :OTX12008021 transaction was refused.(retid=0x90,detail=0x000002c1), error code: 0x8021</string>
    <detail/>
</esb-fault>
(4) デノーマライズ(異常系メッセージ)

JCA BC がコンシューマ動作時に JCA BC や JCA BC と連携している BC/SE 内で Fault/Error が発生した場合、Fault/Error 内のメッセージを元に javax.resource.ResourceException を作成し、作成した ResourceException を連携しているリソースアダプタに返却します。
以下に、リソースアダプタに返却する ResourceException の例を示します。

javax.resource.ResourceException: com.nec.webotx.jbi.exception.WebOTXESBExceptionImpl: ファイル書き込み時にエラーが発生しました。

2.9.3.14. 異常系メッセージ

WebOTX ESB において「JCA BC に誤ったメッセージが入力された」、「サービス呼び出しに失敗した」等の異常が発生した場合、JCA BC の Inbound から 連携しているリソースアダプタに対して javax.resource.cci.MessageListener クラスの onMessage メソッドの戻り値として javax.resource.ResourceException が返却されます。
javax.resource.ResourceException には、Fault/Error 内のメッセージが含まれるため、リソースアダプタでは javax.resource.ResourceException から 異常の内容を知ることができます。

異常の種類により Fault または Error の分類があります。 JCA BC において異常が発生するパターンは [ リファレンス集 開発編(Enterprise Service Bus) > 2. 異常系メッセージ(Fault/Error) > 2.1. バインディングコンポーネント > 2.1.3. JCA BC ] を参照してください。