org.apache.sis.util.logging

Class LoggerAdapter

Object

Logger

LoggerAdapter

public abstract class LoggerAdapter
extends Logger

An adapter that redirect all JDK logging events to an other logging framework. This class redefines the severe, warning, info, config, fine, finer and finest methods as abstract ones. Subclasses should implement those methods in order to map JDK logging levels to the backend logging framework.

All log methods are overridden in order to redirect to one of the above-cited methods. Note that this is the opposite approach than the JDK logging framework one, which implements everything on top of Logger.log(Log­Record). This adapter is defined in terms of severe … finest methods instead because external frameworks like Commons-logging don't work with Log­Record, and sometime provides nothing else than convenience methods equivalent to severe … finest.

Restrictions

Because the configuration is expected to be fully controlled by the external logging framework, every configuration methods inherited from Logger are disabled:

• add­Handler(Handler) since the handling is performed by the external framework.
• set­Use­Parent­Handlers(boolean) since this adapter never delegates to the parent handlers. This is consistent with the previous item and avoid mixing loggings from the external framework with JDK loggings.
• set­Parent(Logger) since this adapter should not inherits any configuration from a parent logger using the JDK logging framework.
• set­Filter(Filter) for keeping this Logger­Adapter simple.

Since Logger­Adapters do not hold any configuration by themselves, it is not strictly necessary to add them to the log manager. The adapters can be created, garbage-collected and recreated again while preserving their behavior since their configuration is entirely contained in the external logging framework.

Localization

This logger is always created without resource bundles. Localizations shall be done through explicit calls to logrb or log(Log­Record) methods. This is sufficient for SIS needs, which performs all localizations through the later. Note that those methods will be slower in this Logger­Adapter than the default Logger because this adapter localizes and formats records immediately instead of letting the Handler performs this work only if needed.

Logging levels

If a log record level is not one of the predefined ones, then this class maps to the first level below the specified one. For example if a log record has some level between FINE and FINER, then the finer method will be invoked. See is­Loggable(Level) for implementation tips taking advantage of this rule.

Since:

0.3

See Also:

Logging

Defined in the sis-utility module

Field Summary

Fields inherited from class Logger

global, GLOBAL_LOGGER_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Logger­Adapter(String name) Creates a new logger.

Method Summary

Modifier and Type	Method and Description
void	add­Handler(Handler handler) Do nothing since this logger adapter does not supports handlers.
abstract void	config(String message) Logs an CONFIG message.
void	entering(String source­Class, String source­Method) Logs a method entry to the debug level.
void	entering(String source­Class, String source­Method, Object param) Logs a method entry to the debug level with one parameter.
void	entering(String source­Class, String source­Method, Object[] params) Logs a method entry to the debug level with many parameters.
void	exiting(String source­Class, String source­Method) Logs a method return to the debug level.
void	exiting(String source­Class, String source­Method, Object result) Logs a method return to the debug level.
abstract void	fine(String message) Logs a FINE message.
abstract void	finer(String message) Logs a FINER message.
abstract void	finest(String message) Logs a FINEST message.
protected Level	get­Debug­Level() Returns the level for entering(…), exiting(…) and throwing(…) methods.
abstract Level	get­Level() Returns the level for this logger.
abstract void	info(String message) Logs an INFO message.
abstract boolean	is­Loggable(Level level) Returns true if the specified level is loggable.
void	log(Level level, String message) Logs a record at the specified level.
void	log(Level level, String message, Object param) Logs a record at the specified level.
void	log(Level level, String message, Object[] params) Logs a record at the specified level.
void	log(Level level, String message, Throwable thrown) Logs a record at the specified level.
void	log(Log­Record record) Logs a record.
void	logp(Level level, String source­Class, String source­Method, String message) Logs a record at the specified level.
void	logp(Level level, String source­Class, String source­Method, String message, Object param) Logs a record at the specified level.
void	logp(Level level, String source­Class, String source­Method, String message, Object[] params) Logs a record at the specified level.
void	logp(Level level, String source­Class, String source­Method, String message, Throwable thrown) Logs a record at the specified level.
void	logrb(Level level, String source­Class, String source­Method, Resource­Bundle bundle, String message, Object... params) Logs a localizable record at the specified level.
void	logrb(Level level, String source­Class, String source­Method, Resource­Bundle bundle, String message, Throwable thrown) Logs a localizable record at the specified level.
void	logrb(Level level, String source­Class, String source­Method, String bundle­Name, String message) Deprecated. JDK 8 has deprecated this method.
void	logrb(Level level, String source­Class, String source­Method, String bundle­Name, String message, Object param) Deprecated. JDK 8 has deprecated this method.
void	logrb(Level level, String source­Class, String source­Method, String bundle­Name, String message, Object[] params) Deprecated. JDK 8 has deprecated this method.
void	logrb(Level level, String source­Class, String source­Method, String bundle­Name, String message, Throwable thrown) Deprecated. JDK 8 has deprecated this method.
void	remove­Handler(Handler handler) Do nothing since this logger adapter does not support handlers.
void	set­Filter(Filter filter) Do nothing since this logger adapter does not support filters.
abstract void	set­Level(Level level) Sets the level for this logger.
void	set­Parent(Logger parent) Do nothing since this logger adapter does not support arbitrary parents.
void	set­Use­Parent­Handlers(boolean use­Parent­Handlers) Do nothing since this logger never use parent handlers.
abstract void	severe(String message) Logs a SEVERE message.
void	throwing(String source­Class, String source­Method, Throwable thrown) Logs a method failure to the debug level.
abstract void	warning(String message) Logs a WARNING message.

