de.unkrig.commons.util.logging

Class SimpleLogging

java.lang.Object

de.unkrig.commons.util.logging.SimpleLogging

public final class SimpleLogging
extends java.lang.Object

A utility class that simplifies the usage of Java™'s java.util.logging facility.

Typically, you simply call

SimpleLogging.init();

as soon as possible when your Java program starts (perhaps from a static initializer of your main class).

Later, at any possible point of time, you'd optionally call one of the following:

setQuiet()	Suppress LOGGER.info() messages
setNoWarn()	Suppress LOGGER.info() and LOGGER.warning() messages
setNormal()	(Resets SimpleLogging to ist default behavior.)
setVerbose()	Also print LOGGER.config() messages to STDOUT
setDebug()	Also print LOGGER.fine() messages to STDERR*
setDebug() setDebug()	Also print LOGGER.finer() messages to STDERR*
setDebug() setDebug() setDebug()	Also print LOGGER.finest() messages to STDERR*

^* These messages are printed with source class name, source method name, exception (if any) and stack trace.

Alternatively, you can call setLevel(Level) with a respective level parameter.

Alternatively, you may want to call configureLoggers(String) to configure log levels, handlers and formats for individual loggers. For example,

SimpleLogging.configureLoggers("FINEST:com.acme:FileHandler(\"foo.txt\"):java.util.logging.XMLFormatter");

activates full debugging for logger "com.acme" and its children (e.g. "com.acme.foo"), and writes to the file "foo.txt" in XML format.

Method Summary

Modifier and Type	Method and Description
static void	configureLoggers(java.lang.String spec) Sets the level of the named loggers, adds the given handler on them and sets the given formatter on the handler.
static java.util.logging.Level	getLevel()
static void	init() Sets up the default configuration.
static void	setDebug() Shorthand for setLevel(FINE).
static void	setFormatter(java.util.logging.Formatter formatter) Sets the formatter for all three handlers (debug, out and stderr).
static void	setFormatter(java.lang.String spec) Sets the formatter for all three handlers (debug, out and stderr).
static void	setLevel(java.util.logging.Level level) Configures the logging of a command-line utility as usual.
static void	setNormal() Shorthand for setLevel(Level.INFO): Messages of level INFO, i.e.
static void	setNoWarn() Shorthand for setLevel(Level.WARNING + 1): Messages of levels INFO and WARNING are suppressed.
static void	setOut(java.io.File value) Sets a Handler which writes messages of levels INFO (inclusive) through WARNING (exclusive) to the given File.
static void	setOut(java.util.logging.Handler handler) Sets the given Handler for messages of levels INFO (inclusive) through WARNING (exclusive).
static void	setQuiet() Shorthand for setLevel(Level.INFO + 1): Messages of level Level.INFO, i.e.
static void	setStdout() Installs a Handler which writes messages of levels INFO (inclusive) through WARNING (exclusive) to STDOUT.
static void	setVerbose() Shorthand for setLevel(Level.CONFIG): Messages of level CONFIG, i.e.

Methods inherited from class java.lang.Object

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

Method Detail

init

public static void init()

Sets up the default configuration.

• Messages with levels >= WARNING are printed to STDERR.
• Messages with levels INFO are printed to STDOUT.
• Messages with levels <= CONFIG are not printed.

setLevel

public static void setLevel(java.util.logging.Level level)

Configures the logging of a command-line utility as usual.

Typical command line option	level	Levels logged to STDERR	Levels logged to STDOUT
-nowarn	SEVERE	SEVERE	-
-quiet	WARNING	SEVERE, WARNING	-
(none)	INFO	SEVERE, WARNING	INFO
-verbose	CONFIG	SEVERE, WARNING	INFO, CONFIG
-debug	FINEST	SEVERE, WARNING FINE, FINER, FINEST*	INFO, CONFIG

^*: FINE, FINER and FINEST log records are printed with class, method, source and line number

getLevel

public static java.util.logging.Level getLevel()

Returns:

The currently configured level for the root logger

See Also:

setLevel(Level)

setFormatter

public static void setFormatter(java.lang.String spec)
                         throws ParseException,
                                EvaluationException

Sets the formatter for all three handlers (debug, out and stderr).

Parameters:

spec - The expression to parse and to evaluate

Throws:

ParseException

EvaluationException

See Also:

The expression syntax

setFormatter

public static void setFormatter(java.util.logging.Formatter formatter)

Sets the formatter for all three handlers (debug, out and stderr).

setNoWarn

public static void setNoWarn()

Shorthand for setLevel(Level.WARNING + 1): Messages of levels INFO and WARNING are suppressed.

setQuiet

public static void setQuiet()

Shorthand for setLevel(Level.INFO + 1): Messages of level Level.INFO, i.e. 'normal output' are suppressed.

setNormal

public static void setNormal()

Shorthand for setLevel(Level.INFO): Messages of level INFO, i.e. 'normal output' and above (WARNING and SEVERE) are logged.

setVerbose

public static void setVerbose()

Shorthand for setLevel(Level.CONFIG): Messages of level CONFIG, i.e. 'verbose output' are logged.

setDebug

public static void setDebug()

Shorthand for setLevel(FINE). All messages down to level FINE are logged.

Calling this method multiply lowers the level to Level.FINER and then Level.FINEST.

setStdout

public static void setStdout()

Installs a Handler which writes messages of levels INFO (inclusive) through WARNING (exclusive) to STDOUT.

setOut

public static void setOut(java.io.File value)
                   throws java.io.IOException

Sets a Handler which writes messages of levels INFO (inclusive) through WARNING (exclusive) to the given File.

Throws:

java.io.IOException

setOut

public static void setOut(@Nullable
                          java.util.logging.Handler handler)

Sets the given Handler for messages of levels INFO (inclusive) through WARNING (exclusive).

Clients may want to use this method to redirect their "normal" output (not the errors, warnings and debug output) elsewhere, e.g. into an "output file".

Parameters:

handler - null to reset to the 'normal' behavior (print to STDOUT)

configureLoggers

public static void configureLoggers(java.lang.String spec)

Sets the level of the named loggers, adds the given handler on them and sets the given formatter on the handler.

The spec is parsed as follows:

 spec := [ level ] [ ':' [ logger-names ] [ ':' [ handler ] [ ':' [ formatter ] [ ':' use-parent-handlers ] ] ] ]
 logger-names := logger-name [ ',' logger-name ]...
 

The level component determines the log level of the handler, or, iff no handler is given, the level of the loggers. It must be parsable by Level.parse(String), i.e. it must be a decimal number, or one of SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL.

The handler and formatter components denote expressions, with the automatically imported packages "java.util.logging", "de.unkrig.commons.util.logging.handler" and "de.unkrig.commons.util.logging.formatter". Notice that neither expression may contain colons.

Example spec:

 FINE:de.unkrig:ConsoleHandler:FormatFormatter("%5$tF %5$tT.%5$tL %10$-20s %3$2d %8$s%9$s%n")
 

If any of the components of the spec is missing or empty, a reasonable default value is assumed:

level

Logger: Level inherited from parent logger
Handler: Handler's default log level, typically ALL

loggers

The root logger

handler

StdoutHandler

formatter

MESSAGE_AND_EXCEPTION

use-parent-handlers

true

It is recommended that command line tools call this method from their main(String[]) method, on each occurrence of a "-log spec" command line option.

See Also:

The expression syntax of the handler and the formatter components