Pronto Logging

Pronto provides a small logging module that is intended to make the dynamic configuration of logging levels simpler and more flexible. It uses the configuration module to provide an api that can collate logging configuration from multiple and varied sources (including system-properties, files, url connections and Maps). In addition to this, the api also allows abbreviations to be defined within logging property files. These can make complicated logging configurations easier to read.

The classes that comprise this api are located in the com.tomgibara.pronto.logging package – full details of which are available in the Javadocs and associated Maven site.

Using the api

A singleton instance of the prime api class LoggingConfig is available via the static method LoggingConfig.getInstance().

The functionality that this class provides is configured through two different objects, a policy (that controls its global operation) and a source (that provides the logging settings), both of which are described below. Both the policy and the source can be set at any time; a LoggingConfig instance is guaranteed to be completely safe for concurrent use.

In general the LoggingConfig operates by polling (as per the policy) for changes in the logging configuration (provided by the source). In some instances, applications may want to force an immediate update of the logging configuration. To support this an update() method is also exposed.

Logging Policies

A logging policy controls the global operation of the logging configurator. It currently has two responsibilities (see the Javadocs for more details):

1. defining the time between successive checks for changes in the logging configuration (returning a null value disables polling).
2. distinguishing a genuine change in logging property timestamps (a technical – but potentially important – distinction for which the default implementation will be sufficient in almost all cases).

Supplying a policy is optional; a default policy is used if no policy is specified – to adapt the default policy extend (or delegate to) the DefaultLoggingPolicy class provided. Note that, in keeping with philosophy adpoted for Pronto configuration, the values returned by a policy do not need to be stable. For example, the duration returned by the policy can vary on each request.

Configuration Sources

The actual logging properties are provided a single ConfigSource. Multiple sources can be combined using the CompositeConfigSource class. Absence of a source (because no source has been set on the LoggingConfig object, or because a null source has been set) naturally prevents log reconfiguration from occuring. Whenever a new source is provided, an update of the logging configuration is automatically performed.

The logging properties supplied by the source (with the exception of the abbreviations defined below) are expected to be consistent with those specified by the java.util.logging package.

Naturally, because this module only provides a layer of convenience over the standard Java logging functionality, it is subject to the same shortcomings. These include: no per-logger handler configuration, no dynamic adjustment of logger handlers, draconian class loading restrictions etc.

Logging abbreviations

The properties provided by the configuration are entirely compatible with those detailed in the documentation for the Java logging framework. However, class does provide some convenient extra behaviour. It allows packages, handler class-names, formatter class-names and filter class-names to be abbreviated:

• Property names begining with $package are taken to define a package abbreviation. These abbreviations are only expanded where they occur at the start of a logging-property key.
• Property names begining with $handler are taken to define a handler abbreviation. These abbreviations are only expanded where they occur in a ".handlers" property value.
• Property names begining with $formatter are taken to define a formatter abbreviation. These abbreviations are only expanded where they occur in a ".formatter" property value.
• Property names begining with filter are taken to define a filter abbreviation. These abbreviations are only expanded where they occur in a ".filter" property value.

For example, the following logging configuration extract:

$package.app = com.sample.app
$handler.simple = app.SimpleHandler
$formatter.db = app.JDBCFormatter
app.SimpleHandler.formatter = db
app.level = INFO
app.package.level = FINE
app.package.handler = simple

Is equivalent to:

com.sample.app.SimpleHandler.formatter = com.sample.app.JDBCFormatter
com.sample.app.level = INFO
com.sample.app.package.level = FINE
com.sample.app.package.handler = simple

The implementation specifies a small number of default definitions that serve to standardize the names of built-in logging classes, they are currently:

$handler.console=java.util.logging.ConsoleHandler
$handler.file=java.util.logging.FileHandler
$handler.socket=java.util.logging.SocketHandler