クライアントコードの記述

本節では、 ログ要求を発行するクライアントコードの記述方法を説明します。

デモンストレーション実装のbasic.client パッケージに属するクラス群も参照してください。

概要

クラス名

本チュートリアルでは、 クラスは全てクラス名のみで表記されています。 完全な名称は以下の通りです。

PTLog のクラス

LogTap の生成

利便性の上から、 はじめに LogTap を生成する必要があります。

public class Client
{
    ....

    final static
    public LogTap TAP =
    new LogTap(Client.class, WriterProvider.STDOUT);
}

LogTap は JDK ログ API(ないし Apache Log4j)における Logger とほぼ同等のものです。

コンストラクタパラメータの前者は、 ログ要求の「主体(subject)」を意味します。 これはログ要求の発行者を識別するために使用されます。

後者のパラメータは、 基礎となるログフレームワークを指定します。 この例における "WriterProvider.STDOUT" の場合は、 初期状態ではログ要求が標準出力に書き出されることを意味します。

後者のパラメータに関する詳細は "ログフレームワークへの接続" をご覧ください。

Log 経由での要求発行

以上で、 LogTap から取得した Log 経由でログ要求を発行できます。 例えば：

    public void doSomething(){
        Log log = TAP.getLog("doSomething");

        log.info("INFO 型によるログ");
        log.dump("DUMP 型によるログ");

        try{
            ....
            ....
        }
        catch(Exception e){
            log.error("ERROR 型によるログ", e);
        }
    }

LogTap#getLog() のパラメータは、 ログ要求の発行元となるメソッドの名前です。

Log は、 ログ要求を受け付ける幾つかの「型(type)」を持っています。

(*1) は、このチュートリアルにおいて "Jakarta Common Loggings" の略称として使用されます。

(*2) は、Log4j 1.2.12 からサポートされています。

(*3) は、 JCL 1.0.x では、"DEBUG" （Log4j 環境）ないし "FINEST"（JDK Logging API 環境）を使用しています。

(*4) に対応する出力は、型変換により可能になります。

Log クラスは、 各「型」ごとに３つのシグネチャバリエーションを持っています。

    public void <type>(String message, Throwable throwable);

    public void <type>(Object data);

    public boolean enables<Type>();

最初の形式は、 他のログフレームワーク(例えば JDK logging API、Log4j ないし JCL) と同様の一般的なものです。 message および（ないし） throwable には、 "null" を指定しても構いません。

２つ目の形式は、 Throwable を含む任意のデータのログ要求の際に使用されます。 String か Throwable のいずれかのみを記録したい場合に有用です。

３つ目の形式は、 指定した「型」のログ要求の可否を判定するのに使用されます。 例えば：

    public void doSomething(){
        Log log = TAP.getLog("doSomething");

        if(log.enablesDump()){
            log.dump("DUMP 型によるログ");
        }
    }

"log.enablesDump()" 条件下のブロックは、 "dump" によるログが可能である場合にのみ実行されます。 このような条件は、実行中に動的に変化する可能性があります。

このような確認は、 常に情報収集を実施することが非常に高価である場合に有用です。

"trace" 型には、 これらに加えて３つの追加バリエーションがあります。

    public void doSomething(){
        Log log = TAP.getLog("doSomething");
        log.enter(); // メソッド開始を意味します

        ....
        log.pass("initialize phase - 1");
        ....
        log.pass("initialize phase - 2");
        ....
        log.pass("initialize phase - 3");
        ....
        ....

        log.exit(); // メソッド終了を意味します
    }

上記例におけるそれぞれのメソッドは "Log#trace" メソッドで置き換え可能ですが、 これらのメソッドは "trace" ログの統一された要求（およびフォーマット） 方式を提供します。

それに、メソッド起動コードが短いのは重要ですよね？

    public void doSomething(int p1, int p2, int p3, ....){
        Log log = TAP.getLog("doSomething");
        log.dump("p1=" + p1 +
                 "/p2=" + p2 +
                 "/p3=" + p3 +
                 .....);
    }

    public void doSomething(int p1, int p2, int p3, ....){
        Log log = TAP.getLog("doSomething");
        log.dump("p1=" + p1);
        log.dump("p2=" + p2);
        log.dump("p3=" + p3);
        ....
    }

    public void doSomething(int p1, int p2, int p3, ....){
        Log log = TAP.getLog("doSomething");

        LogBuffer dump = log.forDump();
        dump.add("p1", p1);
        dump.add("p2", p2);
        dump.add("p3", p3);
        ....
        dump.flush(); // ログ要求発行
    }