3.3.17　汎用カスタムアダプタを定義する

(a)　オペレーション名の決定

オペレーション名は，サービスリクエスタからのサービス部品呼び出しや，ビジネスプロセスのサービス呼出アクティビティからのサービス部品呼び出しで，オペレーションを区別するための識別名です。

255バイト以内で，汎用カスタムアダプタ内で一意な名称を付け，同じ汎用カスタムアダプタ内のほかのオペレーション名と重複しないように指定してください。

指定できる文字列および記号は次のとおりです。

• 英数字

• アンダーバー（_）

• ピリオド（.）

• ハイフン（-）

汎用カスタムアダプタ内のプロトコルコンバータでは，汎用カスタムアダプタが呼び出されたときに，どのオペレーションが呼ばれたのかを識別するために使います。

(b)　通信モデルの決定

汎用カスタムアダプタではオペレーションごとに通信モデルを選択できます。呼び出すサービス部品に合わせて，同期または非同期のどちらかを選択してください。

(c)　要求電文・応答電文の設計

プロトコルコンバータが受け取る要求電文とプロトコルコンバータが応答する応答電文について，電文形式と電文フォーマットを設計します。ただし，通信モデルが非同期の場合，応答電文を返さないので，応答電文を定義する必要はありません。

電文形式は，XML形式とバイナリ形式が選べます。

電文フォーマットは，サービス部品の実行に利用する電文でXML形式のデータを扱うか，バイナリ形式（XML形式以外）のデータを扱うかによって形式が異なります。呼び出すサービス部品に合わせてXML形式とバイナリ形式のどちらかを選択し，呼び出すサービス部品の形式に合わせて，電文フォーマットを作成してください。

XML形式とバイナリ形式の違いについては，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「4.2　電文フォーマットの種類」を参照してください。

XML形式のデータを扱う場合の電文フォーマットの作成については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「4.3　電文フォーマット（XMLフォーマット定義ファイル）の作成方法」を，バイナリ形式（XML形式以外）のデータを扱う場合の電文フォーマットの作成については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「4.4　電文フォーマット（バイナリフォーマット定義ファイル）の作成方法」を参照してください。

(a)　プロトコルコンバータ用独自定義ファイル

プロトコルコンバータは，アダプタコンテキストを通して，汎用カスタムアダプタに設定されたリソース内容を読み込めます。

プロトコルコンバータの動作に必要なファイルがあれば作成してください。

(b)　カスタムアダプタ開発フレームワーク動作定義ファイル

カスタムアダプタ開発フレームワークが使用するプロトコルコンバータのクラス名（パッケージ名を含む）を指定します。ファイル名は必ず「framework_properties.xml」にしてください。

カスタムアダプタ開発フレームワーク動作定義ファイルの設定内容については，「付録B.2(1)　カスタムアダプタ開発フレームワーク動作定義ファイル」を参照してください。

(c)　カスタムアダプタプロパティファイル

プロトコルコンバータに関する設定を外部ファイル化したい場合など，必要に応じて作成するファイルです。このファイルは独自定義ファイルの一種で，汎用カスタムアダプタの定義時に使用します。ファイル名は必ず「customadapter_properties.xml」にしてください。

カスタムアダプタプロパティファイルの設定内容については，「付録B.2(2)　カスタムアダプタプロパティファイル」を参照してください。

(d)　カスタムアダプタ用アプリケーション統合属性ファイル

カスタムアダプタ用アプリケーション統合属性ファイルを用いることで，運用する環境に合わせて，汎用カスタムアダプタのパラメタを設定できます。カスタムアダプタ用アプリケーション統合属性ファイルを指定する場合，ファイル名は必ず「cscadapter_property.xml」にしてください。

アプリケーション統合属性ファイルの設定内容については，「付録B.2(3)　カスタムアダプタ用アプリケーション統合属性ファイル」を参照してください。

アプリケーション統合属性ファイルを指定した場合，Session Bean属性の<pooled-instance>はアプリケーション統合属性ファイルで記載した値となります。

(e)　カスタムアダプタ定義ファイル

カスタムアダプタ定義ファイルを用いることで，データ変換時に電文の構造変換をスキップする機能（構造変換スキップ機能）を利用できます。カスタムアダプタ定義ファイルを指定する場合，ファイル名は必ず「csccustomadapter.properties」にしてください。

カスタムアダプタ定義ファイルの設定内容については，「付録B.2(4)　カスタムアダプタ定義ファイル」を参照してください。

構造変換スキップ機能の設定方法について説明します。

要求電文のデータ変換では，ビジネスプロセスから受け取ったDOMツリーから，直接，バイナリ形式の要求電文を生成し，汎用カスタムアダプタに渡したいときに，構造変換スキップ機能を有効にできます。

応答電文のデータ変換では，汎用カスタムアダプタから返ってきたバイナリ形式の応答電文から生成したDOMツリーを，そのままビジネスプロセスに返したいときに，構造変換スキップ機能を有効にできます。

