Log (j(s)-lib Commons 1.1.2 API)

All Known Implementing Classes:

AbstractLog, DefaultLog
```
public interface Log
```
A log instance has a name and supplies means to write log messages with priority level. Depending on logging system configuration certain classes or levels can be disabled in which case messages are simple discarded. Current implementation handle below levels, listed in priority order. If a level is enabled all level below it are also enabled. For example, if enable WARN, ERROR, FATAL and BUG are automatically enabled.
1. TRACE - the same as debug but with finer granularity,
2. DEBUG - fine-grained informational events that are most useful to debug an application,
3. INFO - informational messages that highlight the progress of the application at coarse-grained level,
4. WARN - potentially harmful situations,
5. ERROR - error events that might still allow the application to continue running,
6. FATAL - very severe error events that will presumably lead the application to abort,
7. BUG - unexpected condition likely to be a bug.
For every level there are two writing methods: one accepting an object message and the second with formatted string and variable number of arguments. Object message is simply converted to string using implementation specific logic. At a minimum, implementation should use Object.toString(). Object message is always converted to string even if it is a Throwable. For stack trace dump uses dump(Object, Throwable).
Anyway, the real workhorse is string formatted variant, that is invoked even if string is not formatted, hence no formatting arguments. This writing variant is well suited for for formatted messages since it actually build the message only if level is enabled.
```
 // StringBuild is auto-created and execute strings merge before invoking debug writer, even if debug level is disabled
 log.debug("Class loaded " + class.getName());
 
 // formatted string and arguments are processed internally by debug writer only if debug level is enabled
 log.debug("Class loaded %s.", class.getName());
 
```
Stack Trace Dump
Logger writing methods does process all objects as strings, even if an exception is passed. In below sample code exception is converted to string before the actual write operation.
```
 catch(IOException exception) {
        log.error(exception);
 }
 
```
If one wants a throwable stack trace needs to explicitly invoke it using dump(Object, Throwable) method.
```
 catch(IOException exception) {
        log.dump("Fatal error on IO. Stack trace follow:", exception);
 }
 
```
Version:

final

Author:

Iulian Rotaru

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`bug(boolean expectedCondition, String message, Object... args)` Bug message variant with integrated condition test.
`void`	`bug(String message, Object... args)` Write a message about a condition that is likely to be a bug.
`void`	`debug(Object message)` Write object message to logger if `debug` level is enabled.
`void`	`debug(String message, Object... args)` Write formatted message to this logger if `debug` level is enabled.
`void`	`dump(Object message, Throwable throwable)` Dump throwable stack trace to this logger using `fatal` level.
`void`	`error(Object message)` Write object message to logger if `error` level is enabled.
`void`	`error(String message, Object... args)` Write formatted message to this logger if `error` level is enabled.
`void`	`fatal(Object message)` Write object message to logger if `fatal` level is enabled.
`void`	`fatal(String message, Object... args)` Write formatted message to this logger if `fatal` level is enabled.
`void`	`info(Object message)` Write object message to logger if `info` level is enabled.
`void`	`info(String message, Object... args)` Write formatted message to this logger if `info` level is enabled.
`void`	`print(LogLevel level, String message)` Write message directly to logger with specified logging level.
`void`	`trace(Object message)` Write object message to logger if `trace` level is enabled.
`void`	`trace(String message, Object... args)` Write formatted message to this logger if `trace` level is enabled.
`void`	`warn(Object message)` Write object message to logger if `warn` level is enabled.
`void`	`warn(String message, Object... args)` Write formatted message to this logger if `warn` level is enabled.

- Method Detail
  - trace
```
void trace(Object message)
```
    Write object message to logger if trace level is enabled. This method converts object message to string and write it as a single log record. Note that string conversion is performed even if given object message is a Throwable. If one needs throwable stack dump should explicitly use dump(Object, Throwable).
    
    Parameters:
    
    message - object message.
  - trace
```
void trace(String message,
           Object... args)
```
    Write formatted message to this logger if trace level is enabled. This method uses formatted message to build the string message and write it as a single log record. Note that the actual string building is performed only only if level is enabled.
    Message should be formatted as defined by String.format(String, Object...) standard method. It is caller responsibility to ensure the number and type of given argument match formatted message place holders. If message is not well formed or arguments are invalid log record is silently discarded.
    
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - debug
```
void debug(Object message)
```
    Write object message to logger if debug level is enabled. See trace(Object) for details.
    
    Parameters:
    
    message - object message.
  - debug
```
void debug(String message,
           Object... args)
```
    Write formatted message to this logger if debug level is enabled. See trace(String, Object...) for details.
    
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - info
```
void info(Object message)
```
    Write object message to logger if info level is enabled. See trace(Object) for details.
    
    Parameters:
    
    message - object message.
  - info
```
void info(String message,
          Object... args)
```
    Write formatted message to this logger if info level is enabled. See trace(String, Object...) for details.
    
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - warn
```
void warn(Object message)
```
    Write object message to logger if warn level is enabled. See trace(Object) for details.
    
    Parameters:
    
    message - object message.
  - warn
```
void warn(String message,
          Object... args)
```
    Write formatted message to this logger if warn level is enabled. See trace(String, Object...) for details.
    
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - error
```
void error(Object message)
```
    Write object message to logger if error level is enabled. See trace(Object) for details.
    
    Parameters:
    
    message - object message.
  - error
```
void error(String message,
           Object... args)
```
    Write formatted message to this logger if error level is enabled. See trace(String, Object...) for details.
    
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - fatal
```
void fatal(Object message)
```
    Write object message to logger if fatal level is enabled. See trace(Object) for details.
    
    Parameters:
    
    message - object message.
  - fatal
```
void fatal(String message,
           Object... args)
```
    Write formatted message to this logger if fatal level is enabled. See trace(String, Object...) for details.
    
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - bug
```
void bug(String message,
         Object... args)
```
    Write a message about a condition that is likely to be a bug. This denote the code reaches a point that is not expected. For example switch default when expect all cases to be processed or an expected value is missing, see sample code.
```
 switch(state) {
        case PLAYING:
        . . .
        break;
 
 case PAUSED:
        . . .
        break;
         
 default:
        log.bug("Player state not handled.");
 }
 
```
```
 Connection connection = connections.remove(listener);
 if (connection == null) {
        log.bug("Unbind called without bind.");
        return;
 }
 
```
    Parameters:
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - bug
```
void bug(boolean expectedCondition,
         String message,
         Object... args)
```
    Bug message variant with integrated condition test. If condition is not true write formatted message but only if bug level is enabled. If bug level is not enabled expected condition is not considered and of course message is not written.
    
    Parameters:
    
    expectedCondition - condition expected to be true,
    
    message - formatted message,
    
    args - optional arguments for formatted message.
  - dump
```
void dump(Object message,
          Throwable throwable)
```
    Dump throwable stack trace to this logger using fatal level. Object message is converted to string and write before stack trace as a separate log record. This method guarantees atomic operation, that is, no other log record present between object message and stack dump.
    If fatal level is not enabled this method does nothing.
    
    Parameters:
    
    message - object message,
    
    throwable - throwable to dump stack trace for.
  - print
```
void print(LogLevel level,
           String message)
```
    Write message directly to logger with specified logging level. Anyway, if level is disabled message is not printed. This method is considered low level and is not intended for general use.
    
    Parameters:
    
    level - requested log level,
    
    message - log message.

Interface Log

Stack Trace Dump

Method Summary

Method Detail

trace

trace

debug

debug

info

info

warn

warn

error

error

fatal

fatal

bug

bug

dump

print