org.geotools.util.logging

Class Logging

Object

Logging

public final class Logging
extends Object

Utility class for configuring logging in GeoTools. All GeoTools code should fetch their logger through a call to getLogger(String), not java util logging Logger.getLogger(String). This is necessary in order to give GeoTools a chance to redirect log events to other logging frameworks, for example LOG4J, or commons-logging.

Example: In order to redirect every GeoTools log events to commons-logging, invoke the following once at application startup:

 Logging.GEOTOOLS.setLoggerFactory}("org.geotools.util.logging.CommonsLoggerFactory");
 

Since:

2.4

Author:

Martin Desruisseaux

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Logging.LogLevel Custom logging level used for FATAL and OPERATION.

Field Summary

Fields

Modifier and Type	Field and Description
static Logging	ALL Logging configuration that apply to all packages.
static Level	FATAL The logging level for fatal error resulting in application shutdown.
static Logging	GEOTOOLS Logging configuration that apply only to GeoTools packages.
static Logging	JAI Logging configuration that apply only to javax.media.jai packages.
static Level	OPERATION The logging level for reporting coverage operations.

Method Summary

Modifier and Type	Method and Description
void	forceMonolineConsoleOutput() Configures the default console handler in order to log records on a single line instead of two lines.
void	forceMonolineConsoleOutput(Level level) Same as forceMonolineConsoleOutput(), but additionnaly set an optional logging level.
static Logger	getLogger(Class<?> classe) Returns a logger for the specified class.
static Logger	getLogger(String name) Returns a logger for the specified name.
LoggerFactory<?>	getLoggerFactory() Returns the logger factory, or null if none.
static Logging	getLogging(String name) Returns a Logging instance for the specified base logger.
String	lookupConfiguration() Checks the LoggerFactory.lookupConfiguration() information, or reports back on java.util.logging configuration if no factory is used.
static boolean	recoverableException(Class<?> classe, String method, Throwable error) Invoked when a recoverable error occurs.
static boolean	recoverableException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when a recoverable error occurs.
void	setLoggerFactory(LoggerFactory<?> factory) Sets a new logger factory for this Logging instance and every children.
void	setLoggerFactory(String className) Sets a new logger factory from a fully qualified class name.
String	toString()
static boolean	unexpectedException(Class<?> classe, String method, Throwable error) Invoked when an unexpected error occurs.
static boolean	unexpectedException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an unexpected error occurs.
static boolean	unexpectedException(Logger logger, Throwable error) Invoked when an unexpected error occurs.

Methods inherited from class Object

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

Field Detail

FATAL

public static final Level FATAL

The logging level for fatal error resulting in application shutdown. This level is equals or slightly higher than than Level.SEVERE.

OPERATION

public static final Level OPERATION

The logging level for reporting coverage operations. This level is equals or slightly lower than Level.INFO.

ALL

public static final Logging ALL

Logging configuration that apply to all packages.

NOTE: ALL must be created before any other static Logging constant.

GEOTOOLS

public static final Logging GEOTOOLS

Logging configuration that apply only to GeoTools packages.

JAI

public static final Logging JAI

Logging configuration that apply only to javax.media.jai packages.

Used by LoggingImagingListener to route errors reported from JAI framework.

Method Detail

getLogger

public static Logger getLogger(Class<?> classe)

Returns a logger for the specified class. This convenience method invokes getLogger(String) with the package name as the logger name.

Parameters:

classe - The class for which to obtain a logger.

Returns:

A logger for the specified class.

Since:

2.5

getLogger

public static Logger getLogger(String name)

Returns a logger for the specified name. If a logger factory has been set, then this method first ask to the factory. It gives GeoTools a chance to redirect logging events to commons-logging or some equivalent framework.

If no factory was found or if the factory choose to not redirect the loggings, then this method returns the usual Logger.getLogger(name).

Parameters:

name - The logger name.

Returns:

A logger for the specified name.

getLogging

public static Logging getLogging(String name)

Returns a Logging instance for the specified base logger. This instance is used for controlling logging configuration in GeoTools. For example methods like forceMonolineConsoleOutput() are invoked on a Logging instance.

Logging instances follow the same hierarchy than Logger, i.e. "org.geotools" is the parent of "org.geotools.referencing", "org.geotools.metadata", etc.

Parameters:

name - The base logger name.

getLoggerFactory

public LoggerFactory<?> getLoggerFactory()

Returns the logger factory, or null if none. This method returns the logger set by the last call to setLoggerFactory(org.geotools.util.logging.LoggerFactory<?>) on this Logging instance or on one of its parent.

setLoggerFactory

public void setLoggerFactory(LoggerFactory<?> factory)

Sets a new logger factory for this Logging instance and every children. The specified factory will be used by getLogger(name) when name is this Logging name or one of its children.

