Hitachi

Cosminexus V11 BPM/ESB基盤 サービスプラットフォーム 開発ガイド 受付・アダプタ定義編


3.3.14 コマンドアダプタを定義する

コマンドアダプタの定義方法について説明します。

〈この項の構成〉

(1) 電文フォーマットの作成

コマンドアダプタでは,要求電文と応答電文の2種類の電文があります。それぞれの内容について説明します。

電文フォーマット作成手順の詳細は,マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「4. 電文フォーマットの作成」を参照してください。

(a) コマンドアダプタの要求電文フォーマット

サービス呼出アクティビティを使用して,コマンドアダプタに渡す要求電文のXMLデータフォーマットと指定値について説明します。

名前空間名は「http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/cmd/request」です。

表3‒107 要求電文フォーマット

タグ名

種別

出現回数

説明

<request>

1

<command-line>

1

<command>

string

1

外部コマンドのファイルパスを指定するタグです。

<argument<N>>

string

0または1

外部コマンドのコマンドライン引数を指定するタグです。

argument<N>にそれぞれ1つずつ指定します。

<N>の部分は,1,2,…,100のどれかを指定します。

<N> の部分は昇順に出現する必要があります。

出現する<N>が連続値である必要はありません。

要素値が空文字列の要素は,引数として採用しません。

<config>

0または1

外部コマンドプロセスに関する動作オプションを設定するタグです。

各子要素で値を指定した場合,コマンドアダプタ実行環境プロパティファイルの対応するプロパティ値は無効になります。

各子要素がない場合,コマンドアダプタ実行環境プロパティファイルの対応するプロパティ値が有効になります。

コマンドアダプタ実行環境プロパティファイルの詳細は,マニュアル「サービスプラットフォーム リファレンス」の「6.15.3 コマンドアダプタ実行環境プロパティファイル」を参照してください。

<timeout>

0または1

外部コマンドプロセスのタイムアウトに関する情報を指定するタグです。

<value>

int

0または1

タイムアウト時間(秒)を指定するタグです。

指定可能値は,0〜86400です。

0を指定した場合,外部コマンドプロセスのタイムアウトを使用しません。

要素値が空要素の場合はエラーになります。

対応するコマンドアダプタ実行環境プロパティファイルのプロパティはadpcmd.config.timeout.valueです。詳細は,マニュアル「サービスプラットフォーム リファレンス」の「6.15.3 コマンドアダプタ実行環境プロパティファイル」を参照してください。

<enable-kill-process>

boolean

0または1

タイムアウト発生時の外部コマンドプロセス強制終了の実施可否を指定するタグです。

指定可能値は,trueまたはfalseです(大文字可)。

trueを指定した場合,タイムアウト発生時にプロセスの強制終了を試みます。

要素値が空要素の場合はエラーになります。

対応するコマンドアダプタ実行環境プロパティファイルのプロパティはadpcmd.config.timeout.enable-kill-processです。詳細は,マニュアル「サービスプラットフォーム リファレンス」の「6.15.3 コマンドアダプタ実行環境プロパティファイル」を参照してください。

<process-environment>

0または1

外部コマンドプロセスの環境に関する情報を設定するタグです。

<variable-file-path>

string

0または1

プロセス環境変数定義ファイルのファイルパスを指定するタグです。

絶対パスで指定してください。

HCSCサーバマシンのファイルを指定してください。

ファイルパスを指定した場合,コマンドアダプタ実行環境プロパティファイルで指定したプロセス環境変数定義ファイルの内容はすべて無視されます。

要素値が空要素の場合はエラーになります。

対応するコマンドアダプタ実行環境プロパティファイルのプロパティはadpcmd.config.process-environment.variable-file-pathです。詳細は,マニュアル「サービスプラットフォーム リファレンス」の「6.15.3 コマンドアダプタ実行環境プロパティファイル」を参照してください。

<working-dir-path>

string

0または1

外部コマンドプロセスの作業ディレクトリを指定するタグです。

絶対パスで指定してください。

HCSCサーバマシンに存在するディレクトリを指定してください。

要素値が空要素の場合はエラーになります。

対応するコマンドアダプタ実行環境プロパティファイルのプロパティはadpcmd.config.process-environment.working-dir-pathです。詳細は,マニュアル「サービスプラットフォーム リファレンス」の「6.15.3 コマンドアダプタ実行環境プロパティファイル」を参照してください。

(凡例)

−:該当する項目はありません。

注※

規定の出現回数を超える場合の動作は保証されません。

