de.fhg.igd.logging
Class LoggingConfiguration

java.lang.Object
  de.fhg.igd.logging.LoggingConfiguration

public class LoggingConfiguration

extends Object

This class allows easy maintenance and configuration of the logging framework at runtime. For this purpose, a set of convenience methods is being provided. Additionally, the main method supports a similar set of command line options. Detailed information is available via the help printout:

/:0> java de.fhg.igd.logging.LoggingConfiguration -help

On initialization, the current configuration will be read from a file whose name will be looked up in the Java system property de.fhg.igd.logging.config. If the system property is not defined or the specified destination file cannot be read, the initialization will look for the resource file de/fhg/igd/logging/logging.properties instead. In case both attempts (system property and system resource) fail, the default configuration will be loaded.

Within the logging configuration file the following properties are supported:

• logger=<logger>
  Defines the underlying logging mechanism to be used.
  See setLogger(java.lang.String) for the list of valid <logger> values and further information.
• interval=<interval>
  Defines the interval between anchor timestamp log entries.
  See setInterval(String) for the list of valid <interval> values and further information.
• <URL>,buffer=<buffer>
  Defines the size of the internal message buffer to be used for specific URLs.
  See setBuffer(String,String) for the list of valid <buffer> values and further information.
• [<name>],output=<URL>[{,<URL>}]
  Defines output destinations for specific packages.
  See addOutput(String,String) for further information.
• [<name>],loglevel=<loglevel>
  Defines the log level of specific packages.
  See setLogLevel(String,String) for the list of valid <loglevel> values and further information.

NOTICE:

• As an additional feature, the logging configuration supports dynamic substitution of system properties: For example, if the directory of an output file of a package foo.bar depends on the system property log.dir, the following line may be put into the configuration file:
  foo.bar,output=file:///${log.dir}/foobar.log
• Besides the definitions of RFC 1738, "socket" will be accepted as an additional protocol identifier for the URL of a TCP socket: e.g. socket://192.168.0.1:30000

Version:

"$Id: LoggingConfiguration.java 1913 2007-08-08 02:41:53Z jpeters $"

Author:

Matthias Pressfreund, Jan Peters

Field Summary

static String	CONFIG_FILE_PROPERTY The name of the system property that contains the path to the logging configuration file
static String	CONFIG_RESOURCE The name of the resource file that will be loaded instead of an undefined or missing logging configuration file
protected Set	configurationChangeListeners_ The storage for registered ConfigurationChangeListener objects
static String	CR The system dependent line separator
protected static LoggingConfiguration	instance_ The singleton instance
protected ConfigurationParameters	parameters_ The configuration parameters

Constructor Summary

private

LoggingConfiguration() Hidden construction.

Method Summary

void	addConfigurationChangeListener(ConfigurationChangeListener listener) Register for configuration change notifications
boolean	addOutput(String name, String output) Add an output destination URL.
boolean	addOutput(String name, URL output)
void	apply(ConfigurationParameters parameters) Apply the given configuration by trying to minimize changes in order to keep alive as many output connections as possible.
static LoggingConfiguration	atPresent() Get the current configuration.
protected static void	checkOutput(URL output) Check the given output destination URL by trying to establish a connection and closing the stream right after.
protected String	findBestName(String target)
private void	fireBufferChanged(URL url, Integer oldval, Integer newval) Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.bufferChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.
private void	fireIntervalChanged(Long oldval, Long newval) Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.intervalChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.
private void	fireLoggerChanged(String oldval, String newval) Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.loggerChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.
private void	fireLogLevelChanged(String name, LogLevel oldval, LogLevel newval) Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.logLevelChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.
private void	fireOutputChanged(String name, Object oldval, Object newval) Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.outputChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.
Integer	getBuffer(URL output) Get the buffer value of an output destination URL.
Long	getInterval() Get the current interval value.
String	getLogger() Get the current logger property value.
ConfigurationParameters.BestMatch	getLogLevel(String name) Get the log level of a logger by its package name.
ConfigurationParameters.BestMatch	getOutput(String name) Get all output URLs for the specified name.
void	help() Print out some information about available command line options.
protected void	init() Initialize the current configuration by first trying to read the logging configuration file defined in the system property.
String	list(String name) Get a printout of all properties for a specific class/package name.
void	load(InputStream is) Reinitialize the current configuration from a stream.
void	load(String file) Reinitialize the current configuration from a file.
static void	main(String[] args) Provides a CommandLineInterface which publishes almost all public methods.
void	reinit()
void	removeConfigurationChangeListener(ConfigurationChangeListener listener) Deregister from configuration change notifications
boolean	removeOutput(String name) Remove all output destinations of the given name.
boolean	removeOutput(String name, String output) Remove an output destination.
boolean	removeOutput(String name, URL output)
void	save(OutputStream os) Write the current configuration to a stream.
void	save(String file) Write the current configuration to a file.
boolean	setBuffer(String output, String buffer) Set the buffer property for a specific output destination.
boolean	setBuffer(URL output, Integer buffer)
boolean	setInterval(Long interval)
boolean	setInterval(String interval) Change the interval property.
boolean	setLogger(String logger) Change the logger property.
boolean	setLogLevel(String name, LogLevel loglevel)
boolean	setLogLevel(String name, String loglevel) Set the loglevel property of a specific class/package name.
boolean	unsetBuffer(String output) Unset the buffer property of a specific output destination.
boolean	unsetBuffer(URL output)
boolean	unsetLogLevel(String name) Unset the loglevel property of a specific class/package name.

