Java.util.logging のベスト・プラクティス

各クラスで以下のパターンを使用して、JSR47 ロガーを取得できます。

private static final String CLAZZ_NAME = MyClass.class.getName();
private static final String PKG = MyClass.class.getPackage().getName();
private static Logger _logger = Logger.getLogger(PKG);

LogManager は、 ファイル <workspace>/.config/rcpinstall.properties の値に基づいて初期化されます。 そこで、ロガーのレベルを設定できます。 例えば、パッケージ com.ibm.rcp.mypackage 内にある自分のコードに対する ログ項目をすべて表示するには、次のストリングを追加します。

com.ibm.rcp.mypackage.level=FINEST

setlogrlev osgi コンソール・コマンドを使用すると、JSR47 を使用可能な Lotus Expeditor コンポーネントのトレースを行えます。このコマンドについてのヘルプを以下に記します。

• setlogrlev <logger> (level) - ロガーを指定のレベルに設定します。デフォルトは、FINEST です。
• getlogrlev <logger> - 指定のロガーの現行レベルを戻します。

以下の例は、com.ibm.rcp.core.internal.pd.manager ロガーに対して FINEST レベルでのトレースを有効にする詳しい方法を示しています。

osgi> setlogrlev com.ibm.rcp.core.internal.pd.manager

「保護されたロギング」は、 ログ・ステートメントが出力されるかどうかをそれを実行する前に検査するためのパターンです。 ロガーは自ら初期検査を実行して、このメッセージが確実にログ・イベント・ハンドラーに送信されるようにしますが、ロガー・ガーダーに到達するためにはすべてのパラメーターが最初に解決される必要があります。場合によっては、パラメーターを解決するには複雑な操作やストリング操作が必要になる場合があります。そのような場合、ログまたはトレースの呼び出しを行う前に、Java™ コードに明示的な保護を追加することをお勧めします。以下の例は、ログ・メッセージのパラメーター解決の一部として複雑なストリング操作を必要とするロギング・メッセージを示しています。

            if(_logger.isLoggable(WARNING)){
                _logger.logp(WARNING,CLAZZ_NAME, METHOD,
                     Nls.bind("warn.unable.to.get.preference",
                   new Object[]{pid,key}));
           }

次のコード・サンプルは、『保護されたロギング』を必要としない簡単なストリング連結を例示しています。

   private boolean methodP(String param1, String param2) {         
		logger.entering(CLAZZ_NAME,METHOD, param1 + "," + param2);
}

前述の例では、param1 と param2 がストリングであると想定されています。こうしたパラメーターがストリング・オブジェクトではなく、複雑な toString() 実装がなされている場合、保護されたロギングは推奨されていません。

行う: コンポーネントの通常の操作を表し、他のコード・セグメントで発生する可能性のある問題を解決するために役立つイベントに対して、INFO を使用します。 例えば、インストール操作の完了を検証した後に、以下のメッセージがランチャーからログに記録されます。

インストール操作が完了しました。

行う: WARNING は、通常の操作に有害な影響を与えても、ほとんどの操作が実行し続けることを妨げないような問題が発生したときに使用します。 その良い例は、プロビジョニングからの次のメッセージです。

URL EXPEDITOR.png のページ・ファイルの検索に失敗しました。

行う: SEVERE は、ある機能がほとんどまたは完全に失われるようなイベントを示すために使用します。 SEVERE メッセージの例としては、plugin_customization.ini を 読み取ることができない場合にプラットフォーム・プラグインによって書き込まれる次のものがあります。

プラグイン・カスタマイズ・ファイルのロード中にエラーが生じました。

FINER: FINER レベルのメッセージを生成する Logger メソッドのセットがあります。 それらは、entering(...)、exitin(..)、finer(..)、および throwing(..) です。

• entry および exit は、メソッドの入り口および出口に使用します。
• finer は、fine で期待されるよりも詳細ではあっても、 メソッドの出入り口ではないトレースや、例外のスローの前に使用されるトレースに使用できます。
• throwing は、例外をスローまたは再スローする直前に使用します。

すべての例外は、ロギング・ステートメントに記述される必要があります。 その例外が些細 (ささい) なものだったり再スローされている場合を除いて、通常これは WARNING または SEVERE レベルとなります。 その他の指針には、以下のものがあります。

• 例外を含むログ項目についての特定のメッセージを常に提供します。 そのメッセージでは、例外の影響について説明します。
• メッセージではなく、例外をログに記録します。 自分で設定したものでなければ、メッセージが理解可能であること、または存在することさえ保証されていません。
• 例外の発生時に printStackTrace を呼び出さないでください。 これはロガーの役割です。ロガーは、オートノミックなどが例外に反応できるような方法でこれを行います。
• 例外をキャッチしてから新しい例外をスローする場合 (上手に記述された API ではよく生じる)、キャッチした例外をスローした例外の原因として使用する必要があります。 この場合、関係者はみな同じ指針に従うことを前提に、キャッチした例外をログに記録しないでください。
• ときには、その情報がユーザーに役立つ可能性があると思われる場合、 別の例外をスローする予定であっても最初の例外をログに記録する価値があることもあります。

次の 2 つのコード例は、一般的なロギング・パターンです。

  _logger.logp(Level.INFO, CLAZZ_NAME, METHOD,
"Messages.PROCESS_RECS");

以下は、ログに記録することが必要な例外の場合です。

_logger.logp(Level.SEVERE,CLAZZ_NAME,METHOD,Messages,RCP_XML_PROCESSING_ERROR
    throwable);

トレース例 1:

if (_logger.isLoggable(Level.FINE)) 
        	            	_logger.logp(CLASS_NAME_METHOD,"Setting activities for page 
                           " + _model.getName() + ":");    	 
}

トレース例 2:

	private GUID methodX(URL url, IProgressMonitor pM, boolean overrideCache) {

          final String METHOD="methodX";
		if (logger.isLoggable(Level.FINER)) {
			logger.entering(CLASSNAME, METHOD, url==
                             null?"null":url.toExternalForm());
		}
		…
	}

この例では、他の引数はデバッグの際にあまり役立たないので、入り口で URL だけがログに記録されます。アプリケーションがロードされない場合、部分的に計算され、部分的に破損した URL の問題によることが多いので、ロード呼び出しに渡されている URL を正確に知ることはとても役立ちます。 また、これは private メソッドです。 この private メソッドを呼び出すことで多くの public メソッドがそれぞれのジョブを行うので、 public 呼び出しを使用して URL を何回もログに記録する代わりに、これによりロギングをこのメソッドに集中させることができます。

		logger.exiting(CLASSNAME, METHOD, res);

トレース例 3:

public void showApplication(URL url, String pageId, IProgressMonitor 
          progressMonitor)
		 throws IllegalArgumentException, CompositeApplicationException {

    final String METHOD="showApplication";
		if (logger.isLoggable(Level.FINER)) {
			logger.entering(CLASSNAME, 
				
    METHOD, 
				new Object[] {url, pageId, progressMonitor});
		}
} catch (RuntimeException e) {
			logger.logp(Level.SEVERE,CLASS NAME, METHOD
Messages.PORTAL APP JOB UPDATE ERROR, e);
			throw new CompositeApplicationException(e);
		}