トレース・メッセージとエラー・メッセージの処理

メッセージ は、ODA が外部の ODA ログに送信することができる情報のストリングです。システム管理者や開発者は、このログでメッセージを確認することにより、ODA の実行時の状況を知ることができます。

ODA が ODA ログに送信できるメッセージのカテゴリーは次の 2 つです。

メッセージは、ODA コード内で生成することも、メッセージ・ファイルから取得することもできます。 ODK API は、トレース・メッセージとエラー・メッセージをログに記録する trace() メソッドを用意しています。このメソッドは、ODKUtility クラス内で定義されています。

このセクションでは、次のトピックについて説明します。

ログの宛先の指定

ODA はメッセージをログの宛先に送信します。ログ は外部の宛先であり、ODA の開始状態を確認する必要のあるユーザーが参照するために用意されています。ログの宛先は、外部ファイルの絶対パス名として、ODA の構成時に構成プロパティー TraceFileName によって定義されます。ログの宛先は、ODA のプロセスと同じマシン上に存在している必要があります。

注:
ODK API では、1 つのメソッドでトレース・メッセージとエラー・メッセージの両方を記録します。そのため、ODA はこれらの 2 種類のメッセージを 1 つのファイルに記録します。したがって、このファイルはトレース・ファイル と呼ばれていますが、ODA が生成するエラー・メッセージも中に含まれます。

トレース・ファイル名の形式については、トレース・ファイルの指定を参照してください。

トレース・ファイルへのメッセージの送信

ODK API は、トレース・メッセージとエラー・メッセージをログに記録する trace() メソッドを用意しています。このメソッドは、ODKUtility クラス内で定義されています。

ODA トレース機構によって送信されるメッセージのタイプは、メッセージのトレース・レベルによって異なります。

表 57. トレース・レベルとメッセージ・タイプ
メッセージのトレース・レベル 説明

ゼロ (0)

ODA トレース機構を使用して、エラー・メッセージ のログがトレース・ファイルに記録されます。

1 から 5 の間のレベル

ODA トレース機構を使用して、トレース・メッセージ のログがトレース・ファイルに記録されます。トレース・メッセージは、状況メッセージ、プロパティー値、およびビジネス・オブジェクト名などの通知を目的としています。

注:
ODA ランタイムは、ODA トレース機構を暗黙的に操作します。トレース機構は、ビジネス・オブジェクト・ウィザードの「エージェントの構成」ダイアログ・ボックスでトレース・ファイルを設定するまでは機能しません。詳しくは、"ODA の開始"を参照してください。

trace() を呼び出す際は、トレース・レベルを引き数として指定します。

そのために、ODK API はトレース・レベル定数を用意しています。メッセージの生成方法については、メッセージ・ストリングの生成を参照してください。トレース・レベルの設定については、"トレース・ファイルとトレース・レベルの指定"を参照してください。

ODA トレース機構は、Connector Development Kit および InterChange Server Express と同じ形式のファイルを生成します。

エラー・メッセージと通知メッセージ

トレース・レベルをゼロ (0) に設定すると、ODA は状況に関する情報をログの宛先に送信します。エラーおよび状況の記録を作成することは、一般にロギング と呼ばれます。次のタイプの情報をログの対象にすることをお勧めします。

ODA は通知メッセージやエラー・メッセージを送信できますが、このロギング・プロセスはエラー・ロギング と呼ばれます。

重要:
例外が発生した場合は必ず、例外をスローしてビジネス・オブジェクト・ウィザードにその例外を表示し、例外を説明するエラー・メッセージをトレース・ファイルに書き込むことをお勧めします。例外をすべてトレース・ファイルに記録すれば、ODA または Business Object Designer Express に万一障害が発生したとしても、例外を特定できるようになります。

トレース・レベルがゼロ (0) のときは、エラー・ロギングがオンになります。デフォルトでは、トレース・レベルが 5 に設定されているため、ODA のロギングはオフになっています。トレース・レベルは、TraceLevel ODA 構成プロパティーで設定します。

TraceLevel に 0 の値を設定すると、メッセージがエラー・メッセージに指定されます。

エラー・メッセージをログに送信するには、trace() メソッドを使用します。表 58 は、エラー・メッセージを送信する trace() のトレース情報をまとめたものです。

表 58. エラー・メッセージのトレース情報
トレース情報 説明 ODKConstant 定数
トレース・レベル 0 TRACELEVEL0
メッセージ・タイプ エラー XRD_FATALXRD_ERROR

警告 XRD_URGENTWARNINGXRD_WARNING

通知 XRD_INFO

表 58 に示す情報の他に、trace() メソッドはエラー・メッセージの内容も要求します。メッセージの内容は、次のいずれかの方法により、メッセージ・テキストとして取得することができます。

トレース・メッセージ

