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'd always call

SimpleLogging.init();

first and create a Logger in each of your classes:

private static final Logger LOGGER = Logger.getLogger(ThisClass.class.getName());

Then, instead of System.out.println() and System.err.println(), you'd use:

 LOGGER.info("Previously: System.out.println()");
 LOGGER.warning("Previously: System.err.println()");
 LOGGER.severe("Previously: System.err.println()");
 

At start-up of your application, right after calling init(), 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.

Additionally, 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

static void	configureLoggers(java.lang.String spec) Reduces the level of the given loggers to the given level, adds the given handler to the logger and sets the given formatter on the handler.
static java.util.logging.Level	getLevel()
static void	init() Set up the default configuration: Messages with levels >= WARNING are printed to STDERR: Logger.warning(String) and Logger.severe(String) are the replacements for System.out.println() Messages with levels INFO are printed to STDOUT: Logger.info(String) is the replacement for System.out.println() Messages with levels <= CONFIG are not printed
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 levels 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()

Set up the default configuration:

• Messages with levels >= WARNING are printed to STDERR: Logger.warning(String) and Logger.severe(String) are the replacements for System.out.println()
• Messages with levels INFO are printed to STDOUT: Logger.info(String) is the replacement for System.out.println()
• 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 java.lang.Exception

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

Parameters:

spec - An expression as defined for ExpressionEvaluator.evaluateTo(String, de.unkrig.commons.lang.protocol.Mapping, Class)

Throws:

EvaluationException - The expression evaluates to null

EvaluationException - The value is not assignable to T

ParseException

java.lang.Exception

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 levels 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)

Reduces the level of the given loggers to the given level, adds the given handler to the logger and sets the given formatter on the handler.

The spec is parsed as follows:

 spec := [ level ] [ ':' [ loggers ] [ ':' [ handler ] [ ':' [ formatter ] ] ] ]
 loggers := logger [ ',' logger ]...
 

If any of the components of spec is missing or non-empty, a reasonable default value is assumed. E.g. a spec of

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

overrides all the other arguments.

The 'level' component 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 class names, where 'java.util.logging.' and 'de.unkrig.commons.util.logging.' is automatically prepended. If an 'formatter-argument' is given, then the formatter must have a on-string-parameter constructor (like PrintfFormatter).

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

Component	Default value
Level	none
Loggers	The root logger
Handler	Stdout
Formatter	MESSAGE_AND_EXCEPTION

It is recommended that command line tools call this method from their main method, on each occurrence of a '-log <spec>' command line option.