Home of: [Atelier "FUJIGURUMA"] >> [PTLog hosted by SourceForge.net]

SEE "For Readers of English Version",
or Japanese version of this page

Customize log type

This section explains how to customize log type for log categorizing.

Please see also classes belonging to basic.type package of demonstration implementation.

Overview

Class names

In this tutorial, abbreviated class names are used. Complete names are shown below.

Classes of PTLog

Notation Full name
InfoLogType jp.ne.dti.lares.foozy.ptlog.InfoLogType
LevelTypeConverterFactory jp.ne.dti.lares.foozy.ptlog.logapi.LevelTypeConverterFactory
Log jp.ne.dti.lares.foozy.ptlog.Log
LogAPIProvider jp.ne.dti.lares.foozy.ptlog.logapi.LogAPIProvider
LogBuffer jp.ne.dti.lares.foozy.ptlog.LogBuffer
LogTap jp.ne.dti.lares.foozy.ptlog.LogTap
LogType jp.ne.dti.lares.foozy.ptlog.LogType
PropertiesConverterConfig jp.ne.dti.lares.foozy.ptlog.PropertiesConverterConfig
ServiceProvider jp.ne.dti.lares.foozy.ptlog.ServiceProvider
TypeConverter jp.ne.dti.lares.foozy.ptlog.TypeConverter
UniversalFormatter jp.ne.dti.lares.foozy.ptlog.format.UniversalFormatter

Define new LogType

Custom LogType definition is very easy. Example of one derived from InfoLogType is shown below.


public class SQLInfoLogType
    extends InfoLogType
{
    // use below for resource efficiency
    final static
    public SQLInfoLogType INSTANCE = new SQLInfoLogType();

    public SQLInfoLogType(){
        super();
    }
}

New LogType

Extend Log/LogTap

Now, you can request logging with your custom type as shown below, even though it is not so simple.


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

        log.info("log with Info type");

        log.log(SQLInfoLogType.INSTANCE,
                "log with SQLInfo type");
    }

Request via bare method invocation

Log customization shown below will decrease such complexity.


public class CustomLog
    extends Log
{
    ....

    final
    public void sqlInfo(Object data){
        log(SQLInfoLogType.INSTANCE,
            data);
    }

    final
    public void sqlInfo(String message,
                        Throwable throwable)
    {
        log(SQLInfoLogType.INSTANCE,
            message, 
            throwable);
    }

    final
    public LogBuffer forSQLInfo(){
        // use default formatter
        return getLogBuffer(SQLInfoLogType.INSTANCE);
    }

    final
    public LogBuffer forSQLInfo(UniversalFormatter formatter){
        return getLogBuffer(SQLInfoLogType.INSTANCE,
                            formatter);
    }

    final
    public boolean enablesSQLInfo(){
        return enables(SQLInfoLogType.INSTANCE);
    }

    ....
}

Extend Log for custom type

You should also customize LogTap to get your custom Log directly from tap.


public class CustomTap
    extends LogTap
{
    ....

    final
    public CustomLog getCustomLog(String method){
        return new CustomLog(getContext(),
                             method,
                             getFormatter());
    }

    final
    public CustomLog getCustomLog(String method,
                                  UniversalFormatter formatter)
    {
        return new CustomLog(getContext(),
                             method,
                             formatter);
    }

    ....
}

Extend LogTap for CustomLog

Now, you can request logging with custom type as shown below.


    public void doSomething(){
        CustomLog log = TAP.getCustomLog("doSomething");

        log.sqlInfo("log with SQLInfo type");
    }

    ....

    final static
    public CustomTap TAP = new CustomTap(Client.class);

Request via convenient method

Configure type conversion

You can already write client code to request logging with custom type, but not yet configure logging type. For example, your SQLInfoLogType is treated as InfoLogType, and causes logging as same "level" as other classes derived from InfoLogType.

PTLog provides the mechanism to configure conversion from LogType to underlying logging framework specific object. Such mechanism is provided at ServiceProvider class, which is base class of LogAPIProvider and so on.

This section explains the easiest way, which configures ServiceProvider by writing "*.properties" file.

NOTE: Please see API document of ServiceProvider and TypeConverter for detail about type conversion.

At first, you should determine underlying logging framework. In this section, it is assumed that JDK Logging API is choosen.

Then, please write "*.properties" file as shown below.


## this specifies alias name of converter factory class.
## you can specify plural aliases.
##
##   KEY SYNTAX: ptlog.typeConverter.alias.AnyLabel
## VALUE SYNTAX: AliasName | FactoryClassFQN
##
ptlog.typeConverter.alias. = \
    level|jp.ne.dti.lares.foozy.ptlog.logapi.LevelTypeConverterFactory

## these specify conversion configuration.
##
##   KEY SYNTAX: ptlog.typeConverter.component.AnyLabel
## VALUE SYNTAX: AliasName | LogTypeFQN, Level, Label[, BundleName]
##
ptlog.typeConverter.component.01 = \
    level|your.package.SQLInfoLogType,800,SQLInfo
ptlog.typeConverter.component.02 = \
    level|your.package.NetworkInfoLogType,799,NetworkInfo
ptlog.typeConverter.component.03 = \
    level|your.package.LogicInfoLogType,800,LogicInfo
    ....

Type conversion configuration

LevelTypeConverterFactory is the factory class which create Level of JDK Logging API from parameters shown below:

  1. fully qualified class name derived from LogType
  2. digit value as "level"
  3. label string
  4. name in resource bundle(optional)

So, when configuration of JDK Logging API passes logging request with INFO(= has level value 800) or higher, configuration shown above causes that logging requests with NetworkInfoLogType are discarded, even thoug SQLInfoLogType and LogicInfoLogType are passed.

NOTE: Please refer API document about the factory classes because difference between each undrelying logging frameowrk is difference between parameter specification of factory classes.

Package descriptions for each logging frameworks, which are already supported by PTLog, point the factory class for appropriate type conversion.

Now, you can configure type conversion by invocation as shown below.


PropertiesConverterConfig configure =
PropertiesConverterConfig.DISALLOW_FAILURE;
// means that invalid configuration causes exception throwing

configure.add(LogAPIProvider.INSTANCE, filename);
// means that configurations in "filename" are added to
// plugging point for JDK Logging API

Load type conversion configuration

PropertiesConverterConfig has some other signature variations of "add()" method. Please see API document for detail.