setLoggerFactory

public void setLoggerFactory(String className)
                      throws ClassNotFoundException,
                             IllegalArgumentException

Sets a new logger factory from a fully qualified class name. This method should be preferred to setLoggerFactory(LoggerFactory) when the underlying logging framework is not guaranteed to be on the classpath.

Parameters:

className - The fully qualified factory class name.

Throws:

ClassNotFoundException - if the specified class was not found.

IllegalArgumentException - if the specified class is not a subclass of LoggerFactory, or if no public static getInstance() method has been found or can be executed.

forceMonolineConsoleOutput

public void forceMonolineConsoleOutput()

Configures the default console handler in order to log records on a single line instead of two lines. More specifically, for each ConsoleHandler using a SimpleFormatter, this method replaces the simple formatter by an instance of MonolineFormatter. If no ConsoleHandler are found, then a new one is created.

Note: this method may have no effect if the loggings are redirected to an other logging framework.

forceMonolineConsoleOutput

public void forceMonolineConsoleOutput(Level level)

Same as forceMonolineConsoleOutput(), but additionnaly set an optional logging level. If the specified level is non-null, then all Handlers using the monoline formatter will be set to the specified level.

Note: Avoid this method as much as possible, since it overrides user's level setting. A user trying to configure his logging properties may find confusing to see his setting ignored.

See Also:

GeoTools.init(org.geotools.util.factory.Hints)

lookupConfiguration

public String lookupConfiguration()

Checks the LoggerFactory.lookupConfiguration() information, or reports back on java.util.logging configuration if no factory is used.

The details returned are suitable for troubleshooting.

Returns:

logging configuration details.

unexpectedException

public static boolean unexpectedException(Logger logger,
                                          Throwable error)

Invoked when an unexpected error occurs. This method logs a message at the WARNING level to the specified logger. The originating class name and method name are inferred from the error stack trace, using the first stack trace element for which the class name is inside a package or sub-package of the logger name. For example if the logger name is "org.geotools.image", then this method will uses the first stack trace element where the fully qualified class name starts with "org.geotools.image" or "org.geotools.image.io", but not "org.geotools.imageio".

Parameters:

logger - Where to log the error.

error - The error that occured.

Returns:

true if the error has been logged, or false if the logger doesn't log anything at the WARNING level.

unexpectedException

public static boolean unexpectedException(Logger logger,
                                          Class<?> classe,
                                          String method,
                                          Throwable error)

Invoked when an unexpected error occurs. This method logs a message at the WARNING level to the specified logger. The originating class name and method name can optionnaly be specified. If any of them is null, then it will be inferred from the error stack trace as in unexpectedException(Logger, Throwable).

Explicit value for class and method names are sometime preferred to automatic inference for the following reasons:

• Automatic inference is not 100% reliable, since the Java Virtual Machine is free to omit stack frame in optimized code.

• When an exception occured in a private method used internally by a public method, we sometime want to log the warning for the public method instead, since the user is not expected to know anything about the existence of the private method. If a developper really want to know about the private method, the stack trace is still available anyway.

Parameters:

logger - Where to log the error.

classe - The class where the error occurred, or null.

method - The method where the error occurred, or null.

error - The error.

Returns:

true if the error has been logged, or false if the logger doesn't log anything at the WARNING level.

unexpectedException

public static boolean unexpectedException(Class<?> classe,
                                          String method,
                                          Throwable error)

Invoked when an unexpected error occurs. This method logs a message at the WARNING level to a logger inferred from the given class.

Parameters:

classe - The class where the error occurred.

method - The method where the error occurred, or null.

error - The error.

Returns:

true if the error has been logged, or false if the logger doesn't log anything at the WARNING level.

Since:

2.5

recoverableException

public static boolean recoverableException(Logger logger,
                                           Class<?> classe,
                                           String method,
                                           Throwable error)

Invoked when a recoverable error occurs. This method is similar to unexpectedException except that it doesn't log the stack trace and uses a lower logging level.

Parameters:

logger - Where to log the error.

classe - The class where the error occurred.

method - The method name where the error occurred.

error - The error.

Returns:

true if the error has been logged, or false if the logger doesn't log anything at the specified level.

Since:

2.5

recoverableException

public static boolean recoverableException(Class<?> classe,
                                           String method,
                                           Throwable error)

Invoked when a recoverable error occurs. This method is similar to unexpectedException except that it doesn't log the stack trace and uses a lower logging level.

Parameters:

classe - The class where the error occurred.

method - The method name where the error occurred.

error - The error.

Returns:

true if the error has been logged, or false if the logger doesn't log anything at the specified level.

Since:

2.5

toString

public String toString()

Overrides:

toString in class Object