構造変換スキップ機能を設定するには，開発環境のサービスアダプタ定義（詳細）画面で，［独自定義ファイル］にカスタムアダプタ定義ファイルを設定する必要があります。

サービスアダプタ定義画面については，マニュアル「サービスプラットフォーム リファレンス」の「1.2.2　サービスアダプタ定義画面」を参照してください。

構造変換スキップ機能を使用するときの注意事項を次に示します。

• 開発環境のサービスアダプタ定義画面で，要求電文および応答電文の標準電文フォーマットにXMLフォーマット定義ファイルを，要求電文および応答電文のサービス電文フォーマットにバイナリフォーマット定義ファイルを指定してください。

• 開発環境のサービスアダプタ定義画面で，要求電文および応答電文の標準電文フォーマットには，受付電文フォーマット（バイナリフォーマット定義ファイル）からcscfdx2xsdコマンドを使用して生成したXMLフォーマット定義ファイルを指定してください。

(a)　汎用カスタムアダプタのインスタンスとプロトコルコンバータのインスタンスの関係

1つの汎用カスタムアダプタは複数のインスタンスを持つことがありますが，その場合でもプロトコルコンバータのインスタンスは常に1つです。そのため，プロトコルコンバータはマルチスレッドでアクセスされることに注意して実装してください。

図3‒31　汎用カスタムアダプタのインスタンスとプロトコルコンバータのインスタンスの関係

(b)　リソースの確保方法

カスタムアダプタ開発フレームワークでは，プロトコルコンバータでのリソースの確保について，次の方法を推奨しています。

• 静的なリソースの取得：CSCMsgCustomProtocolConverterのstartメソッド

  サービス部品の呼び出しに必要なプロトコルのヘッダ情報やサービス部品のアドレスなど，サービス部品を呼び出すときに参照だけが行われるリソースについては，startメソッドでインスタンスフィールドに確保することを推奨しています。

  これは，汎用カスタムアダプタ開始時に一度だけ取得すれば，以後同じリソースを使い続けることができるためです。

• 動的なリソース（スレッドセーフでないリソース）の取得：CSCMsgCustomProtocolConverterのinvokeメソッド

  ストリームによるファイルアクセスやサービス部品に対するコネクションなど，スレッドセーフにアクセスできないリソースについては，invokeメソッドでサービス部品を呼び出すごとに取得することを推奨しています。

  スレッドセーフにアクセスできないリソースをインスタンスフィールドに確保してしまうと，スレッド間の排他制御が必要になります。

  サービス部品を呼び出すごとにリソースを取得すれば，スレッド間の排他制御による処理性能の低下を抑止できます。

  注意事項

  一度確保したリソースは，処理が終了しても保持し続けるため，システム全体に高い負荷がかかった場合に，Javaヒープ不足やMetaspace領域不足などが原因でOutOfMemoryErrorが発生することがあります。そのため，OutOfMemoryErrorが発生したときに適切にリソースを解放する処理や，ロールバックなどのエラー処理を実装しておく必要があります。

(c)　リソースファイルのファイル名指定方法

プロトコルコンバータでは，アダプタコンテキストを用いてアーカイブファイル内のリソースファイルにアクセスできます。アーカイブファイル内のリソースファイルにアクセスする場合，次の点に注意してください。

• 指定するファイル名は，アーカイブ内の相対パスを含むファイル名を指定してください。

• 独自定義ファイルのファイル名と，アーカイブファイル内のリソースファイル名が重なった場合，独自定義ファイルを指定したことになります。

• 複数のアーカイブファイル内で，同一名称のリソースファイルを配置しないでください。ファイル名が重複していると，どのアーカイブ内のファイルが使用されたのか特定できなくなります。

(d)　フォルト情報と例外の違い

CSCMsgCustomProtocolConverterのinvokeメソッドの実行中にエラーが起きた場合，プロトコルコンバータは例外を生成して送出，またはフォルト情報を応答電文メッセージに格納します。

フォルト情報は，サービス部品呼び出し処理（CSCMsgCustomProtocolConverterのinvokeメソッド）の実行中に発生した業務上の障害を，カスタムアダプタ開発フレームワークに伝達するために使用します。

例外は，サービス部品呼び出し処理中に発生した通信エラーなどのシステム障害を，カスタムアダプタ開発フレームワークに伝達するために使用します。

フォルトを使用した場合と例外を使用した場合とでは，障害情報を受け取るサービスアダプタやビジネスプロセスでは次のような違いがあります。

●フォルト情報

• サービスリクエスタへの応答

  フォルト情報の取得については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「9.2.8　エラー情報を取得する」または「9.4.7　エラー情報を取得する」を参照してください。

• ビジネスプロセスへの応答

  ビジネスプロセスでは，サービスプラットフォームが提供するほかのサービスアダプタのフォルトと同様に処理できます。ビジネスプロセスでのフォルト処理については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「5.4.4　フォルト処理を定義する」を参照してください。

参考

