1つの汎用カスタムアダプタは複数のオペレーションを持つことができます。1つのオペレーションごとにオペレーション名，通信モデル，要求電文，および応答電文の設計が必要です。

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

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

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

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

• 英数字
• アンダーバー（_）
• ピリオド（.）
• ハイフン（-）

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

(b)　通信モデルの決定

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

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

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

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

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

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

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

「3.3.16(1)　オペレーションの設計」で設計したプロトコルコンバータが受けたい電文フォーマットと，サービスリクエスタやビジネスプロセスから要求するときの電文フォーマットが異なる場合，データ変換が必要です。電文のフォーマットは，サービスアダプタ定義画面で設定できます。

電文のデータ変換を行う場合，変換元の電文フォーマット定義ファイルおよび変換先の電文フォーマット定義ファイルを設定し，データ変換定義画面でデータ変換を定義します。

データ変換の詳細については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「6.　データ変換の定義」を参照してください。

プロトコルコンバータやカスタムアダプタ開発フレームワークが使用する定義ファイルを作成します。

• プロトコルコンバータ用独自定義ファイル
• カスタムアダプタ開発フレームワーク動作定義ファイル
• カスタムアダプタプロパティファイル
• カスタムアダプタ用アプリケーション統合属性ファイル
• カスタムアダプタ定義ファイル

作成した定義ファイルは，開発環境のサービスアダプタ定義画面で設定します。

次に作成するファイルの内容を説明します。

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

プロトコルコンバータ（プロトコル変換処理）を実装するクラスファイルを作成します。作成するクラスファイルは，カスタムアダプタ開発フレームワークが提供するCSCMsgCustomProtocolConverterインターフェースを実装します。

プロトコルコンバータは，サービスプラットフォーム上で動くStateless SessionBeanの一部として動作します。そのため，クラスファイルを作成するときは，マニュアル「アプリケーションサーバ 機能解説 基本・開発編(EJBコンテナ)」のEJBやStateless Session Beanに関する説明を参照してください。

CSCMsgCustomProtocolConverterインターフェースの詳細は，「付録B.1(1)(a)　CSCMsgCustomProtocolConverterインターフェース」を参照してください。また，実装例については，「付録B.3　カスタムアダプタ開発フレームワークのサンプルプログラム」を参照してください。

プロトコルコンバータを実装するときに考慮する内容を次に示します。

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

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

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

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

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

• 静的なリソースの取得：CSCMsgCustomProtocolConverterのstartメソッド
  サービス部品の呼び出しに必要なプロトコルのヘッダ情報やサービス部品のアドレスなど，サービス部品を呼び出すときに参照だけが行われるリソースについては，startメソッドでインスタンスフィールドに確保することを推奨しています。
  これは，汎用カスタムアダプタ開始時に一度だけ取得すれば，以後同じリソースを使い続けることができるためです。
  
• 動的なリソース（スレッドセーフでないリソース）の取得：CSCMsgCustomProtocolConverterのinvokeメソッド
  ストリームによるファイルアクセスやサービス部品に対するコネクションなど，スレッドセーフにアクセスできないリソースについては，invokeメソッドでサービス部品を呼び出すごとに取得することを推奨しています。
  スレッドセーフにアクセスできないリソースをインスタンスフィールドに確保してしまうと，スレッド間の排他制御が必要になります。
  サービス部品を呼び出すごとにリソースを取得すれば，スレッド間の排他制御による処理性能の低下を抑止できます。
  

  注意

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

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

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

• 指定するファイル名は，アーカイブ内の相対パスを含むファイル名を指定してください。
• 独自定義ファイルのファイル名と，アーカイブファイル内のリソースファイル名が重なった場合，独自定義ファイルを指定したことになります。
• 複数のアーカイブファイル内で，同一名称のリソースファイルを配置しないでください。ファイル名が重複していると，どのアーカイブ内のファイルが使用されたのか特定できなくなります。

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

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

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

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

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