参考

サービスプラットフォームが提供している要求電文のXMLスキーマファイルは,「<サービスプラットフォームのインストールディレクトリ>/CSC/custom-adapter/Command/schema/adpcmd_request.xsd」に格納されています。

コマンドライン引数を10個以上使用したい場合は,フォルダごと任意の場所にコピーしてから,コマンドライン引数要素(argument<N>)を追加してください。

(b) コマンドアダプタの応答電文フォーマット

サービス呼出アクティビティを使用して,コマンドアダプタから受け取る応答電文のバイナリデータフォーマットについて説明します。

●応答電文の内容

全体の構造を次の図で示します。

図3‒30 応答電文のバイナリフォーマットの構造

[図データ]

応答電文のバイナリデータフォーマットの詳細を次の表に示します。

表3‒108 応答電文のバイナリデータフォーマットの詳細

情報

サイズ

(バイト)

説明

終了コード

4

外部コマンドプロセスの終了コードです。

符号付2進整数(リトルエンディアン)で表現した値が格納されています。

[標準出力への出力結果]領域のサイズ

4

標準出力への出力結果として応答電文に格納されているサイズ(バイト)です。

符号付2進整数(リトルエンディアン)で表現した値が格納されています。

サイズの最小値は0,サイズの最大値はコマンドアダプタ実行環境プロパティファイルのadpcmd.config.stdout.sizeキーで指定した値です。

標準出力への出力結果

可変

外部コマンドプロセスが標準出力に出力した内容です。

サービスプラットフォームでは,標準出力への出力結果を1つの文字列として扱うバイナリフォーマットファイルを提供します。エンコード形式の設定が異なる2つのファイルを次の場所に提供します。

<サービスプラットフォームのインストールディレクトリ>/CSC/custom-adapter/Command/schema/adpcmd_response_ms932.fdx
<サービスプラットフォームのインストールディレクトリ>/CSC/custom-adapter/Command/schema/adpcmd_response_utf8.fdx
●応答電文フォーマットの作成

サービスプラットフォームが提供する応答電文のフォーマットファイルは,標準出力への出力結果を1つの文字列として扱う定義となっています。このファイルを利用する場合は,応答電文フォーマットを作成する必要はありません。

応答電文で標準出力への出力結果を構造データとして扱う場合は,バイナリフォーマットファイルを作成する必要があります。

バイナリフォーマットファイルの作成手順を次に示します。

  1. サービスプラットフォームが提供する応答電文バイナリフォーマットファイルを,Eclipseのパッケージエクスプローラからアクセスできる場所にコピーします。

  2. コピーしたファイルをバイナリフォーマットエディタで開きます。

  3. 複合内容要素[standard-output]を削除します。

    削除する順序を次の図に示します。

    [図データ]

  4. 応答電文バイナリフォーマットの「標準出力への出力結果」領域に対応する定義を,外部コマンドの仕様に合わせて作成します。

    応答電文のバイナリデータフォーマットの詳細については,表3-108を参照してください。

作成したバイナリフォーマットファイルは,コマンドアダプタのサービスアダプタ定義画面でEXECオペレーションの応答電文フォーマットに設定します。また,作成したバイナリフォーマットファイルでビジネスプロセスの変数を作成して,サービス呼出アクティビティの応答電文に指定します。

ポイント

コマンドアダプタは,要求電文で外部コマンドを指定できるため,リクエストごとに外部コマンドを変更できます。そのため,複数のビジネスプロセスでコマンドアダプタを共有しやすく,定義コンポーネント数を削減することができます。

定義コンポーネント数を削減するため,複数の外部コマンドに対して,外部コマンドの標準出力形式に合わせて作成した応答電文フォーマットを使用したい場合は,次のとおりビジネスプロセスとコマンドアダプタを設定してください。

  • 外部コマンドに合わせて作成したバイナリフォーマット定義ファイルは,ビジネスプロセスでだけ使用してください。

    その際,サービス呼出アクティビティの応答電文変数は,コマンドアダプタが提供するバイナリフォーマット定義ファイルの変数とします。また,作成したバイナリフォーマット定義ファイルを基にした変数は,コマンドアダプタを呼び出した後に,Java呼出アクティビティや代入アクティビティで使用してください。

  • コマンドアダプタのEXECオペレーションの応答電文フォーマットは,コマンドアダプタが提供するバイナリフォーマット定義ファイルを使用してください。

(2) サービスアダプタ定義画面での操作