カスタムアダプタ開発フレームワークに伝達するフォルト情報は，SOAPのSOAP Fault情報に対応する要素を持ちます。各要素の使用方法もSOAPの仕様に準拠しています。SOAP通信基盤がサポートするSOAPおよびSAAJの仕様に従って記述してください。SOAP通信基盤のサポートするSOAPおよびSAAJの仕様については，マニュアル「アプリケーションサーバ SOAPアプリケーション開発の手引」の「12.　標準仕様との対応」を参照してください。

●例外

• サービスリクエスタへの応答

  例外情報の取得については，サービスリクエスタ作成でのエラー情報の取得に関する内容を参照してください。

• ビジネスプロセスへの応答

  ビジネスプロセスでは，フォルト処理はできないため，エラー（例外）として扱われます。

(e)　コンパイル

カスタムアダプタ開発フレームワークで使用する次のJARファイルをクラスパスに指定してコンパイルする必要があります。

<サービスプラットフォームのインストールディレクトリ>\CSC\lib\csc_adapter.jar

また，サービスプラットフォームのAPIなどを使う場合は，別途必要なJARファイルを追加してコンパイルしてください。

(a)　プロトコルコンバータJARファイルの作成

jarコマンドを使用して，プロトコルコンバータクラスファイルとそれが使用するクラスファイルおよび，カスタムアダプタ開発フレームワーク動作定義ファイルをJARファイルにアーカイブします。

JARファイルにアーカイブする場合のディレクトリ構成，およびjarコマンドの指定例を次に示します。

●JARファイルのディレクトリ構造

jarコマンドによってアーカイブするときのJARファイルのディレクトリ構成を次の表に示します。

表3‒119　jarコマンドによってアーカイブするときのJARファイルのディレクトリ構成

ディレクトリ名 またはファイル名	説明	指定
/	アーカイブ内のルートディレクトリです。	○
*.class	プロトコルコンバータおよびそれらが依存するクラス（インターフェース）のクラスファイル（*.class）をパッケージ名に従ったディレクトリ階層で格納します。	○
framework_properties.xml	カスタムアダプタ開発フレームワークが使用するプロトコルコンバータのクラス名（パッケージ名を含む）を指定します。	○※
*	プロトコルコンバータが使用する任意のリソースファイルです。 ディレクトリを作成して，その中にファイルを格納できます。	−
/META-INF/	管理情報を格納するディレクトリです。 jarコマンドによって自動的に作成されます。	−
MANIFEST.MF	マニフェストファイルです。 jarコマンドのmオプションを指定することで，アーカイブ内に自動的に作成されます。	−

（凡例）

○：アーカイブするときに指定が必須であることを示します。

−：アーカイブするときに指定が不要，または任意であることを示します。

注※

JARファイルが複数の場合は，プロトコルコンバータを格納したJARファイルにだけ格納してください。

●JARファイル作成時のjarコマンド指定例

JARファイルにアーカイブする場合のjarコマンドの指定例を次に示します。

• 前提

  カレントディレクトリおよびサブディレクトリに次のようにファイルが用意されているとします。

  framework_properties.xml
  protocolconverter/CustomProtocolConverter.class
  lib/MyLib.class
  data/table.dat

• 指定例

  「MyProtocolConverter.jar」という名称のJARファイルを作成する場合のjarコマンドの指定例を次に示します。

  jar cf ..\MyProtocolConverter.jar .\

(b)　ライブラリJARファイルの作成

ライブラリJARファイルは一般のJARファイルと同じように作成してください。

ライブラリJARファイルの作成時の注意事項を次に示します。

●JARファイルのファイル構造

複数のJARファイル間でファイル名は重複しないようにしてください。

ファイル名が重複していると，どのJARファイルのファイルが使用されたのか特定できなくなります。なお，ディレクトリだけが重複している場合は，問題ありません。

A.jarとB.jarという2つのJARファイルを使用し，アーカイブ内のディレクトリおよびファイル構造が重複した場合の例を次の表に示します。

表3‒120　アーカイブ内のディレクトリおよびファイル構造が重複した場合の例

A.jarの構造	B.jarの構造	説明
myfile.txt	−	A.jarのファイル「myfile.txt」が使用されます。
samedata.dat	samedata.dat	A.jarとB.jarのどちらのファイル「samedata.dat」が使用されたのか特定できません。ファイル名は重複させないでください。
dir/	dir/	ディレクトリの重複はかまいません。
−	dir/b.class	B.jarのファイル「dir/b.class」が使用されます。
dir/same.class	dir/same.class	A.jarとB.jarのどちらのファイル「def/same.class」が使用されたのか特定できません。ファイル名は重複させないでください。

（凡例）

−：存在しないことを示します。

●JARファイルの配置

ファイル名が「framework_properties.xml」であるファイルをJARファイルのルートディレクトリに配置しないでください。

「framework_properties.xml」と同じファイル名のJARファイルがルートディレクトリに存在すると，プロトコルコンバータJARファイル内のファイル「framework_properties.xml」が使用されなくなるおそれがあります。