Methods inherited from class java.lang.Object

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

Field Detail

CONFIG_FILE_PROPERTY

public static final String CONFIG_FILE_PROPERTY

The name of the system property that contains the path to the logging configuration file

See Also:

Constant Field Values

CONFIG_RESOURCE

public static final String CONFIG_RESOURCE

The name of the resource file that will be loaded instead of an undefined or missing logging configuration file

See Also:

Constant Field Values

CR

public static final String CR

The system dependent line separator

configurationChangeListeners_

protected Set configurationChangeListeners_

The storage for registered ConfigurationChangeListener objects

parameters_

protected ConfigurationParameters parameters_

The configuration parameters

instance_

protected static LoggingConfiguration instance_

The singleton instance

Constructor Detail

LoggingConfiguration

private LoggingConfiguration()

Hidden construction.

Method Detail

init

protected void init()

Initialize the current configuration by first trying to read the logging configuration file defined in the system property. If the system property is not defined or loading the configuration fails, try to read the resource file. In case initialization even with the system resource file fails, load the default configuration.

atPresent

public static LoggingConfiguration atPresent()

Get the current configuration.

Returns:

The current configuration instance

load

public void load(String file)

Reinitialize the current configuration from a file.

Parameters:

file - The file to load the logging configuration from

Throws:

IllegalArgumentException - if the file name is null or empty

LoggingException - if initializing the configuration failed

load

public void load(InputStream is)

Reinitialize the current configuration from a stream.

Parameters:

is - The stream to load the logging configuration from

Throws:

IllegalArgumentException - if the argument is null

LoggingException - if initializing the configuration failed

save

public void save(String file)

Write the current configuration to a file.

Parameters:

file - The target logging configuration file

Throws:

IllegalArgumentException - if the argument is null or empty

LoggingException - in case the logging configuration file could not be written

save

public void save(OutputStream os)

Write the current configuration to a stream.

Parameters:

os - The target stream

Throws:

IllegalArgumentException - if the argument is null

apply

public void apply(ConfigurationParameters parameters)

Apply the given configuration by trying to minimize changes in order to keep alive as many output connections as possible.

Parameters:

parameters - The new configuration parameters

Throws:

IllegalArgumentException - if the argument is null

reinit

public void reinit()

See Also:

init()

setLogger

public boolean setLogger(String logger)

Change the logger property. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

logger - The new logger value (as to be used in the logging configuration file), which might be as follows:

• auto
• sun
• log4j

If set to auto, the logging mechanism with the highest priority will be chosen automatically. Priorities are as follows:

1. sun
2. log4j

Default value is: auto

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

Throws:

IllegalArgumentException - if the argument is null

LoggingException - in case the requested property value could not be changed

getLogger

public String getLogger()

Get the current logger property value.

Returns:

The logger property value

setInterval

public boolean setInterval(String interval)

Change the interval property. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

