メッセージ は、ODA が外部の ODA ログに送信することができる情報のストリングです。システム管理者や開発者は、このログでメッセージを確認することにより、ODA の実行時の状況を知ることができます。
ODA が ODA ログに送信できるメッセージのカテゴリーは次の 2 つです。
メッセージは、ODA コード内で生成することも、メッセージ・ファイルから取得することもできます。 ODK API は、トレース・メッセージとエラー・メッセージをログに記録する trace() メソッドを用意しています。このメソッドは、ODKUtility クラス内で定義されています。
このセクションでは、次のトピックについて説明します。
ODA はメッセージをログの宛先に送信します。ログ は外部の宛先であり、ODA の開始状態を確認する必要のあるユーザーが参照するために用意されています。ログの宛先は、外部ファイルの絶対パス名として、ODA の構成時に構成プロパティー TraceFileName によって定義されます。ログの宛先は、ODA のプロセスと同じマシン上に存在している必要があります。
トレース・ファイル名の形式については、トレース・ファイルの指定を参照してください。
ODK API は、トレース・メッセージとエラー・メッセージをログに記録する trace() メソッドを用意しています。このメソッドは、ODKUtility クラス内で定義されています。
ODA トレース機構によって送信されるメッセージのタイプは、メッセージのトレース・レベルによって異なります。
メッセージのトレース・レベル | 説明 |
---|---|
ゼロ (0)
|
ODA トレース機構を使用して、エラー・メッセージ のログがトレース・ファイルに記録されます。
|
1 から 5 の間のレベル
|
ODA トレース機構を使用して、トレース・メッセージ のログがトレース・ファイルに記録されます。トレース・メッセージは、状況メッセージ、プロパティー値、およびビジネス・オブジェクト名などの通知を目的としています。
|
trace() を呼び出す際は、トレース・レベルを引き数として指定します。
そのために、ODK API はトレース・レベル定数を用意しています。メッセージの生成方法については、メッセージ・ストリングの生成を参照してください。トレース・レベルの設定については、"トレース・ファイルとトレース・レベルの指定"を参照してください。
ODA トレース機構は、Connector Development Kit および InterChange Server Express と同じ形式のファイルを生成します。
トレース・レベルをゼロ (0) に設定すると、ODA は状況に関する情報をログの宛先に送信します。エラーおよび状況の記録を作成することは、一般にロギング と呼ばれます。次のタイプの情報をログの対象にすることをお勧めします。
ODA は通知メッセージやエラー・メッセージを送信できますが、このロギング・プロセスはエラー・ロギング と呼ばれます。
トレース・レベルがゼロ (0) のときは、エラー・ロギングがオンになります。デフォルトでは、トレース・レベルが 5 に設定されているため、ODA のロギングはオフになっています。トレース・レベルは、TraceLevel ODA 構成プロパティーで設定します。
TraceLevel に 0 の値を設定すると、メッセージがエラー・メッセージに指定されます。
エラー・メッセージをログに送信するには、trace() メソッドを使用します。表 58 は、エラー・メッセージを送信する trace() のトレース情報をまとめたものです。
トレース情報 | 説明 | ODKConstant 定数 |
---|---|---|
トレース・レベル | 0 | TRACELEVEL0 |
メッセージ・タイプ | エラー | XRD_FATAL、XRD_ERROR |
| 警告 | XRD_URGENTWARNING、XRD_WARNING |
| 通知 | XRD_INFO |
表 58 に示す情報の他に、trace() メソッドはエラー・メッセージの内容も要求します。メッセージの内容は、次のいずれかの方法により、メッセージ・テキストとして取得することができます。
Util.trace(ODKConstant.TRACELEVEL0, ODKConstant.XRD_ERROR, "Invalid property value");
ODKException クラスの getMsg() メソッドを使用すれば、例外からメッセージ・ストリングを取得することもできます。
try
{ boDef.setAttributeList(Attributes); boDef.setVerbList(Verbs); defList[i] = boDef; }
catch(BusObjInvalidAttrException e)
{ Util.trace(ODKConstant.TRACELEVEL0, ODKConstant.XRD_ERROR, e.getMsg()); }
Util.trace(ODKConstant.TRACELEVEL0, ODKConstant.XRD_WARNING, 1009);
メッセージ・ファイルの使用方法については、メッセージ・ファイルを参照してください。
トレースは、ODA でオンにすることができるトラブルシューティングおよびデバッグ用のオプションの機能です。トレースをオンにすると、システム管理者は、ODA がタスクを実行している間にコンテンツ生成を追跡できます。トレースを使用すると、開発者や、開発者が作成した ODA コードを使用するその他のユーザーは、ODA の振る舞いをモニターできます。
トレースは、特定の ODA メソッドを呼び出したときに追跡することもできます。
トレースは、トレース・レベルが 1 から 5 のときにオンになります。デフォルトではトレース・レベルが 5 に設定されているため、ODA のトレースはオンになっています。トレース・レベルは、TraceLevel ODA 構成プロパティーで設定します。
TraceLevel は、詳細レベルに応じて 1 から 5 を設定できます。トレース・レベルを 5 に設定すると、それより下のレベルのトレース・メッセージがすべて ログに記録されます。ODA が各トレース・レベルで戻す情報のタイプを定義するのは開発者の責任です。表 15 は、推奨される ODA トレース・メッセージの内容を示しています。
詳しくは、トレース・レベルの設定を参照してください。
トレース・メッセージをトレース・ファイルに送信するには、trace() メソッドを使用します。表 58 は、トレース・メッセージを送信する trace() のトレース情報をまとめたものです。
トレース情報 | 説明 | ODKConstant 定数 |
---|---|---|
トレース・レベル | 1 | TRACELEVEL1 |
| 2 | TRACELEVEL2 |
| 3 | TRACELEVEL3 |
| 4 | TRACELEVEL4 |
| 5 | TRACELEVEL5 |
メッセージ・タイプ | トレース | XRD_TRACE |
表 59 に示す情報の他に、trace() メソッドはトレース・メッセージの内容も要求します。メッセージの内容は、次のいずれかの方法で取得できます。
Util.trace(ODKConstant.TRACELEVEL1, ODKConstant.XRD_TRACE, "Entering method getProperties");
Util.trace(ODKConstant.TRACELEVEL1, ODKConstant.XRD_TRACE, 1009);
メッセージ・ファイルの使用方法については、メッセージ・ファイルを参照してください。
この場合、trace() は、指定されたビジネス・オブジェクト定義のコンテンツをフォーマットします。
BusObjDef boDef = new BusObjDef(); // code that populates business object definition ... // write out the business object definition ODKUtility.getODKUtility().trace(ODKConstant.TRACELEVEL5, ODKConstant.XRD_TRACE, boDef);
この場合、trace() は、指定可能なストリングを前に付けてエージェント・プロパティーのリストをフォーマットします。
AgentProperties[] propArray; // code that populates agent-property array ... // write out the agent-property array ODKUtility.getODKUtility().trace(ODKConstant.TRACELEVEL2, ODKConstant.XRD_TRACE, propArray, "List of configuration properties:");
エラー・メッセージの場合でもトレース・メッセージの場合でも、メッセージの内容は、ハードコーディングされたストリング、またはメッセージ・ファイル から取得したストリングとして提供できます。メッセージ・ファイルは、メッセージ番号とそれに関連するメッセージ・テキストが含まれたテキスト・ファイルです。メッセージ・テキストには、ODA からの実行時データを渡すための定位置パラメーターを含めることができます。メッセージ・ファイルは、ファイルを作成し、必要なメッセージを定義することにより提供できます。
このセクションでは、メッセージ・ファイルに関して次のトピックを取り上げます。
メッセージ・ファイル内のメッセージの形式は次のとおりです。
MessageNum Message [EXPL] Explanation
MessageNum は、各メッセージを固有に識別する整数です。
このメッセージ番号は、1 行で指定する必要があります。 メッセージ・テキストは、複数の行にまたがって記述できます (各行は復帰で終了します)。 説明 テキストには、メッセージを表示する原因となった状況をより詳細に記述します。説明テキストの最後の行の後ろには空白行を入れないでください。次のメッセージの番号が説明テキストの次の行に来るようにします。メッセージ・ファイルは、メモ帳など任意のテキスト・エディターで編集してください。
例えば、メッセージ番号 1005 は次のようになります。
1005 ODA content generation is complete. [EXPL] This is a log message that indicates successful completion of the ODA.
メッセージには、実行時にプログラムからの値で置き換えるパラメーターを含めることができます。このパラメーターは定位置パラメーターであり、中括弧付きの番号でメッセージ内に指定します。例えば、次のメッセージには、エージェント・プロパティー名を指定するパラメーターが 3 つ含まれています。
1003 The agent configuration properties are {1}, {2}, {3}. [EXPL] This is a trace message that provides startup properties.
メッセージ・パラメーターの指定方法については、パラメーター値の使用を参照してください。
ODA は、次の 2 つのメッセージ・ファイルのいずれかからメッセージを取得できます。
ODAnameAgent.txt
ここで、ODAname は ODA を固有に識別する名前です。詳しくは、ODA の名前付けを参照してください。このメッセージ・ファイルには、ODA に固有のメッセージを含めます。例えば、LegacyApp という名前の ODA を作成した場合は、そのメッセージ・ファイルに LegacyAppAgent.txt という名前を付けます。
ODA を構成する際は、このメッセージ・ファイル名を変更し、既存のファイルを指し示すことができます。ODA が実行を継続するためには、指定したメッセージ・ファイルが存在しなければなりません。メッセージ・ファイルの指定方法については、"ODA メッセージ・ファイルの指定"を参照してください。
すべての Object Discovery Agent に対してグローバルなメッセージを作成する場合は、それらのメッセージをグローバル・メッセージ・ファイルに追加します。
上記 2 つのメッセージ・ファイルは、製品ディレクトリーの次のサブディレクトリーに含める必要があります。
ProductDir¥ODA¥messages
次のメソッドは、定義済みのメッセージをメッセージ・ファイルから取得します。
メッセージ・メソッド | 説明 |
---|---|
getMsg()
| 指定した重大度のメッセージをメッセージ・ファイルから生成します。 |
trace()
| 指定した重大度のメッセージをメッセージ・ファイルから生成し、それをトレース・ファイルに送ります。 |
表 60 に示すメッセージ生成メソッドは、ODKUtility クラス内に定義されています。これらのメソッドは、次の情報を必要とします。
表 60 に示すメッセージ生成メソッドは、引き数としてメッセージ番号を必要とします。
この引き数は、メッセージ・ファイルから取得するメッセージの番号を指定します。メッセージ・フォーマットで説明したように、メッセージ・ファイル内の各メッセージには、固有のメッセージ番号 (整数) を付ける必要があります。これらのメッセージ生成メソッドは、指定されたメッセージ番号がメッセージ・ファイル内にあるかどうかを検索し、その番号が付いているメッセージ・テキストを抽出します。
これらのメソッドは、該当するメッセージ番号を探す際に、次の順序で ODA メッセージ・ファイルを検索します。
表 60 に示すメッセージ生成メソッドは、引き数としてメッセージ・タイプも必要です。
この引き数は、メッセージの重大度 を指定します。 表 61 は、有効なメッセージ・タイプとそれに関連するメッセージ・タイプ定数を示しています。
メッセージに関連付けるメッセージ・タイプを指定するには、表 61 に示すメッセージ・タイプ定数のいずれかを使用します。
メッセージ・タイプ定数は、ODKConstant クラスで定義されています。
考えられるすべての状況ごとに別のメッセージを作成する必要はありません。代わりに、パラメーターを使って実行時に変化する値を表します。パラメーターを使うことにより、1 つのメッセージで複数の状況に対処することが可能になり、メッセージ・ファイルの増大を防ぐことができます。
パラメーターは常に、{number} のように中括弧で囲まれた番号として表示されます。メッセージに追加したい各パラメーターには、以下のように中括弧で囲んだ番号をメッセージのテキストに挿入します。
message text {number} more message text.
表 60 に示すメッセージ生成メソッドでは、メッセージ・パラメーターとしてオプションの数だけ値を指定できます。メソッド呼び出し内のパラメーター値の数は、メッセージ・テキスト内に定義されているパラメーターの数と同じでなければなりません。メッセージ生成メソッドは、各パラメーターの値を提供する必要があります。例として、メッセージ 1003 を再度見てみましょう。
1003 The agent configuration properties are {1}, {2}, {3}. [EXPL] This is a trace message that provides startup properties.
このメッセージを送信するコードには次のような行があります。
Vector params = new Vector(3); for(int i=0; i<3; i++) params.add(agtProperties[i].propName); Util.trace(ODKConstant.TRACELEVEL2, 1003, ODKConstant.XRD_TRACE, params);
trace() メソッドは、メッセージ・ファイル内のメッセージ・テキストにこれらのパラメーター値を組み合わせてメッセージを作成します。メッセージをトレース・ファイルに書き込む前に、trace() は、メッセージ・パラメーターを params 変数の値で置き換えます。
例えば、メッセージ 1003 は、トレース・ファイル内で次のように表示されるでしょう。
The agent configuration properties are Username, Password, Url.
メッセージ・テキストではパラメーターを使って特定のプロパティー・タイプを指定するので、ハードコーディングされた文字ストリングとして組み込む代わりに、欠落したプロパティーの任意のセットに対して同じメッセージを使用できます。
ユーザー・サイトでは、ODA メッセージをフィルター操作して、E メールまたは E メール・ページャーを使って問題を解決する能力を持つ人に通知するためのプロシージャーを管理者が設定する場合があります。そのため、エラー番号とその番号に対応する意味が Object Discovery Agent の最初のリリースの前後で変わらないようにすることが重要です。エラー番号に対応するテキストを変更することはできますが、テキストの意味を変更したりエラー番号を割り当て直すことは推奨できません。
ただし、それでもエラー番号に対応する意味を変更するという場合は、必ずその変更を文書化して Object Discovery Agent のユーザーに通知してください。
Object Discovery Agent の実行中は、Object Discovery Agent のメッセージ・ファイルを変更することができます。ただし、この変更は、次に Object Discovery Agent が起動してそのメッセージ・ファイルがメモリーに読み込まれるまでは有効になりません。Object Discovery Agent の実行中に InterChange Server Express に障害が発生すると、サーバーは、以前に実行中であったすべての Object Discovery Agent のメッセージ・ファイルを、メモリー内に自動的に読み込みます。