コマンドアダプタを定義する場合の手順を次に示します。

  1. サービスアダプタ定義画面を表示します。

    サービスアダプタ定義画面の表示方法については,「3.3.1(4) サービスアダプタ定義画面の表示」を参照してください。

  2. サービスアダプタ定義画面(基本)で定義情報を設定します。

    サービスアダプタ定義画面(基本)で設定が必要な項目については,「3.3.18(14) コマンドアダプタの場合」およびマニュアル「サービスプラットフォーム リファレンス」の「1.2.2 サービスアダプタ定義画面」を参照してください。

  3. [サービスアダプタ定義(詳細)]タブをクリックします。

    サービスアダプタ定義画面(詳細)が表示されます。

  4. サービスアダプタ定義画面(詳細)で定義情報を設定します。

    サービスアダプタ定義画面(詳細)で設定が必要な項目については,「3.3.18(14) コマンドアダプタの場合」を参照してください。

(3) コマンドアダプタの定義ファイルの作成および編集

作成および編集する定義ファイルの種類を次に示します。

各定義ファイルの作成手順および編集手順を次に示します。

(a) 実行許可コマンド定義ファイルの作成

  1. コマンドアダプタで実行を許可するファイルパス,および指定を可能にするコマンドライン引数の仕様をまとめます。

  2. チェック対象文字列を受理する正規表現を作成して,ファイルに定義します。

  3. 作成したファイルを任意のパスに保存します。

    注意事項

    実行許可コマンド定義ファイルを有効にするには,コマンドアダプタ実行環境プロパティファイルのadpcmd.config.command.allow-file-pathプロパティに保存先のファイルパスを指定してください。

(b) プロセス環境変数定義ファイル

  1. プロセス環境変数定義ファイルは,Javaのプロパティファイル形式で作成します。

    環境変数名をキーとして,変数値を要素とします。

  2. 作成したプロセス環境変数定義ファイルは,任意の場所に任意のファイル名で保存します。

    注意事項

    プロセス環境変数定義ファイルを有効にするには,コマンドアダプタ実行環境プロパティファイルのadpcmd.config.process-environment.variable-file-pathプロパティに保存先のファイルパスを指定してください。

(c) コマンドアダプタ実行環境プロパティファイル

  1. テンプレートファイル(<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Command\config\templates\serviceid.properties)をコピーして,次のディレクトリに格納します。

    全HCSCサーバ共通の定義の場合

    <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Command\config

    特定のHCSCサーバ用の定義の場合

    サブディレクトリ<HCSCサーバ名>を作成して格納してください。Windowsの場合,HCSCサーバ名の大文字・小文字は区別されます。

    <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Command\config\<HCSCサーバ名>

  2. コピーしたテンプレートファイルのファイル名を「<サービスID>.properties」に変更します。

  3. 定義内容を編集して保存します。

    コマンドアダプタ実行環境プロパティファイルで編集できる定義内容については,マニュアル「サービスプラットフォーム リファレンス」の「6.15.3 コマンドアダプタ実行環境プロパティファイル」を参照してください。

注※

サービスIDは,開発環境のコマンドアダプタエディタで設定した値です。

コマンドアダプタ実行環境プロパティファイルは,コマンドアダプタを開始する際に実行環境に反映されます。このため,コマンドアダプタ実行環境プロパティファイルの内容を変更する場合は,いったんコマンドアダプタを停止する必要があります。

(d) コマンドアダプタ実行環境共通プロパティファイル

  1. テンプレートファイル(<サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Command\config\templates\adpcmdcom.properties)をコピーして,次のディレクトリに格納します。

    全HCSCサーバ共通の定義の場合

    commonディレクトリはユーザが作成してください。

    <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Command\config\common

    特定のHCSCサーバ用の定義の場合

    サブディレクトリ<HCSCサーバ名>と「common」はユーザが作成してください。Windowsの場合,HCSCサーバ名の大文字・小文字は区別されます。

    <サービスプラットフォームのインストールディレクトリ>\CSC\custom-adapter\Command\config\<HCSCサーバ名>\common

    ファイル名は変更しないでください。

  2. 定義内容を編集して保存します。

コマンドアダプタ実行環境共通プロパティファイルで編集できる定義内容は,コマンドアダプタ実行環境プロパティファイルと同じです。

コマンドアダプタ実行環境共通プロパティファイルは,コマンドアダプタを開始する際に実行環境に反映されます。このため,コマンドアダプタ実行環境共通プロパティファイルの内容を変更する場合は,いったんコマンドアダプタを停止する必要があります。