interval - The new interval value (as to be used in the logging configuration file), which might be as follows:

• off
• <millis>
  (number of millseconds)
• <secs>s
  (number of seconds, e.g. 5s)
• <mins>m
  (number of minutes, e.g. 10m)
• <hrs>h
  (number of hours, e.g. 2.5h)
• <days>d
  (number of days, e.g. 2d)

If set to 0 (zero) or off, no periodic anchor timestamps, but instead, the full timestamp will be written into every log entry. Default value is: off

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

setInterval

public boolean setInterval(Long interval)

Throws:

IllegalArgumentException - if the argument is null or less than zero

See Also:

setInterval(String)

getInterval

public Long getInterval()

Get the current interval value.

Returns:

The current interval value

setBuffer

public boolean setBuffer(String output,
                         String buffer)

Set the buffer property for a specific output destination. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

output - The output destination URL to set the buffer for

buffer - The new buffer property value (as to be used in the logging configuration file), which might be as follows:

• off
• <msgs>
  (number of messages)
• <msgs/k>k
  (number of thousands of messages; e.g. 2.5k corresponds to 2,500 messages)
• <msgs/M>m
  (number of millions of messages; e.g. 1.5m corresponds to 1,500,000 messages)

According to the buffer size, logging will be carried out either synchronously or asynchronously. For synchronous dispatching, the buffer size needs to be 0 (zero) or off. Buffer sizes other than off or greater than zero will implicitly activate the Asynchronous Message Dispatcher. If there is no buffer size defined for a specific URL, the default (which depends on the protocol identifier) will be used:

• for files: off (synchronous dispatching)
• otherwise: 10k (asynchronous dispatching)

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

setBuffer

public boolean setBuffer(URL output,
                         Integer buffer)

Throws:

IllegalArgumentException - if any argument is null or the buffer size is less than zero

LoggingException - in case the requested property value could not be set

See Also:

setBuffer(String,String)

unsetBuffer

public boolean unsetBuffer(String output)

Unset the buffer property of a specific output destination. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

output - The output destination URL to unset the buffer for

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

unsetBuffer

public boolean unsetBuffer(URL output)

Throws:

IllegalArgumentException - if the argument is null

LoggingException - in case the requested property value could not be unset

See Also:

unsetBuffer(String)

getBuffer

public Integer getBuffer(URL output)

Get the buffer value of an output destination URL. In case there is no buffer value configured for the given URL, the default value (which depends on the protocol identifier) will be returned.

Parameters:

output - The corresponding URL

Returns:

The corresponding buffer value or the default value in case no buffer is defined for the given URL

addOutput

public boolean addOutput(String name,
                         String output)

Add an output destination URL. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

name - The class/package name to add the new output destination to

output - The new output destination URL To configure the root logger, simply omit the package name. The root logger always needs to be configured. If omitted, the default will be used. The default value is: file:///./default.log

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

addOutput

public boolean addOutput(String name,
                         URL output)

Throws:

IllegalArgumentException - if any argument is null

LoggingException - in case the requested property value could not be added

See Also:

addOutput(String,String)

removeOutput

public boolean removeOutput(String name,
                            String output)

Remove an output destination. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

name - The class/package name to remove the output destination from

output - The output destination URL to be removed

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

removeOutput

public boolean removeOutput(String name,
                            URL output)

Throws:

IllegalArgumentException - if any argument is null or on the attempt to remove the last output URL of the root entry

LoggingException - in case the requested property value could not be removed

See Also:

removeOutput(String,String)

removeOutput

public boolean removeOutput(String name)

Remove all output destinations of the given name.

Notice: In case an exception is thrown while trying to apply necessary property value changes, the previous configuration will not be restored.

Parameters:

name - The class/package name to remove all output destinations from

Returns:

true if all output destinations have been removed successfully, false if at least one output destination could not be removed

Throws:

IllegalArgumentException - if the argument is null

getOutput

public ConfigurationParameters.BestMatch getOutput(String name)

Get all output URLs for the specified name. If there are none defined for the given name, find the closest match.

Parameters:

name - The name to search the output URLs for

Returns:

The best matching name assigned to the corresponding Set of output destination URL objects

setLogLevel

public boolean setLogLevel(String name,
                           String loglevel)