Methods inherited from class Logger

config, fine, finer, finest, get­Anonymous­Logger, get­Anonymous­Logger, get­Filter, get­Global, get­Handlers, get­Logger, get­Logger, get­Name, get­Parent, get­Resource­Bundle, get­Resource­Bundle­Name, get­Use­Parent­Handlers, info, log, log, logp, logp, set­Resource­Bundle, severe, warning

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Detail

LoggerAdapter

protected LoggerAdapter(String name)

Creates a new logger.

Parameters:

name - The logger name.

Method Detail

setLevel

public abstract void setLevel(Level level)

Sets the level for this logger. Subclasses must redirect the call to the external logging framework, or do nothing if the level can not be changed programmatically.

Overrides:

set­Level in class Logger

Parameters:

level - The new value for the log level (may be null).

getLevel

public abstract Level getLevel()

Returns the level for this logger. Subclasses shall get this level from the external logging framework.

Overrides:

get­Level in class Logger

Returns:

The logger's level.

getDebugLevel

@Debug
protected Level getDebugLevel()

Returns the level for entering(…), exiting(…) and throwing(…) methods. The default implementation returns Level.FINER, which is consistent with the value used in the JDK logging framework. Subclasses should override this method if a different debug level is wanted.

Returns:

The level to use for debugging informations.

isLoggable

public abstract boolean isLoggable(Level level)

Returns true if the specified level is loggable.

Implementation tip

Given that Level.int­Value() for all predefined levels are documented in the Level specification and are multiple of 100, given that integer divisions are rounded toward zero and given rule documented in this class javadoc, then logging levels can be efficiently mapped to predefined levels using switch statements as below. This statement has good chances to be compiled to the tableswitch bytecode rather than lookupswitch (see Compiling Switches in The Java Virtual Machine Specification).

public boolean isLoggable(Level level) {
    final int n = level.intValue();
    switch (n / 100) {
        default: {
            // MAX_VALUE is a special value for Level.OFF. Otherwise and
            // if positive, fallthrough since we are greater than SEVERE.
            switch (n) {
                case Integer.MIN_VALUE: return true;  // Level.ALL
                case Integer.MAX_VALUE: return false; // Level.OFF
                default: if (n < 0) return false;
            }
        }
        case 10: return isSevereEnabled();
        case  9: return isWarningEnabled();
        case  8: return isInfoEnabled();
        case  7: return isConfigEnabled();
        case  6: // fallthrough
        case  5: return isFineEnabled();
        case  4: return isFinerEnabled();
        case  3: return isFinestEnabled();
        case  2: // fallthrough
        case  1: // fallthrough
        case  0: return false;
    }
}

Overrides:

is­Loggable in class Logger

Parameters:

level - A message logging level.

Returns:

true if the given message level is currently being logged.

severe

public abstract void severe(String message)

Logs a SEVERE message.

Overrides:

severe in class Logger

Parameters:

message - The message to log.

warning

public abstract void warning(String message)

Logs a WARNING message.

Overrides:

warning in class Logger

Parameters:

message - The message to log.

info

public abstract void info(String message)

Logs an INFO message.

Overrides:

info in class Logger

Parameters:

message - The message to log.

config

public abstract void config(String message)

Logs an CONFIG message.

Overrides:

config in class Logger

Parameters:

message - The message to log.

fine