トレースは、ODA でオンにすることができるトラブルシューティングおよびデバッグ用のオプションの機能です。トレースをオンにすると、システム管理者は、ODA がタスクを実行している間にコンテンツ生成を追跡できます。トレースを使用すると、開発者や、開発者が作成した ODA コードを使用するその他のユーザーは、ODA の振る舞いをモニターできます。

トレースは、特定の ODA メソッドを呼び出したときに追跡することもできます。

トレースは、トレース・レベルが 1 から 5 のときにオンになります。デフォルトではトレース・レベルが 5 に設定されているため、ODA のトレースはオンになっています。トレース・レベルは、TraceLevel ODA 構成プロパティーで設定します。

TraceLevel は、詳細レベルに応じて 1 から 5 を設定できます。トレース・レベルを 5 に設定すると、それより下のレベルのトレース・メッセージがすべて ログに記録されます。ODA が各トレース・レベルで戻す情報のタイプを定義するのは開発者の責任です。表 15 は、推奨される ODA トレース・メッセージの内容を示しています。

詳しくは、トレース・レベルの設定を参照してください。

トレース・メッセージをトレース・ファイルに送信するには、trace() メソッドを使用します。表 58 は、トレース・メッセージを送信する trace() のトレース情報をまとめたものです。

表 59. トレース・メッセージのトレース情報
トレース情報 説明 ODKConstant 定数
トレース・レベル 1 TRACELEVEL1

2 TRACELEVEL2

3 TRACELEVEL3

4 TRACELEVEL4

5 TRACELEVEL5
メッセージ・タイプ トレース XRD_TRACE

表 59 に示す情報の他に、trace() メソッドはトレース・メッセージの内容も要求します。メッセージの内容は、次のいずれかの方法で取得できます。

メッセージ・ファイル

エラー・メッセージの場合でもトレース・メッセージの場合でも、メッセージの内容は、ハードコーディングされたストリング、またはメッセージ・ファイル から取得したストリングとして提供できます。メッセージ・ファイルは、メッセージ番号とそれに関連するメッセージ・テキストが含まれたテキスト・ファイルです。メッセージ・テキストには、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 つのメッセージ・ファイルのいずれかからメッセージを取得できます。

上記 2 つのメッセージ・ファイルは、製品ディレクトリーの次のサブディレクトリーに含める必要があります。

ProductDir¥ODA¥messages
 

メッセージ・ストリングの生成

次のメソッドは、定義済みのメッセージをメッセージ・ファイルから取得します。

表 60. メッセージ・ストリングを生成するメソッド
メッセージ・メソッド 説明
getMsg()
指定した重大度のメッセージをメッセージ・ファイルから生成します。
trace()
指定した重大度のメッセージをメッセージ・ファイルから生成し、それをトレース・ファイルに送ります。

表 60 に示すメッセージ生成メソッドは、ODKUtility クラス内に定義されています。これらのメソッドは、次の情報を必要とします。

メッセージ番号の指定

表 60 に示すメッセージ生成メソッドは、引き数としてメッセージ番号を必要とします。

この引き数は、メッセージ・ファイルから取得するメッセージの番号を指定します。メッセージ・フォーマットで説明したように、メッセージ・ファイル内の各メッセージには、固有のメッセージ番号 (整数) を付ける必要があります。これらのメッセージ生成メソッドは、指定されたメッセージ番号がメッセージ・ファイル内にあるかどうかを検索し、その番号が付いているメッセージ・テキストを抽出します。

これらのメソッドは、該当するメッセージ番号を探す際に、次の順序で ODA メッセージ・ファイルを検索します。

  1. ODA 固有のメッセージ・ファイル (デフォルト名は ODAnameAgent.txt)
  2. グローバル ODK メッセージ・ファイル (useragentmessages.txt)

メッセージ・タイプの指定

表 60 に示すメッセージ生成メソッドは、引き数としてメッセージ・タイプも必要です。

この引き数は、メッセージの重大度 を指定します。 表 61 は、有効なメッセージ・タイプとそれに関連するメッセージ・タイプ定数を示しています。


表 61. メッセージ・タイプ
メッセージ・タイプ定数 重大度レベル 説明
XRD_FATAL 致命的エラー プログラムの実行が停止するエラーを示します。
XRD_ERROR エラー 調査が必要なエラーを示します。
XRD_URGENTWARNING 緊急警告 問題である可能性が高く、無視しないほうがよい状況を示します。
XRD_WARNING 警告 問題である可能性があるものの、無視しても構わない状況を示します。
XRD_INFO 通知 単なる通知メッセージ。アクションは不要です。
XRD_TRACE ---- トレース・メッセージで使用します。

メッセージに関連付けるメッセージ・タイプを指定するには、表 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 のメッセージ・ファイルを、メモリー内に自動的に読み込みます。

Copyright IBM Corp. 2004