Set the loglevel property of a specific class/package name. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

name - The class/package name to set the log level for

loglevel - The new loglevel value (as to be used in the logging configuration file), which might be as follows:

• ALL
• TRACE
• DEBUG
• INFO
• WARNING
• ERROR
• SEVERE
• FATAL
• OFF

To configure the root logger, simply omit the package name. The root logger always needs to be configured. If omitted, the default will be used. The default value is: ERROR

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

setLogLevel

public boolean setLogLevel(String name,
                           LogLevel loglevel)

Throws:

IllegalArgumentException - if any argument is null

LoggingException - in case the requested property value could not be set

See Also:

setLogLevel(String,String)

unsetLogLevel

public boolean unsetLogLevel(String name)

Unset the loglevel property of a specific class/package name. In case an exception is thrown while trying to apply the requested property value changes, the previous configuration will be restored.

Parameters:

name - The class/package name to unset the log level for

Returns:

true if the property value has been changed successfully, false if the property value did not need to be changed since it is already equal to the given value

Throws:

IllegalArgumentException - if the argument is null on the attempt to remove the root loglevel

LoggingException - in case the requested property value could not be unset

getLogLevel

public ConfigurationParameters.BestMatch getLogLevel(String name)

Get the log level of a logger by its package name. If there is none defined for the given name, find the closest match.

Parameters:

name - The name to search the log level for

Returns:

The best matching name assigned to the corresponding LogLevel object

list

public String list(String name)

Get a printout of all properties for a specific class/package name.

Parameters:

name - The class/package name to get the printout for

Returns:

The listed properties for the given name

findBestName

protected String findBestName(String target)

See Also:

ConfigurationParameters.findBestName(String)

checkOutput

protected static void checkOutput(URL output)

Check the given output destination URL by trying to establish a connection and closing the stream right after.

Parameters:

output - The output destination URL to test

Throws:

LoggingException - if establishing the connection failed

NullPointerException - if the output URL is null

help

public void help()

Print out some information about available command line options.

addConfigurationChangeListener

public void addConfigurationChangeListener(ConfigurationChangeListener listener)

Register for configuration change notifications

removeConfigurationChangeListener

public void removeConfigurationChangeListener(ConfigurationChangeListener listener)

Deregister from configuration change notifications

fireLoggerChanged

private void fireLoggerChanged(String oldval,
                               String newval)

Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.loggerChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.

Parameters:

oldval - The previous logger property value

newval - The new logger property value

fireIntervalChanged

private void fireIntervalChanged(Long oldval,
                                 Long newval)

Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.intervalChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.

Parameters:

oldval - The previous interval property value

newval - The new interval property value

fireBufferChanged

private void fireBufferChanged(URL url,
                               Integer oldval,
                               Integer newval)

Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.bufferChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.

Parameters:

url - The URL of the changed buffer value

oldval - The previous buffer property value

newval - The current buffer property value

fireOutputChanged

private void fireOutputChanged(String name,
                               Object oldval,
                               Object newval)

Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.outputChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.

Parameters:

name - The class/package name of the changed output destination URL

oldval - The previous output destination(s); in case a new URL (to be found in curval) has been added, or null if there were no output destinations defined yet, or a Set of previously assigned URLs for the given name; if a single URL, this one has been removed (possibly remaining destinations may be found in newval)

newval - The current output destination(s); in case an existing URL (to be found in preval) has been removed, or null if there are no output destinations defined anymore, or a Set of remaining URLs for the given name; if a single URL, this one has been added (previously existing destinations may be found in preval)

fireLogLevelChanged

private void fireLogLevelChanged(String name,
                                 LogLevel oldval,
                                 LogLevel newval)

Fire an appropriate ConfigurationChangeEvent to ConfigurationChangeListener.logLevelChanged(de.fhg.igd.logging.ConfigurationChangeEvent) of all registered listener objects.

Parameters:

name - The class/package name of the changed LogLevel

oldval - The previous loglevel property value of the given name

newval - The current loglevel property value of the given name

main

public static void main(String[] args)

Provides a CommandLineInterface which publishes almost all public methods. For more information just run

java LoggingConfiguration -help

Parameters:

args - The command line arguments