DPML Metro Logging

Logging Channels

The effectivness of logging information is directly related to category naming and utilization of priorities. The Metro system encorages the usage of logging hierachies constructed relative to component names (as opposed to static category names). For example, a top level component named "server" may have child component named "demo" and "hello" - the logging channel assigned to the server will have the logging category name "server" and the respective child components will be assigned logging channels with the names "service.hello" and "server.demo". Implemeting this approach requires that logging channels are supplied to a component (or more specifically - components should not create their own top-level or statically named logging channels).

The following sample code demonstrates the appraoch to logging channel delivery - the component declares a logging channel as one of possibly multiple constructor argument and the container an appropriately configured channel.

import java.util.logging.Logger;
import java.util.logging.Level;

public class Widget
{
    public Widget( final Logger logger )
    {
        if( logger.isLoggable( Level.INFO ) )
        {
            logger.info( "Hello!" );
        }
    }
}

Supported Logging Classes

During deployment the metro runtime will evaluate constructor parameters. If an parameter class is equal any of the following log channel classes, an appropriate instance will be provided by the container with a category name corresponding to the component fully-qualified path:

java.util.logging.Logger
net.dpml.util.Logger

DPML Logger convinience class

The net.dpml.util.Logger class is a convinience class that simply wraps an underlying java.util.logging.Logger instance. It provides support for log-level testing (e.g. logger.isDebugEnabled(), level oriented log emitter operations (e.g. logger.debug( "..." )), and the creation of new subsidiary logging channels. More importantly, the class does not expose any operations dealing with channel priority, naming, or other associated management operations (as these are concerns that should not be exposed to individual components).

The following code sample demonstrates a component using the DPML Logger.

import net.dpml.util.Logger;

public class Widget
{
    public Widget( final Logger logger )
    {
        if( logger.isInfoEnabled() )
        {
            logger.info( "Hello!" );
        }
    }
}

The following table summarises the logging priority names used in the DPML Logger and their mapping to the underlying Java Logger priorities.

DPML Level	Java Logger Level	Recommended Usage
ERROR	SEVERE	Notification of a error.
WARNING	WARNING	Notification of a non-critical warning.
INFO	INFO	Notification of significant application event.
DEBUG	FINE	Notification of internal event.
TRACE	FINER	Fine-grain notification of an internal event.