Static
Logging
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Object
public final class Logging
A set of utilities method for configuring loggings in Geotk. Library implementors shall fetch
their logger using the getLogger(Class) static method provided in this class rather
than Logger.getLogger(String), in order to give Geotk a chance to redirect the logging
to an other framework like Commons-logging or
Log4J.
This method provides also a log(Class, String, LogRecord) convenience static method, which
set the logger name of the given record before to log it.
An other worthy static method is unexpectedException(Class, String, Throwable), for
reporting an anomalous but nevertheless non-fatal exception.
Configuration
The log records can be redirected explicitly to an other logging framework using the
following method call (replace LoggerFactory.COMMONS_LOGGING by
LoggerFactory.LOG4J or an other framework if desired):
Note however that the above method invocation is performed automatically if theLogging.GEOTOOLKIT.setLoggerFactory(LoggerFactory.COMMONS_LOGGING);
geotk-logging-commons.jar or the geotk-logging-log4j.jar file is
found on the classpath, so it usually doesn't need to be invoked explicitely.
See the scanLoggerFactory() method for more details on automatic logger
factory registration.
| utility/geotk-utility (download) | View source code for this class |
| Field Summary | |
|---|---|
static Logging |
ALL
Logging configuration that apply to all packages. |
static Logging |
GEOTOOLKIT
Logging configuration that apply only to org.geotoolkit packages. |
String |
name
The name of the base package. |
| Method Summary | |
|---|---|
void |
flush()
Flushes all handlers used by the logger named name. |
void |
forceMonolineConsoleOutput(Level level)
Configures the default console handler in order to log records on a single line instead of two lines. |
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. |
static void |
log(Class<?> classe,
LogRecord record)
Deprecated. Replaced by log(Class, String, LogRecord), because experience suggests
that letting the caller specifies himself the source class and method names is error prone. |
static void |
log(Class<?> classe,
String method,
LogRecord record)
Logs the given record to the logger associated to the given class. |
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 |
scanLoggerFactory()
Scans the classpath for logger factories. |
void |
setLoggerFactory(LoggerFactory<?> factory)
Sets a new logger factory for this Logging instance and every children. |
void |
setLoggerFactory(String className)
Deprecated. The META-INF/services mechanism should be sufficient. This method
will be removed in order to reduce the weight of the Geotk library. |
static boolean |
severeException(Logger logger,
Class<?> classe,
String method,
Throwable error)
Invoked when a severe error occurs. |
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, toString, wait, wait, wait |
| Field Detail |
|---|
public static final Logging ALL
public static final Logging GEOTOOLKIT
org.geotoolkit packages.
public final String name
| Method Detail |
|---|
public static void log(Class<?> classe,
String method,
LogRecord record)
getLogger(Class);
classe - The class for which to obtain a logger.method - The name of the method which is logging a record.record - The record to log.
@Deprecated
public static void log(Class<?> classe,
LogRecord record)
log(Class, String, LogRecord), because experience suggests
that letting the caller specifies himself the source class and method names is error prone.
getLogger(Class);Note:
This method does not set the source class name because LogRecord
can infer it automatically. However callers are encouraged to set the source class
and method names themselves for more reliability.
classe - The class for which to obtain a logger.record - The record to log.public static Logger getLogger(Class<?> classe)
getLogger(String) with the package name as the logger name.
classe - The class for which to obtain a logger.
public static Logger getLogger(String name)
If no factory was found or if the factory choose to not redirect the loggings, then this
method returns the usual Logger.getLogger(name).
name - The logger name.
public static Logging getLogging(String name)
Logging instance for the specified base logger. This instance is
used for controlling logging configuration in Geotk. For example methods like
forceMonolineConsoleOutput(java.util.logging.Level) are invoked on a Logging instance.
Logging instances follow the same hierarchy than Logger, i.e.
"org.geotoolkit" is the parent of "org.geotoolkit.referencing",
"org.geotoolkit.metadata", etc.
name - The base logger name.
public LoggerFactory<?> getLoggerFactory()
null if none. This method returns the logger set
by the last call to setLoggerFactory(org.geotoolkit.util.logging.LoggerFactory) on this Logging instance or on one
of its parent.
@Configuration public void setLoggerFactory(LoggerFactory<?> factory)
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.
If the factory is set to null (the default), then the standard Logging framework
will be used.
factory - The new logger factory, or null if none.
@Deprecated
@Configuration
public void setLoggerFactory(String className)
throws ClassNotFoundException,
IllegalArgumentException
META-INF/services mechanism should be sufficient. This method
will be removed in order to reduce the weight of the Geotk library.
setLoggerFactory(LoggerFactory) when the underlying logging
framework is not guaranteed to be on the classpath.
className - The fully qualified factory class name.
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.LoggerFactory.COMMONS_LOGGING,
LoggerFactory.LOG4J@Configuration public void scanLoggerFactory()
The first factory found on the classpath is given toMETA-INF/services/org.geotoolkit.util.logging.LoggerFactory
setLoggerFactory(String).
If it can't be used (for example because of missing dependency), then the second factory
is tried, etc. until an acceptable factory is found.
This method usually doesn't need to be invoked explicitly, since it is automatically
invoked on Logging class initialization. However developers may invoke it if
new LoggerFactorys are added later on the classpath of a running JVM.
@Configuration public void forceMonolineConsoleOutput(Level level)
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 than the standard Java one.In addition, this method can set the handler levels. If the level is non-null, then every
Handlers using the monoline formatter may be set to the specified level. Whatever
the given level is used or not depends on current configuration. The choice is based on
heuristic rules that may change in any future version. Developers are encouraged to avoid
non-null level except for debugging purpose, since a user trying to configure his logging
properties file may find confusing to see his setting ignored.
level - The desired logging level, or null to left it unchanged.Setuppublic void flush()
name.
If that logger uses parent handlers,
then those handlers will be flushed as well.
If the log records seem to be interleaved with the content of System.out
or System.err, invoking this method before to write to the standard streams
may help.
Handler.flush()
public static boolean unexpectedException(Logger logger,
Throwable error)
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.geotoolkit.image", then this method will uses
the first stack trace element where the fully qualified class name starts with
"org.geotoolkit.image" or "org.geotoolkit.image.io", but not
"org.geotoolkit.imageio".
logger - Where to log the error.error - The error that occurred.
true if the error has been logged, or false if the logger
doesn't log anything at the WARNING level.
public static boolean unexpectedException(Logger logger,
Class<?> classe,
String method,
Throwable error)
WARNING level to the specified logger. The originating
class name and method name can optionally 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 occurred 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 developer really want to know about the private method, the stack trace is still available anyway.
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.
true if the error has been logged, or false if the logger
doesn't log anything at the WARNING level.recoverableException(Logger, Class, String, Throwable),
severeException(Logger, Class, String, Throwable)
public static boolean unexpectedException(Class<?> classe,
String method,
Throwable error)
WARNING level to a logger inferred from the given class.
classe - The class where the error occurred.method - The method where the error occurred, or null.error - The error.
true if the error has been logged, or false if the logger
doesn't log anything at the WARNING level.recoverableException(Class, String, Throwable)
public static boolean recoverableException(Class<?> classe,
String method,
Throwable error)
unexpectedException
except that it doesn't log the stack trace and uses a lower logging level.
classe - The class where the error occurred.method - The method name where the error occurred.error - The error.
true if the error has been logged, or false if the logger
doesn't log anything at the FINE level.unexpectedException(Class, String, Throwable)
public static boolean recoverableException(Logger logger,
Class<?> classe,
String method,
Throwable error)
unexpectedException
except that it doesn't log the stack trace and uses a lower logging level.
logger - Where to log the error.classe - The class where the error occurred.method - The method name where the error occurred.error - The error.
true if the error has been logged, or false if the logger
doesn't log anything at the FINE level.unexpectedException(Logger, Class, String, Throwable),
severeException(Logger, Class, String, Throwable)
public static boolean severeException(Logger logger,
Class<?> classe,
String method,
Throwable error)
unexpectedException
except that it logs the message at the SEVERE level.
logger - Where to log the error.classe - The class where the error occurred.method - The method name where the error occurred.error - The error.
true if the error has been logged, or false if the logger
doesn't log anything at the SEVERE level.unexpectedException(Logger, Class, String, Throwable),
recoverableException(Logger, Class, String, Throwable)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||