public abstract void fine(String message)

Logs a FINE message.

Overrides:

fine in class Logger

Parameters:

message - The message to log.

finer

public abstract void finer(String message)

Logs a FINER message.

Overrides:

finer in class Logger

Parameters:

message - The message to log.

finest

public abstract void finest(String message)

Logs a FINEST message.

Overrides:

finest in class Logger

Parameters:

message - The message to log.

entering

public void entering(String sourceClass,
                     String sourceMethod)

Logs a method entry to the debug level. Compared to the default Logger, this implementation bypass the level check in order to let the backing logging framework do its own check.

Overrides:

entering in class Logger

Parameters:

source­Class - Name of class that issued the logging request.

source­Method - Name of method that is being entered.

entering

public void entering(String sourceClass,
                     String sourceMethod,
                     Object param)

Logs a method entry to the debug level with one parameter. Compared to the default Logger, this implementation bypass the level check in order to let the backing logging framework do its own check.

Overrides:

entering in class Logger

Parameters:

source­Class - Name of class that issued the logging request.

source­Method - Name of method that is being entered.

param - Parameter to the method being entered.

entering

public void entering(String sourceClass,
                     String sourceMethod,
                     Object[] params)

Logs a method entry to the debug level with many parameters. Compared to the default Logger, this implementation bypass the level check in order to let the backing logging framework do its own check.

Overrides:

entering in class Logger

Parameters:

source­Class - Name of class that issued the logging request.

source­Method - Name of method that is being entered.

params - Array of parameters to the method being entered.

exiting

public void exiting(String sourceClass,
                    String sourceMethod)

Logs a method return to the debug level. Compared to the default Logger, this implementation bypass the level check in order to let the backing logging framework do its own check.

Overrides:

exiting in class Logger

Parameters:

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

exiting

public void exiting(String sourceClass,
                    String sourceMethod,
                    Object result)

Logs a method return to the debug level. Compared to the default Logger, this implementation bypass the level check in order to let the backing logging framework do its own check.

Overrides:

exiting in class Logger

Parameters:

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

result - Object that is being returned.

throwing

public void throwing(String sourceClass,
                     String sourceMethod,
                     Throwable thrown)

Logs a method failure to the debug level. Compared to the default Logger, this implementation bypass the level check in order to let the backing logging framework do its own check.

Overrides:

throwing in class Logger

Parameters:

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

thrown - The Throwable that is being thrown.

log

public void log(LogRecord record)

Logs a record. The default implementation delegates to one of the logrb or logp(Level,String,String,String) methods.

Overrides:

log in class Logger

Parameters:

record - The log record to be published.

log

public void log(Level level,
                String message)

Logs a record at the specified level. The default implementation delegates to one of the severe, warning, info, config, fine, finer or finest methods according the supplied level.

Overrides:

log in class Logger

Parameters:

level - One of the message level identifiers.

message - The message to log.

log

public void log(Level level,
                String message,
                Throwable thrown)

Logs a record at the specified level. The default implementation discards the exception and delegates to log(level, message).

Overrides:

log in class Logger

Parameters:

level - One of the message level identifiers.

message - The message to log.

thrown - Throwable associated with log message.

log

public void log(Level level,
                String message,
                Object param)

Logs a record at the specified level. The default implementation delegates to log(level, message, params) where the params array is built from the param object.

Overrides:

log in class Logger

Parameters:

level - One of the message level identifiers.

message - The message to log.

param - Parameter to the method being entered.

log

public void log(Level level,
                String message,
                Object[] params)

Logs a record at the specified level. The default implementation formats the message immediately, then delegates to log(level, message).

Overrides:

log in class Logger

Parameters:

level - One of the message level identifiers.

message - The message to log.

params - Array of parameters to the method being entered.

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message)

Logs a record at the specified level. The default implementation discards the source class and source method, then delegates to log(level, message).

Overrides:

logp in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

message - The message to log.

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message,
                 Throwable thrown)

Logs a record at the specified level. The default implementation discards the source class and source method, then delegates to log(level, message, thrown).

Overrides:

logp in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

message - The message to log.

thrown - Throwable associated with log message.

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message,
                 Object param)

Logs a record at the specified level. The default implementation delegates to logp(level, source­Class, source­Method, message, params) where the params array is built from the param object.

Note that source­Class and source­Method will be discarded unless the target logp method has been overridden.

Overrides:

logp in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

message - The message to log.

param - Parameter to the method being entered.

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String message,
                 Object[] params)

