Package org.apache.sis.util.logging
Class Logging
java.lang.Object
org.apache.sis.util.Static
org.apache.sis.util.logging.Logging
A set of utilities method for configuring loggings in SIS.
This class provides also some convenience static methods, including:
log(Class, String, LogRecord)
for setting the logger name, source class name and source method name of the given record before to log it.unexpectedException(Logger, Class, String, Throwable)
for reporting an anomalous but nevertheless non-fatal exception.
- Since:
- 0.3
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
The threshold at whichunexpectedException(Logger, String, String, Throwable, Level)
shall set the throwable in theLogRecord
. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) static boolean
configurationException
(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an unexpected error occurred while configuring the system.static Logger
Returns a logger for the package of the specified class.static boolean
ignorableException
(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an ignorable error occurred.private static Logger
inferCaller
(Logger logger, String classe, String method, StackTraceElement[] trace, LogRecord record) Sets theLogRecord
source class and method names according values inferred from the given stack trace.private static boolean
Returnstrue
if the given stack trace element describes a method considered part of public API.static void
Logs the given record to the logger associated to the given class.static boolean
recoverableException
(Logger logger, Class<?> classe, String method, Throwable error) Invoked when a recoverable error occurred.static boolean
severeException
(Logger logger, Class<?> classe, String method, Throwable error) Invoked when a severe error occurred.static boolean
unexpectedException
(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an unexpected error occurred.private static boolean
Implementation ofunexpectedException(Logger, Class, String, Throwable)
.
-
Field Details
-
LEVEL_THRESHOLD_FOR_STACKTRACE
private static final int LEVEL_THRESHOLD_FOR_STACKTRACEThe threshold at whichunexpectedException(Logger, String, String, Throwable, Level)
shall set the throwable in theLogRecord
. For any record to be logged at a lowerLevel
, theLogRecord.setThrown(Throwable)
method will not be invoked.The default value is 600, which is the
invalid reference
PerformanceLevel#PERFORMANCE
Level.FINE
(500) andLevel.CONFIG
(700). Consequently, we will ignore the stack traces of recoverable failures, but will report stack traces that may impact performance, configuration, or correctness.- See Also:
-
-
Constructor Details
-
Logging
private Logging()Do not allow instantiation of this class.
-
-
Method Details
-
getLogger
Returns a logger for the package of the specified class. This convenience method invokesLogger.getLogger(String)
with the package name of the given class taken as the logger name.- Parameters:
source
- the class which will emit a logging message.- Returns:
- a logger for the specified class.
- Since:
- 1.0
-
log
Logs the given record to the logger associated to the given class. This convenience method performs the following steps:- Unconditionally set the source class name to the canonical name of the given class;
- Unconditionally set the source method name to the given value;
- Get the logger for the logger name if specified,
or for the
classe
package name otherwise; - Set the logger name of the given record, if not already set;
- Log the modified record.
- Parameters:
classe
- the class to report as the source of the logging message.method
- the method to report as the source of the logging message.record
- the record to log.
-
inferCaller
private static Logger inferCaller(Logger logger, String classe, String method, StackTraceElement[] trace, LogRecord record) Sets theLogRecord
source class and method names according values inferred from the given stack trace. This method inspects the given stack trace, skips what looks like internal API based on heuristic rules, then if some arguments are non-null tries to match them.- Parameters:
logger
- where the log record will be sent after this method call, ornull
if unknown.classe
- the name of the class to report in the log record, ornull
if unknown.method
- the name of the method to report in the log record, ornull
if unknown.trace
- the stack trace to use for inferring the class and method names.record
- the record where to set the class and method names.- Returns:
- the record to use for logging the record.
-
isPublic
Returnstrue
if the given stack trace element describes a method considered part of public API. This method is invoked in order to infer the class and method names to declare in aLogRecord
. We do not document this feature in public Javadoc because it is based on heuristic rules that may change.The current implementation compares the class name against a hard-coded list of classes to hide. This implementation may change in any future SIS version.
- Parameters:
e
- a stack trace element.- Returns:
true
if the class and method specified by the given element can be considered public API.
-
unexpectedException
public static boolean unexpectedException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an unexpected error occurred. This method logs a message atLevel.WARNING
to the specified logger. The originating class name and method name can optionally be specified. If any of them isnull
, then it will be inferred from the error stack trace as described below.Recommended usage: explicit value for class and method names are preferred to automatic inference for the following reasons:If the- 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 sometimes 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.
classe
ormethod
arguments are null, then the originating class name and method name are inferred from the givenerror
using the first stack trace element for which the class name is inside a package or sub-package of the same name than the logger name.Example: if the logger name is"org.apache.sis.image"
, then this method will uses the first stack trace element where the fully qualified class name starts with"org.apache.sis.image"
or"org.apache.sis.image.io"
, but not"org.apache.sis.imageio"
.- Parameters:
logger
- where to log the error, ornull
for inferring a default value from other arguments.classe
- the class where the error occurred, ornull
for inferring a default value from other arguments.method
- the method where the error occurred, ornull
for inferring a default value from other arguments.error
- the error, ornull
if none.- Returns:
true
if the error has been logged, orfalse
if the givenerror
was null or if the logger does not log anything atLevel.WARNING
.- See Also:
-
unexpectedException
private static boolean unexpectedException(Logger logger, String classe, String method, Throwable error, Level level) Implementation ofunexpectedException(Logger, Class, String, Throwable)
.- Parameters:
logger
- where to log the error, ornull
for inferring a default value from other arguments.classe
- the fully qualified class name where the error occurred, ornull
for inferring a default value from other arguments.method
- the method where the error occurred, ornull
for inferring a default value from other arguments.error
- the error, ornull
if none.level
- the logging level.- Returns:
true
if the error has been logged, orfalse
if the givenerror
was null or if the logger does not log anything at the specified level.
-
configurationException
static boolean configurationException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an unexpected error occurred while configuring the system. The error shall not prevent the application from working, but may change the behavior in some minor aspects.Example: If theorg.apache.sis.util.logging.MonolineFormatter.time
pattern declared in thejre/lib/logging.properties
file is illegal, thenMonolineFormatter
will log this problem and use a default time pattern.- Parameters:
logger
- where to log the error, ornull
for inferring a default value from other arguments.classe
- the class where the error occurred, ornull
for inferring a default value from other arguments.method
- the method name where the error occurred, ornull
for inferring a default value from other arguments.error
- the error, ornull
if none.- Returns:
true
if the error has been logged, orfalse
if the givenerror
was null or if the logger does not log anything atLevel.CONFIG
.- See Also:
-
recoverableException
public static boolean recoverableException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when a recoverable error occurred. This method is similar tounexpectedException(…)
except that it does not log the stack trace and uses a lower logging level.- Parameters:
logger
- where to log the error, ornull
for inferring a default value from other arguments.classe
- the class where the error occurred, ornull
for inferring a default value from other arguments.method
- the method name where the error occurred, ornull
for inferring a default value from other arguments.error
- the error, ornull
if none.- Returns:
true
if the error has been logged, orfalse
if the givenerror
was null or if the logger does not log anything atLevel.FINE
.- See Also:
-
ignorableException
public static boolean ignorableException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when an ignorable error occurred. This method is similar tounexpectedException(…)
except that it uses a lower logging level.- Parameters:
logger
- where to log the error, ornull
for inferring a default value from other arguments.classe
- the class where the error occurred, ornull
for inferring a default value from other arguments.method
- the method name where the error occurred, ornull
for inferring a default value from other arguments.error
- the error, ornull
if none.- Returns:
true
if the error has been logged, orfalse
if the givenerror
was null or if the logger does not log anything atLevel.FINER
.- Since:
- 1.0
-
severeException
public static boolean severeException(Logger logger, Class<?> classe, String method, Throwable error) Invoked when a severe error occurred. This method is similar tounexpectedException
except that it logs the message at theSEVERE
level.- Parameters:
logger
- where to log the error, ornull
for inferring a default value from other arguments.classe
- the class where the error occurred, ornull
for inferring a default value from other arguments.method
- the method name where the error occurred, ornull
for inferring a default value from other arguments.error
- the error, ornull
if none.- Returns:
true
if the error has been logged, orfalse
if the givenerror
was null or if the logger does not log anything atLevel.SEVERE
.- See Also:
-