com.tomgibara.pronto.logging
Class LoggingConfig

java.lang.Object
  com.tomgibara.pronto.logging.LoggingConfig

Direct Known Subclasses:

LoggingConfigImpl

public abstract class LoggingConfig
extends java.lang.Object

This class provides the basis for the convenient reconfiguration of Java's java.util.logging framework. A single instance of the class's default implementation is available via the getInstance method, through which the object's policy can configuration can be set. In addition, the class provides the functionality to force a reconfiguration at any time.

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
 

Because the logging configuration is layered atop the java.util.logging package it inherits all of its deficiencies: no per-logger handler configuration and no dynamic adjustment of logger handlers to name just two.

Constructor Summary

LoggingConfig()

Method Summary

static LoggingConfig	getInstance() Should be called to obtain a LoggingConfig instance.
abstract LoggingPolicy	getPolicy() The policy currently in use by this object.
abstract com.tomgibara.pronto.config.ConfigSource	getSource() The current source of configuration properties.
abstract void	setPolicy(LoggingPolicy policy) Sets the policy for this object.
abstract void	setSource(com.tomgibara.pronto.config.ConfigSource source) Sets the source of configuration properties for this object.
abstract void	update() Causes the logging to be reconfigured immediately with the properties from the current configuration source.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LoggingConfig

public LoggingConfig()

Method Detail

getInstance

public static LoggingConfig getInstance()
                                 throws com.tomgibara.pronto.core.ProntoException

Should be called to obtain a LoggingConfig instance. This method provides access to control logging configuration in the Pronto framework.

Returns:

the single instance of this class

Throws:

com.tomgibara.pronto.core.ProntoException - if the instance could not be created

setPolicy

public abstract void setPolicy(LoggingPolicy policy)

Sets the policy for this object. Policies control global aspects of the objects operation. If null is supplied, a default policy is used. Changes to a policy may be expected to take effect instantaneously.

Parameters:

policy - the policy to be used for this object, or null

getPolicy

public abstract LoggingPolicy getPolicy()

The policy currently in use by this object.

Returns:

the current policy, never null

setSource

public abstract void setSource(com.tomgibara.pronto.config.ConfigSource source)
                        throws ProntoLoggingException

Sets the source of configuration properties for this object. Until this method is called with a non-null source, this object will not perform any actions. Calling this method with a source will cause the logging to be immediately reconfigured, unless the source supplied is the same as the object's current source, or is null, in which case no action is performed.

Parameters:

source - the source of configuration information for the logging

Throws:

ProntoLoggingException - if reconfiguration of the logging failed

getSource

public abstract com.tomgibara.pronto.config.ConfigSource getSource()

The current source of configuration properties.

Returns:

the source of configuration for this object, may be null

update

public abstract void update()
                     throws ProntoLoggingException

Causes the logging to be reconfigured immediately with the properties from the current configuration source. If the source for this object is null, no action is taken. This method may be useful if an application needs to respond to requests for logging configuration directly instead of polling for them (the default behaviour of this class). Note that the rate of polling can be adjusted (or stopped) with this object's policy.

Throws:

ProntoLoggingException - if reconfiguration of the logging failed