コラボレーションに対する操作

このセクションでは、コラボレーション全体に影響する操作について説明します。これには、以下の操作が含まれます。

各コラボレーション・テンプレートには、メッセージ・ファイルが関連付けられている必要があります。

メッセージ・ファイル には、コラボレーションの例外およびメッセージのロギングのためのテキストが含まれています。

メッセージ・ファイル内の各メッセージは、固有 ID によって識別されます。また、メッセージのテキストには、プレースホルダー変数も含まれます。

コラボレーションは、特定のメッセージを表示するメソッドを呼び出すときに、メッセージの識別番号および (場合によっては) 追加パラメーターをこのメソッドに渡します。このメソッドはこの識別番号を使用して、メッセージ・ファイルから正しいメッセージを探し出し、追加パラメーターの値をメッセージ・テキストのプレースホルダー変数に挿入します。

例えば、あるコラボレーションのメッセージ・ファイルに番号 23 のメッセージが含まれ、このテキストには {1} および {2} と表示された 2 つのプレースホルダー変数が含まれるとします。

23
 Customer ID {1} could not be changed: {2}
 

このコラボレーションは、このメッセージを表示または記録する場合、raiseException() など適切なメソッドに対して、メッセージ (23) の識別番号、2 つの追加パラメーター、顧客 ID 番号 (6701)、および greater than maximum length などの追加説明テキストを含む String 変数を渡します。このメソッドは、正しいメッセージを探し出し、メッセージのプレースホルダーのパラメーター値を置換し、以下のメッセージを表示または記録します。

Customer ID 6701 could not be changed: greater than maximum length
 

メッセージのロギング

コラボレーション・テンプレートは、管理者に関係があると考えられる事態が発生するたびにメッセージをログに記録できます。メッセージをログに記録するには、コラボレーション・テンプレートの logInfo()、logWarning()、および logError() メソッドを使用します。

各メソッドには、さまざまなメッセージの重大度レベルが関連付けられています。表 47 に、重大度レベルおよびそれに関連したメソッドを示します。


表 47. ログ・メソッドのメッセージ・レベル
メソッド 重大度レベル 説明
logInfo() 情報 情報のみ。ユーザーは何もする必要はありません。
logWarning() 警告 問題に関する情報を示します。このレベルは、ユーザーが解決する必要がある問題には使用しないでください。
logError() エラー ユーザーが調べる必要がある重要な問題を示します。

これらのメソッドがログ宛先に送信するメッセージ・テキストは、接頭部に重大度レベルが付いています。

このセクションでは、ロギング・メッセージについて、以下の内容を説明します。

メッセージ・ファイルの使用

すべてのコラボレーション・テンプレートには、ログ・メッセージを保持するメッセージ・ファイルが必要です。

コラボレーションがエラーをログに記録する場合、エラー・メッセージのテキストにはコラボレーションのメッセージ・ファイルが使用されます。次の例では、コラボレーションのメッセージ・ファイルにテキストが格納されているエラー・メッセージをログに記録します。