●フォルト情報

• サービスリクエスタへの応答
  フォルト情報の取得については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「8.2.8　エラー情報を取得する」または「8.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ファイルを追加してコンパイルしてください。

汎用カスタムアダプタの開発で作成するJARファイルの総称を次のように分けています。

• プロトコルコンバータJARファイル
  プロトコルコンバータクラスファイルおよびカスタムアダプタ開発フレームワーク動作定義ファイルを含むJARファイル
  
• ライブラリJARファイル
  プロトコルコンバータJARファイル以外のJARファイル
  

それぞれのJARファイルの作成方法について説明します。

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

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

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

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

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

表3-112　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-113　アーカイブ内のディレクトリおよびファイル構造が重複した場合の例

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ファイルの配置

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

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

汎用カスタムアダプタの新規登録に必要なEARファイルを作成します。

EARファイルの作成は，jarコマンドを使用し，サービスプラットフォームが提供しているJARファイルをEARファイルにアーカイブします。

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

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

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

表3-114　jarコマンドによってアーカイブするときのEARファイルのディレクトリ構造

ディレクトリ名 またはファイル名	説明	指定
/	アーカイブ内のルートディレクトリです。	○
cscmsg_adpejb.jar	次に示すファイルのコピーを格納します。 <サービスプラットフォームのインストールディレクトリ>\CSC\lib\cscmsg_adpejb.jar	○
/META-INF/	管理情報を格納するディレクトリです。 jarコマンドによって自動的に作成されます。	−
MANIFEST.MF	マニフェストファイルです。 jarコマンドのmオプションを指定することで，アーカイブ内に自動的に作成されます。	−

（凡例）

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

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

注意

上記以外のファイルは格納しないでください。複数のjarファイルを格納した場合，汎用カスタムアダプタの登録ができなくなります。

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

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

• 前提
  カレントディレクトリに次に示すファイルのコピーを格納します。
  <サービスプラットフォームのインストールディレクトリ>\CSC\lib\cscmsg_adpejb.jar
  
• 指定例
  「CustomAdapter.ear」という名称のEARファイルを作成する場合のjarコマンドの指定例を次に示します。
  

  jar cf ..\CustomAdapter.ear .\

汎用カスタムアダプタの追加時にEARファイルを設定します。汎用カスタムアダプタを追加したあとにEARファイルを修正する必要がある場合，汎用カスタムアダプタのサービスアダプタ定義画面で，EARファイルを入れ替えます。

入れ替えるEARファイルに含まれるEJB-JARファイル名は，汎用カスタムアダプタの追加時に設定したEARファイルのEJB-JAR名と同じにしてください。EJB-JARファイル名が異なる場合は，EARファイルを指定したときにエラーが発生し，EARファイルを設定できません。

汎用カスタムアダプタのサービスアダプタ定義画面で，EARファイルを入れ替える手順を次に示します。

1. ツリービューのサービス定義一覧で，EARファイルを入れ替える汎用カスタムアダプタをダブルクリックします。
   サービスアダプタ定義画面が表示されます。
   
2. 画面下部の［サービスアダプタ定義（詳細）］タブをクリックします。
   サービスアダプタ定義（詳細）画面が表示されます。
   
3. サービスアダプタ定義（詳細）画面で，［参照］ボタンをクリックします。
4. 入れ替えるEARファイルを指定します。

汎用カスタムアダプタを定義する場合の手順を次に示します。

1. サービスアダプタ定義画面を表示します。
   サービスアダプタ定義画面の表示方法については，「3.3.1(4)　サービスアダプタ定義画面の表示」を参照してください。
   
2. サービス部品制御情報の［サービス名］，［サービスID］，および［最大インスタンス数］を必要に応じて編集します。
3. サービス部品制御情報の［追加］ボタンをクリックして，オペレーションを追加します。
   「3.3.16(1)　オペレーションの設計」で設計したオペレーション名を指定してください。
   
