Tutorial Objective

The objective of this tutorial is to general logging management within Metro. The Metro runtime recognizes two logging classes - the first is the defacto standard java.util.logging.Logger. The second is a pragmatic wrapper that presents a logging channel as an immutable service exposing a small number of logging functions.

Recognized Logger Classes

The following table summarises the two logging classes that are recognized by the Metro runtime platform as valid constructor arguments.

java.util.logging.Logger

This is the defacto logging implementation included within the Java Runtime. Generally speaking the Logger class provides everything you need although it leaves a lot of room for consolidation (hence the provision of an alternative).

net.dpml.logging.Logger

This is an interface that exposes a small set of query and execution operation concerning logging. The Logger class provides support for priority evaluation (logger.isXxxxEnabled) and priority-based log message generation (logger.info( ... ), etc.). The standard logging priorities supported by the interface include debug, info, warning, error, and trace. In addition to query and actionable operations, the Logger interface declares the getChildLogger( <name> ) method, enabling access to a logging channel that is a subsidiary of the assigned logging channel.

The DPML Logger

The DPML Logger interface exposes a set of operations that meet the requirements of a component implementation. More specifically - the DPML Logger interface does not expose operations dealing with channel management. A typical usage scenario is demonstrated in the following code fragment:

import net.dpml.logging.Logger;
        
public class Demo
{
    public Demo( final Logger logger )
    {
        if( logger.isTraceEnabled() )
        {
            logger.trace( "commencing instantiation cycle" );
        }
        if( logger.isInfoEnabled() )
        {
            logger.info( "Hello." );
        }
        if( logger.isDebugEnabled() )
        {
            logger.debug( "instantiation complete." );
        }
    }
}
        

The following table summarises the mapping of priorities in the DPML Logger with priority values used in the java.util.logging framework:

	Java	Recommended Usage
TRACE	FINER	Low-level developer debugging.
DEBUG	FINE	Debug information that summarises implementation activity.
INFO	INFO	Significant application events.
WARN	WARNING	Notification of potential issues.
ERROR	SEVERE	Notification of an error condition.

Testcase Logging Configuration

The Junit test tasks which is automatically executed if a src/test directory is present will check for the presence of a file named etc/data/logging.properties and if present - that file will be used as the logging configuration for the test task phase. The following configuration file sets the default logging priority level to INFO and overrides logging channel priority for the demo component with a FINE priority.

.level=INFO
demo.level=FINE

Testcase output with the above configuration is shown below:

test:
    [junit] Created dir: C:\dev\osm\trunk\tutorial\components\logging\target\reports\test
    [junit] Executing forked test.
    [junit] Running org.acme.logging.LoggingDemoTestCase
    [junit] [90261] [FINE   ] (demo): established per-thread lifestyle handler for [org.acme.logging.Demo]
    [junit] [90261] [INFO   ] (demo): Hello!
    [junit] [90261] [FINE   ] (demo): instantiation complete
    [junit] [90261] [FINE   ] (demo): instantiated [32820206]
    [junit] [90261] [FINE   ] (demo): activated [32820206]
    [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.75 sec

Summary

Irrespect of the logging constructor type you choose, in both cases the underlying log channel management is based on the management utilities provided withing the java.util.logging package. In particular, this means that the logging configuration (channel priority, channel targets, etc. may be changed at runtime by an independent management application.