Logs a record at the specified level. The default implementation formats the message immediately, then delegates to logp(level, source­Class, source­Method, message).

Note that source­Class and source­Method will be discarded unless the target logp method has been overridden.

Overrides:

logp in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

message - The message to log.

params - Array of parameters to the method being entered.

logrb

public void logrb(Level level,
                  String sourceClass,
                  String sourceMethod,
                  ResourceBundle bundle,
                  String message,
                  Object... params)

Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to logp(level, source­Class, source­Method, message, params).

Overrides:

logrb in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

bundle - The resource bundle for localizing the message, or null.

message - The message to log.

params - Array of parameters to the method being entered.

Since:

0.5

logrb

public void logrb(Level level,
                  String sourceClass,
                  String sourceMethod,
                  ResourceBundle bundle,
                  String message,
                  Throwable thrown)

Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to logp(level, source­Class, source­Method, message, thrown).

Overrides:

logrb in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

bundle - The resource bundle for localizing the message, or null.

message - The message to log.

thrown - Throwable associated with log message.

Since:

0.5

logrb

@Deprecated
public void logrb(Level level,
                              String sourceClass,
                              String sourceMethod,
                              String bundleName,
                              String message)

Deprecated. JDK 8 has deprecated this method.

Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to logp(level, source­Class, source­Method, message).

Overrides:

logrb in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

bundle­Name - Name of resource bundle to localize message, or null.

message - The message to log.

logrb

@Deprecated
public void logrb(Level level,
                              String sourceClass,
                              String sourceMethod,
                              String bundleName,
                              String message,
                              Throwable thrown)

Deprecated. JDK 8 has deprecated this method.

Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to logp(level, source­Class, source­Method, message, thrown).

Overrides:

logrb in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

bundle­Name - Name of resource bundle to localize message, or null.

message - The message to log.

thrown - Throwable associated with log message.

logrb

@Deprecated
public void logrb(Level level,
                              String sourceClass,
                              String sourceMethod,
                              String bundleName,
                              String message,
                              Object param)

Deprecated. JDK 8 has deprecated this method.

Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to logp(level, source­Class, source­Method, message, param).

Overrides:

logrb in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

bundle­Name - Name of resource bundle to localize message, or null.

message - The message to log.

param - Parameter to the method being entered.

logrb

@Deprecated
public void logrb(Level level,
                              String sourceClass,
                              String sourceMethod,
                              String bundleName,
                              String message,
                              Object[] params)

Deprecated. JDK 8 has deprecated this method.

Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to logp(level, source­Class, source­Method, message, params).

Overrides:

logrb in class Logger

Parameters:

level - One of the message level identifiers.

source­Class - Name of class that issued the logging request.

source­Method - Name of the method.

bundle­Name - Name of resource bundle to localize message, or null.

message - The message to log.

params - Array of parameters to the method being entered.

addHandler

public void addHandler(Handler handler)

Do nothing since this logger adapter does not supports handlers. The configuration should be fully controlled by the external logging framework (e.g. Commons-logging) instead, which is not expected to use Handler objects.

Overrides:

add­Handler in class Logger

Parameters:

handler - A logging handler, ignored in default implementation.

removeHandler

public void removeHandler(Handler handler)

Do nothing since this logger adapter does not support handlers.

Overrides:

remove­Handler in class Logger

Parameters:

handler - A logging handler, ignored in default implementation.

setUseParentHandlers

public void setUseParentHandlers(boolean useParentHandlers)

Do nothing since this logger never use parent handlers. This is consistent with add­Handler(java.util.logging.Handler) not allowing to add any handlers, and avoid mixing loggings from the external framework with JDK loggings.

Overrides:

set­Use­Parent­Handlers in class Logger

Parameters:

use­Parent­Handlers - Ignored in default implementation.

setParent

public void setParent(Logger parent)

Do nothing since this logger adapter does not support arbitrary parents. More specifically, it should not inherits any configuration from a parent logger using the JDK logging framework.

Overrides:

set­Parent in class Logger

Parameters:

parent - Ignored in default implementation.

setFilter

public void setFilter(Filter filter)

Do nothing since this logger adapter does not support filters. It is difficult to query efficiently the filter in this Logger­Adapter architecture (e.g. we would need to make sure that Filter.is­Loggable(java.util.logging.Log­Record) is invoked only once even if a log call is cascaded into many other log calls, and this test must works in multi-threads environment).

Overrides:

set­Filter in class Logger

Parameters:

filter - Ignored in default implementation.