4. サービス部品制御情報の［オペレーション］のドロップダウンリストから，編集したいオペレーションを選択します。
5. サービス部品制御情報の［システム例外をフォルトに変換する］チェックボックスを必要に応じてチェックします。
6. オペレーション情報の［通信モデル］のドロップダウンリストから，「同期」または「非同期」を選択します。
   「3.3.16(1)　オペレーションの設計」で設計した通信モデルを指定してください。
   
7. 次に示す操作をします。
   

   標準電文のフォーマットを指定する場合

   手順8.〜12.を実施して，手順13.に進みます。

   標準電文のフォーマットを指定しない場合

   手順13.に進みます。

8. 要求電文の［>>］ボタンをクリックします。
   標準電文およびデータ変換定義の情報欄が表示されます。
   
9. 標準電文の［使う］チェックボックスをチェックします。
10. 標準電文の［フォーマットID］を指定します。
11. 標準電文の［参照］ボタンをクリックして，［電文フォーマット］に標準電文のフォーマットを指定します。
    ［電文フォーマット］には電文種別は，XML電文とバイナリ電文のどちらも指定できます。
    
12. 標準電文の［表示］ボタンをクリックします。
    標準電文のフォーマットが表示されます。必要に応じて指定した標準電文のフォーマットを確認してください。
    
13. サービス部品電文の［フォーマットID］を指定します。
14. サービス部品電文の［参照］ボタンをクリックして，［電文フォーマット］にサービス部品電文のフォーマットを指定します。
    「3.3.16(1)　オペレーションの設計」で設計した電文フォーマットを指定してください。
    ［電文フォーマット］には電文種別は，XML電文とバイナリ電文のどちらも指定できます。
    
15. サービス部品電文の［表示］ボタンをクリックします。
    サービス部品電文のフォーマットが表示されます。必要に応じて指定したサービス部品電文のフォーマットを確認してください。
    
16. 次に示す操作をします。
    

    標準電文の［使う］チェックボックスをチェックした場合

    手順17.〜19.を実施して，手順20.に進みます。

    標準電文の［使う］チェックボックスをチェックしない場合

    手順20.に進みます。

17. データ変換定義のファイル名を入力します。
18. ［編集］ボタンをクリックします。
    データ変換定義画面が表示されます。
    なお，初めて定義する場合は，［ルート要素選択］ダイアログが表示されます。
    また，電文フォーマットを変更した場合は，電文フォーマットの変更を反映するかを確認するダイアログが表示されます。詳細は，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「6.3.2　電文フォーマットを変更した場合の定義手順」を参照してください。
    
19. 標準電文とサービス部品電文の内容をマッピングします。
20. 手順6.で「同期」を選択した場合，応答電文についても同様に，手順7.から手順19.までを実施します。
21. サービスアダプタ定義（詳細）タブをクリックします。
22. サービスアダプタ（EJB-JARファイル）の名称を確認します。
    名称が「cscmsg_adpejb.jar」であることを確認します。
    
23. ユーティリティクラス（JARファイル）の［追加］ボタンをクリックして，JARファイルを登録します。
    追加するファイルは，「3.3.16(5)(a)　プロトコルコンバータJARファイルの作成」で作成したJARファイルです。
    必要に応じて，プロトコルコンバータで使用するJARファイル（ライブラリJARファイルなど）も追加できます。
    
24. 独自定義ファイルの［追加］ボタンをクリックして，必要に応じて次のファイルを追加します。
    
    • プロトコルコンバータ用独自定義ファイル
    • カスタムアダプタプロパティファイル
    • カスタムアダプタ用アプリケーション統合属性ファイル
25. 必要に応じて，独自定義ファイルを選択して［編集］ボタンをクリックし，ファイルの内容を編集します。
26. 定義内容を確認して，Eclipseのメニューから［ファイル］−［保管］を選択し，定義内容を保存します。