logError(10, customer.get("LName"), customer.get("FName");
 

エラー・メッセージ 10 のテキストには、2 つのメッセージ・パラメーターがあり、以下のようにメッセージ・ファイルに表示されます。

10 
 Credit report error for {1} {2}. 
 

logError() メソッドが実行されると、メッセージ・ファイルからメッセージ 10 のテキストを取得し、メッセージ・パラメーター 1 および 2 で顧客のラストネームおよびファーストネームを置換して、メッセージの接頭部に重大度「Error」を付加します。その後、このエラー・メッセージがコラボレーションのログ宛先に書き込まれます。

例えば、顧客名 John Davidson のログに記録されたメッセージは、次のようになります。

Error: Credit report error for Davidson John.
 

コラボレーションが E メール通知に構成されていると、logError() はこのエラー・メッセージを指定された E メール受信側 (複数の場合あり) にも送信します。メッセージ・ファイルの設定方法の詳細は、メッセージ・ファイルの作成を参照してください。

適切なメッセージ・ロギングの原則

メッセージを作成する場合、管理者がロギング機能を使用する方法に注意してください。

重大度レベルの割り当て

メッセージに対するエラー・レベルの割り当ては、厳密に行う必要があります。

InterChange Server の E メール通知機能では、エラー・メッセージまたは致命エラー・メッセージの生成が検出されると、指定された人物 (通常は管理者) にメッセージが送信されます (logError())。管理者は、この InterChange Server の E メール通知機能を使用すると共に、この機能を E メール・ページャーにリンクして、エラーが発生した場合にメッセージを送信することもできます。エラー・レベルをメッセージに正確に割り当てることにより、重大メッセージの数を減らすことができます。

メッセージの変更

例えば、テキストを明確にしたり、拡張するために、メッセージのテキストをいつでも変更できます。ただし、特定のタイプのエラーにメッセージ番号を割り当てたら、その番号を再度割り当てない ことが重要です。多くの管理者はスクリプトを使用してログ・メッセージをフィルター操作しています。ただし、これらのスクリプトはメッセージ番号に依存しています。このため、メッセージ・ファイルの番号の意味を変更しないことが重要です。番号が変更されると、ユーザーがメッセージを喪失したり、間違ったメッセージを受信することがあります。

情報メッセージを使用する場合

logInfo() メソッドを使用して、ユーザー独自のデバッグ用一時メッセージを作成できます。

ただし、開発が完了したら、これらのデバッグ・メソッド呼び出しは除去するようにしてください。

コラボレーションの通常操作を文書化する場合は、logInfo() メソッドを使用しないようにしてください。このメソッドを使用すると、管理者のログ・ファイルが関係のないメッセージでいっぱいになってしまいます。代わりに、trace() メソッドを使用して、管理者用のデバッグの詳細情報を記録してください。

トレース・メッセージの追加

トレース・メッセージをコラボレーション・テンプレートに追加することにより、コラボレーション・オブジェクトの実行時にそのアクションの詳細な説明が生成されるようにすることができます。トレース・メッセージは、ユーザー独自のデバッグや、管理者によるオンサイトのトラブルシューティングに役立ちます。

トレース・メッセージは、そのトレース・メッセージに含まれるログ・メッセージとは異なり、デフォルトでは削除可能となっています。ただし、そのログ・メッセージを削除することはできません。通常、トレース・メッセージの方がより詳細で、一定の状況下でのみ表示されるようになっています。例えば、あるユーザーがコラボレーション・オブジェクトのトレース・レベルを意図的にゼロより大きい番号に構成した場合などがあります。トレース・メッセージとログ・メッセージは別のファイルに送信できます。

コラボレーションには、以下の 2 つのタイプのトレース・メッセージがあります。

System Manager の「Collaboration Object Properties」ダイアログ・ボックスを使用して、両タイプのトレース・メッセージのトレース・レベルを設定します。

コラボレーション・テンプレート開発者は、コラボレーション生成トレースを要求できるレベルを作成します。これについては、次のセクションで説明します。システム生成トレース・レベルは、すべてのコラボレーション・オブジェクトに対して同じです。これについては、"InterChange Server Express 生成トレース・メッセージ"を参照してください。

コラボレーション生成トレース・メッセージ

トレース・メッセージをコラボレーション・テンプレートに追加して、そのコラボレーションに固有の操作を報告できます。以下は、コラボレーションがトレース・ファイルに書き込むことができる情報の例です。

トレース・レベルの割り当て

各トレース・メッセージには、1 から 5 までの間の トレース・レベルを割り当てる必要があります。通常、トレース・レベルには、レベルとその詳細の度合いに相関関係があります。通常は、レベル 1 よりレベル 2 の方が詳細であり、レベル 2 よりレベル 3 の方が詳細というようになります。このため、レベル 1 のトレースをオンにした場合、レベル 5 のメッセージより詳細ではないメッセージが表示されます。ただし、レベルは必要なレベルに設定できます。以下は、レベルを割り当てる際の提案事項です。

特定のレベルでのトレースをオンにすると、特定のレベルに関するメッセージと、これ以下のレベルに関するメッセージが表示されます。例えば、レベル 2 のトレースの場合は、レベル 2 とレベル 1 に関するメッセージが表示されます。

ヒント:
トレース・レベルは、文書に記録して、ユーザーがトレースを行うときに使用するレベルがわかるようにしてください。

トレース・メッセージの生成

以下は、メッセージと、メッセージを生成するメソッドの呼び出しの例です。メッセージは、以下のようにメッセージ・ファイルに表示されます。

20
 Configuration property DO_VERIFICATION = {1} 
 

このメソッドの呼び出しは、構成プロパティー DO_VERIFICATION の値を取得し、この値を使用してメッセージのパラメーターを置換します。コードは、以下のようにコラボレーションに表示され、このメッセージは、ユーザーがトレースをレベル 3 に設定したときに表示されます。


String validateProp = getConfigProperty("DO_VERIFICATION"); trace(3, 20, validateProp);

以下の例では、Employee ビジネス・オブジェクトの Salary 属性が取得され、給与の額に基づいて分岐の決定が実行されます。メッセージ・ファイルのメッセージは、以下のとおりです。

15
 Salary {1} {2}
 

この例では、給与の額と実行された経路が記述されたトレース・メッセージが送信されます。
int newsalary = employee.getInt("Salary"); String sal = Integer.toString(newsalary); if (newsalary <150000) { trace (3, 15, sal, "do extra check"); } else { trace (3, 15, sal, "take normal path"); }

InterChange Server Express 生成トレース・メッセージ

InterChange Server Express のコラボレーション・ランタイム環境には、コラボレーションの実行に関するメッセージを提供するトレース・コンポーネントが用意されています。

ランタイム環境のトレース・コンポーネントは、6 つの番号を使用してトレース・レベルを示します。

第 1 レベルのゼロ (デフォルト設定) は、トレースが行われていないことを示します。レベル 1 から 5 は、それぞれ詳細のレベルを示します。レベル 1 のトレースは最小限の詳細レベルを示し、レベル 5 は最も高い詳細レベルを示します。

トレースをオンにするには、コラボレーション・オブジェクトのトレース・レベルをゼロより大きい値にします。各トレース・メッセージには、個別のレベルが関連付けられています。表 48 に、各レベルで表示されるメッセージのタイプを示します。

表 48. システム生成トレースのトレース・レベル
レベル InterChange Server Express システム生成トレース
0 なし。
1 トリガー・イベントの受信およびシナリオの開始。
2 シナリオの開始および完了 (順方向実行およびロールバックの報告)。
3 アクション・ノードの実行。
4 サービス呼び出しのビジネス・オブジェクトの送信および応答の受信。
5 レベル 4 のトレースの詳細バージョン。このレベルのトレースでは、送受信されるビジネス・オブジェクトの各属性値が出力されます。

コラボレーション構成プロパティーの検索

コラボレーションの構成プロパティーを検索するには、getConfigProperty() メソッドを使用します。

以下の例は、コラボレーションが構成プロパティーを使用してコード経路を決定する方法を示します。
if (getConfigProperty("CONVERT_NEGQTY").equals("true")) { // take this code path } else { // take this code path }

構成値を特定の値と比較する場合は、常に equals() メソッドを使用してください (例を参照)。

条件等価演算子 == は使用しないでください。この演算子を使用すると、同じ値に 2 つのオブジェクトが含まれるかどうかではなく、2 つの変数が同じオブジェクトを参照しているかどうかがテストされます。

値は大文字小文字が区別されるので注意してください。構成パラメーターの大文字小文字の区別は、等価性についてテストするコードと同じである必要があります。

上記の例では、True の値により、比較が失敗します。

また、構成プロパティーには、セミコロンで区切った値の配列を使用することもできます。詳細については、getConfigPropertyArray()を参照してください。

コラボレーション・オブジェクト・インスタンスの再利用

通常、InterChange Server Express は、各トリガー・イベントを処理するためにコラボレーション・オブジェクトのインスタンスを作成します。

インスタンスがトリガー・イベントの処理を完了すると、そのリソースは解放され、Java 空きプールに戻されます。ただし、JDK では、これらのインスタンスが必ずしも効率的にクリーンアップされるとは限らないため、メモリーが過度に使用される場合があります。

InterChange Server Express では、メモリーの使用量を減らすために、「Collaboration Instance Reuse」オプションが使用されます。これにより、コラボレーション・オブジェクトのインスタンスをキャッシュに格納し、同じタイプのコラボレーション・オブジェクトのインスタンスを後で生成するときにそれを再使用して、コラボレーション・オブジェクトのインスタンスを再生することができます。InterChange Server Express で既存のコラボレーション・インスタンスを再生すると、次のことを回避できます。

「Collaboration Instance Reuse」オプションは、コラボレーション・テンプレートが以下の両方の 要件を満たす限り、自動的に使用されます。

これらの条件のいずれかが満たされない 場合、「Collaboration Instance Reuse」オプションは使用されません。このため、このオプションを利用するには、コラボレーション・テンプレート・コードでテンプレート (グローバル) 変数を使用しないようにしてください。

テンプレート変数はユーザーが宣言し、その有効範囲はコラボレーション・テンプレート全体です。テンプレート変数は、「定義」ウィンドウの「宣言」タブにある「グローバル変数:」というラベルが付いた領域で宣言します。

コラボレーションにテンプレート変数が必要だが、「Collaboration Instance Reuse」オプションを使用したい場合は、コラボレーション・テンプレートが以下のプログラミング要件を満たすようにしてください。

要確認

第 1 ノードで初期化されていない テンプレート変数を含むコラボレーション・テンプレートは、安全に再生できません。これは、キャッシュに格納されているコラボレーション・オブジェクト・インスタンスの変数値が再使用される場合、このインスタンスが永続的であるためです。キャッシュに格納されているコラボレーション・インスタンスが再使用され、実行が開始されると、各テンプレート変数には、コラボレーション・インスタンスの前回の使用時の終わりの値が含まれます。

テンプレート変数が正しく初期化されるようコラボレーション・テンプレートをコーディングしたら、以下の操作を実行して「Collaboration Instance Reuse」オプションを使用可能にします。

  1. EnableInstanceReuse というコラボレーション固有の構成プロパティーを定義し、そのデフォルト値を true または false に設定します。

    「テンプレート定義」ウィンドウで、コラボレーション固有の構成プロパティーを定義します。

    コラボレーション・オブジェクトに求める振る舞いに応じて、EnableInstanceReuse のデフォルト値を設定します。

  2. 再生する各コラボレーション・オブジェクトの EnableInstanceReuse コラボレーション・プロパティーが true に設定されていることを確認します。

    コラボレーション固有の構成プロパティーの値は、System Manager の「Collaboration Object Properties」ウィンドウの「プロパティー」タブで設定します。詳細については、「システム管理ガイド」を参照してください。

前のプログラミング要件を満たすようコラボレーションをコーディングできない場合は、「Collaboration Instance Reuse」オプションを使用しない でください。このオプションを使用できないようにするには、コラボレーション・テンプレートに EnableInstanceReuse コラボレーション構成プロパティーを定義しないでください。

注:
「Collaboration Instance Reuse」オプションをアクティブにするには、コラボレーション・テンプレートを停止してから始動する必要があります。このオプションは、コラボレーションを再活動化しないとアクティブにはなりません。

ソフトウェアは コラボレーション・インスタンス・キャッシュ というキャッシュを使用して、コラボレーション・オブジェクトのインスタンスを保持します。コラボレーション・インスタンス・キャッシュのサイズは、「並行イベントの最大数」の値から算出されます。この値は、System Manager の「Collaboration Object Properties」ウィンドウの「一般」タブで構成します。コラボレーション・インスタンス・キャッシュのサイズは、コラボレーションを実行するフロー処理モデルがイベントと呼び出しのどちらを使用して起動されるかに応じて、変更する必要があることがあります。

コラボレーション・インスタンス・キャッシュのサイズの変更には、CollaborationInstanceCacheSize と呼ばれるコラボレーション構成プロパティーの定義が含まれます。

このプロパティーはその他のコラボレーション・プロパティーと共に、「テンプレート定義」ウィンドウの「一般」タブにある「プロパティー」というラベルが付いた領域で定義します。

CollaborationInstanceCacheSize を定義したら、その値をコラボレーション・インスタンス数のデフォルト値に適した値に設定します。詳細については、「システム管理ガイド」の「Collaboration Instance Reuse」オプションに関する説明を参照してください。

ネイティブ・マップの呼び出し

通常、マップおよびサブマップの呼び出しはマップ内でのみ行われます。ただし、場合によっては、コラボレーションは InterChange Server Express ネイティブ・マップを直接呼び出す必要がある場合があります。コラボレーションからネイティブ・マップを呼び出す場合、以下のようないくつかの利点があります。

コラボレーション・テンプレートからのネイティブ・マップの呼び出しには、以下のステップが含まれます。

マップ名用のコラボレーション・プロパティーの作成

呼び出し対象のマップ名を含むコラボレーション・プロパティーを作成できます。このステップは必須ではありませんが、このステップにより、マップ名が変更された場合でもコラボレーション・コードを再コンパイルする必要がなくなります。代わりに、マップ名が変更された場合は、このコラボレーション・プロパティーの値を変更するだけで済みます。例えば、MAP_NAME と呼ばれるコラボレーション・プロパティーを定義することにより、呼び出す必要があるマップ名を保持できます。コラボレーション・プロパティーは、「テンプレート定義」ウィンドウで定義されます。詳細については、"コラボレーション構成プロパティーの定義 (「プロパティー」タブ)"を参照してください。

注:
getConfigProperty() メソッドを使用して、コラボレーション・テンプレートのコード内でこのコラボレーション・プロパティーの値を取得します。

コラボレーションの初期化

マップを呼び出すためのコラボレーション・テンプレートの初期化には、コラボレーション・テンプレートに対するマッピング API の Java クラスのインポートが含まれます。InterChange Server Express マップには、実行すべき特定の Java クラスが必要です。

これらのクラスの一部は、コラボレーション・テンプレートに自動的には組み込まれません。マップを実行するには、以下のマップ・クラスおよびパッケージを明示的にインポートする必要があります。

これらの各項目は、「テンプレート定義」ウィンドウの「宣言」タブの「インポート」セクションでインポートします。

例えば、インポート・テーブルに次のエントリーを追加して、マップ・クラスをコラボレーション・テンプレートにインポートします。

CxCommon.CxExecutionContext
 CxCommon.Exceptions.*
 CxCommon.Dtp.*
 CxCommon.BaseRunTimes.*
 DLM.*
 

注:
パッケージ内のすべての クラスをインポートする場合は、パッケージ名の後ろに「.*」構文を付けるようにしてください。

Java クラスのインポート方法の詳細については、"Java パッケージのインポート"を参照してください。

マップの呼び出し

マップを呼び出すには、マッピング API クラスの runMap() メソッド、DtpMapService を使用します。runMap() メソッドには、以下の情報を引き数として渡す必要があります。

したがって、runMap() を呼び出す前に コラボレーション内でこの情報を初期化する必要があります。

マップ名の取得

実行対象のマップの名前を渡す場合、runMap() の呼び出しでマップ名をハードコーディングできます。ただし、最も柔軟な設計は、コラボレーション・プロパティーにマップ名を含めるという方法です。この設計には、以下の手順が含まれます。

図 70 に、コラボレーション・プロパティー MAP_NAME に格納されているマップ名を取得するコード行を示します。

図 70. 実行対象のマップの名前の取得

String map_name = getConfigProperty("MAP_NAME");
 

注:
この方法を使用するには、MAP_NAME コラボレーション・プロパティーが作成されており、実行対象の正しいマップ名がこのプロパティーに割り当てられていることが前提です。

入力配列の初期化

runMap() メソッドには、マップのソース・ビジネス・オブジェクトを含む入力配列が必要です。通常、マップにより、単一のソース・ビジネス・オブジェクトが変換されます。このようなマップの場合、この入力配列には 1 つの要素のみがあります。通常、コラボレーションからマップを呼び出す場合、トリガー・ビジネス・オブジェクトのコピーを入力配列に入れます。この場合、この入力配列を 3 番目の引き数として runMap() に入力します。

図 71 に、コラボレーションのトリガー・ビジネス・オブジェクトのコピーを使用して入力配列を初期化するコード行を示します。

図 71. トリガー・ビジネス・オブジェクトによる入力配列の初期化

BusObj[] sourceBusObjs = { inputBusObj };
 

マップ実行コンテキストの作成

マップ・インスタンスは、マップが必要とする以下のような情報を含む特定のマップ実行コンテキスト内で実行されます。

マッピング API は、マッピング実行コンテキストを MapExeContext オブジェクトとして示します。マップ・コードでは、マップの実行コンテキストを常にシステム生成変数 cwExecCtx から取得できます。ただし、コラボレーション・テンプレートからはこのようなシステム生成変数にアクセスできません。代わりに、コラボレーションは以下の手順を実行する必要があります。

図 72 に、マップ実行コンテキストを初期化するコード・フラグメントを示します。これらのコード・フラグメントには EVENT_DELIVERY の呼び出しコンテキスト (アプリケーション固有のビジネス・オブジェクトから汎用ビジネス・オブジェクトへの変換) およびトリガー・ビジネス・オブジェクトの元の要求ビジネス・オブジェクトが使用されています。

図 72. マップ実行コンテキストの初期化

// Instantiate objects for the map execution context and the global
 // execution context
 map_exe_context = new MapExeContext();
 global_exe_context = new CxExecutionContext();
  
 // Assign the map execution context to the global execution context
 global_exe_context.setContext(
    CxExecutionContext.MAPCONTEXT,
    map_exe_context);
  
 // Initialize the map execution context
 map_exe_context.setInitiator(MapExeContext.EVENT_DELIVERY);
 

runMap() メソッドの呼び出し

コラボレーション・テンプレートは、マップ情報を初期化した後に、マップを呼び出すことができます。runMap() メソッドを呼び出すには、以下の 2 つの手順を実行します。

図 73 に、次の特性でマップを実行するための runMap() への呼び出しを示します。

コラボレーション変数の取り込み

マップの宛先ビジネス・オブジェクトは、runMap() が戻す出力配列で使用できます。コラボレーションから宛先ビジネス・オブジェクトを送信するには、そのオブジェクトを出力配列から適切なコラボレーション変数にコピーする必要があります。通常、このコラボレーション変数は、コラボレーションの To ポートに関連付けられます。このため、通常、宛先ビジネス・オブジェクトは、ToBusObj コラボレーション変数にコピーされます。

図 74 は、BusObj.copy() メソッドを使用して、図 73 内の runMap() 呼び出しによって戻される単一宛先ビジネス・オブジェクトを ToBusObj コラボレーション変数へコピーします。

図 74. コラボレーション変数の取り込み

ToBusObj.copy(destinationBusObjs[0]);
 

Copyright IBM Corp. 2004