fc.io
Class Log

java.lang.Object
  extended by fc.io.Log
Direct Known Subclasses:
SystemLog

public abstract class Log
extends Object

A system wide logging facility. Clearer and more elegant semantics/nomenclature than java.util.logging.

Logs messages to some user specified destination(s). Each log has a name and a log level.

The names are arbitrary (hopefully descriptive) names, per your liking. Many different logs can be created and then later retrieved by their name as needed.

The levels provided by this class have the order:

OFF < ERROR < WARN < INFO < DEBUG
The above levels are self-explanatory.

Convenience methods with names equal to a level name are provided. So for example, instead of saying:

log(LogLevel.warn, "the message");
one can say:
log.warn("the message");

A little historical quirk. For the debug level LogLevel.debug, one can say:
        log.debug("the message"); 
           --or--
        log.bug("the message"); 
        

A default logger of type SystemLog is provided for convenience in this class and can be retrieved by calling the getDefault() method.

The closeLog(String) method is called on all logs at JVM shutdown.

Note:To log a full stack traces, pass the string obtained by the IOUtil.throwableToString(java.lang.Throwable) method. (by default, an exception simply prints its message but not the full stack trace)

Implementation Note: subclasses should implement static getLog(..) type methods. These that create, as needed, and return a new log object of that subclass type. These getter methods should be static for convenience. Also, the implementation of the subclass.getLog(...) methods in subclasses is expected by convention.

Thread Safety: This class is Threadsafe and all its methods can be used concurrently.


Field Summary
static LogLevel DEBUG
           
static LogLevel DEFAULT_LEVEL
          The default level used for new logs.
static LogLevel ERROR
           
static LogLevel INFO
           
static LogLevel OFF
           
static LogLevel WARN
           
 
Method Summary
 void bug(Object str1)
           
 void bug(Object str1, Object str2)
           
 void bug(Object str1, Object str2, Object str3)
           
 void bug(Object str1, Object str2, Object str3, Object str4)
           
 void bug(Object str1, Object str2, Object str3, Object str4, Object str5)
           
 void bug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
           
 void bug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
           
 void bug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
           
 boolean canLog(LogLevel level)
          Returns true if the log's current level will allow logging messages at the specified logging level.
abstract  void close()
           
static void closeLog(String name)
          Closes and removes the log with the specified name if it exists
 void debug(Object str1)
           
 void debug(Object str1, Object str2)
           
 void debug(Object str1, Object str2, Object str3)
           
 void debug(Object str1, Object str2, Object str3, Object str4)
           
 void debug(Object str1, Object str2, Object str3, Object str4, Object str5)
           
 void debug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
           
 void debug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
           
 void debug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
           
 void error(Object str1)
           
 void error(Object str1, Object str2)
           
 void error(Object str1, Object str2, Object str3)
           
 void error(Object str1, Object str2, Object str3, Object str4)
           
 void error(Object str1, Object str2, Object str3, Object str4, Object str5)
           
 void error(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
           
 void error(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
           
 void error(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
           
static Log get(Class c)
          Convenience method that returns the log named after the package that the specified class belong to.
static Log get(Object obj)
          Convenience method that returns a log named after the package that the specified object's class belong to.
static Log get(String name)
          Returns a SystemLog with the specified name.
 String getDebugContext(LogLevel level, int framenum)
          Returns the method name, file number and line number of the calling method.
static SystemLog getDefault()
          Returns the default system log.
 LogLevel getLevel()
          Returns the current level set for this log.
 Iterator getLevelNames()
          Returns an iteration containing level names for this log.
static Log getLog(String name)
          An alias for method get(String).
 String getName()
          Returns the name of this log.
 void info(Object str1)
           
 void info(Object str1, Object str2)
           
 void info(Object str1, Object str2, Object str3)
           
 void info(Object str1, Object str2, Object str3, Object str4)
           
 void info(Object str1, Object str2, Object str3, Object str4, Object str5)
           
 void info(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
           
 void info(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
           
 void info(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
           
abstract  void log(LogLevel level, Object str1)
           
abstract  void log(LogLevel level, Object str1, Object str2)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3, Object str4)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3, Object str4, Object str5)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object str8)
           
abstract  void log(LogLevel level, Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object str8, Object... args)
           
 void logSystemInfo()
           
 void printLevelName(boolean printName)
          If set to true, will print the level name before the logging message.
 void printMethodInfoAtLevel(LogLevel level)
          By default, method, line and thread information is printed wich each logging statement at the DEBUG level.
 void printRelativeTimestamp(boolean val)
          Prints a relative time stamp with every message.
 void printTimestamp(boolean val)
          Prints a time stamp with every message.
static void setDefaultLevel(LogLevel level)
          Sets the new default logging level for all new instances of loggers (that are created after this method is invoked).
static void setDefaultLevel(String level)
          Sets the new default logging level for all new instances of loggers (created after this method is invoked).
 void setLevel(LogLevel level)
          Sets the current logging level for this logger.
 void setLevel(String levelname)
          Sets the level of this log based on a level description.
static void setLevelForAll(String name, LogLevel level)
          Sets the level for all logs whose name contain the specified name.
 String toString()
           
 void warn(Object str1)
           
 void warn(Object str1, Object str2)
           
 void warn(Object str1, Object str2, Object str3)
           
 void warn(Object str1, Object str2, Object str3, Object str4)
           
 void warn(Object str1, Object str2, Object str3, Object str4, Object str5)
           
 void warn(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
           
 void warn(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
           
 void warn(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

OFF

public static final LogLevel OFF

ERROR

public static final LogLevel ERROR

WARN

public static final LogLevel WARN

INFO

public static final LogLevel INFO

DEBUG

public static final LogLevel DEBUG

DEFAULT_LEVEL

public static LogLevel DEFAULT_LEVEL
The default level used for new logs. Subclasses should (by default) create logs using this level.

Method Detail

get

public static Log get(String name)
Returns a SystemLog with the specified name. If the log does not already exist, creates and returns a new SystemLog with that name.

The system log created will have a default destination of System.err and a default level of INFO.

To obtain logs with a different destination, create a SystemLog directly.


getLog

public static Log getLog(String name)
An alias for method get(String).

Returns a SystemLog with the specified name. If the log does not already exist, creates and returns a new SystemLog with that name.

The system log created will have a default destination of System.err and a default level of INFO.

To obtain logs with a different destination, create a SystemLog directly.


get

public static final Log get(Class c)
Convenience method that returns the log named after the package that the specified class belong to. If 2 classes
a.b.Class1
and
a.b.Class2
call this method, they will get the same logger (named a.b).

If the log does not already exist, creates and returns a new SystemLog with that name.

Parameters:
c - a non-null class

get

public static final Log get(Object obj)
Convenience method that returns a log named after the package that the specified object's class belong to. If 2 objects of class
a.b.Class1
and
a.b.Class2
call this method, they will get the same logger (named a.b).

If the log does not already exist, creates and returns a new SystemLog with that name.

Parameters:
obj - a non-null object

getDefault

public static SystemLog getDefault()
Returns the default system log. This system log writes to System.err and has it's level set to INFO. This level can be changed to some other level if desired by invoking setLevel() on the returned object.


getLevelNames

public Iterator getLevelNames()
Returns an iteration containing level names for this log. The names can be in any order.


closeLog

public static void closeLog(String name)
Closes and removes the log with the specified name if it exists


getDebugContext

public final String getDebugContext(LogLevel level,
                                    int framenum)
Returns the method name, file number and line number of the calling method. Useful for logging/code tracing.

Parameters:
level - the level for which this logging call was invoked.
framenum - the method to examine. This method itself has frame number 0, the calling method has frame number 1, it's parent 2 and so on.

printLevelName

public void printLevelName(boolean printName)
If set to true, will print the level name before the logging message. For example, if the level is INFO, the message is foo, then
INFO foo
will be printed.

This is set to true by default.


printTimestamp

public void printTimestamp(boolean val)
Prints a time stamp with every message. By default this is false

Parameters:
val - specify true to print time stamps, false to not

printRelativeTimestamp

public void printRelativeTimestamp(boolean val)
Prints a relative time stamp with every message. By default, printing any timestamp is false. Timestamps must first be enabled via the printTimestamp method before this method can have any effect.

Parameters:
val - if true, prints a relative time stamp. An initial timestamp is printed and all succeeding timestamps are second increments from the initial timestamp

printMethodInfoAtLevel

public void printMethodInfoAtLevel(LogLevel level)
By default, method, line and thread information is printed wich each logging statement at the DEBUG level. Other levels print only the log message but skip the method/stack information.

This method allows method information to be printed at all levels greater than or equal to the specified level.


setLevel

public void setLevel(LogLevel level)
Sets the current logging level for this logger. Each log has a logging level. A message is printed only if the message level is equal to or lower than the current maximum level for that log.

Typically, classes that implement a log will define a bunch of static variables of type LogLevel that list the available levels for that implementation. Clients of a particular log class should use levels defined within only that class.


setLevel

public void setLevel(String levelname)
Sets the level of this log based on a level description. This is convenient for when levels are specified in a configuration file. If the specified name cannot be converted into a level, then no change is made.

Parameters:
levelname - the level name. For example, "info" would set the level of this log to INFO. The name is case-insensitive.

setLevelForAll

public static void setLevelForAll(String name,
                                  LogLevel level)
Sets the level for all logs whose name contain the specified name. This is convenient when changing log levels for package heirarchies. A empty string (non-null) "" sets the level for all logs.

Parameters:
levelname - the level name. For example, "info" would set the level of this log to INFO. The name is case-insensitive.

setDefaultLevel

public static void setDefaultLevel(LogLevel level)
Sets the new default logging level for all new instances of loggers (that are created after this method is invoked).


setDefaultLevel

public static void setDefaultLevel(String level)
Sets the new default logging level for all new instances of loggers (created after this method is invoked).


canLog

public boolean canLog(LogLevel level)
Returns true if the log's current level will allow logging messages at the specified logging level.

Implementation Note: If the currentLevel is lesser or equal to the specified level returns true, else false. Subclasses can override this method if needed.

Parameters:
level - the specified logging level

getName

public String getName()
Returns the name of this log.


getLevel

public LogLevel getLevel()
Returns the current level set for this log. Useful when printing out debugging info.


logSystemInfo

public void logSystemInfo()

toString

public String toString()
Overrides:
toString in class Object

error

public final void error(Object str1)

error

public final void error(Object str1,
                        Object str2)

error

public final void error(Object str1,
                        Object str2,
                        Object str3)

error

public final void error(Object str1,
                        Object str2,
                        Object str3,
                        Object str4)

error

public final void error(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5)

error

public final void error(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5,
                        Object str6)

error

public final void error(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5,
                        Object str6,
                        Object str7)

error

public final void error(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5,
                        Object str6,
                        Object str7,
                        Object... args)

warn

public final void warn(Object str1)

warn

public final void warn(Object str1,
                       Object str2)

warn

public final void warn(Object str1,
                       Object str2,
                       Object str3)

warn

public final void warn(Object str1,
                       Object str2,
                       Object str3,
                       Object str4)

warn

public final void warn(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5)

warn

public final void warn(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5,
                       Object str6)

warn

public final void warn(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5,
                       Object str6,
                       Object str7)

warn

public final void warn(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5,
                       Object str6,
                       Object str7,
                       Object... args)

info

public final void info(Object str1)

info

public final void info(Object str1,
                       Object str2)

info

public final void info(Object str1,
                       Object str2,
                       Object str3)

info

public final void info(Object str1,
                       Object str2,
                       Object str3,
                       Object str4)

info

public final void info(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5)

info

public final void info(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5,
                       Object str6)

info

public final void info(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5,
                       Object str6,
                       Object str7)

info

public final void info(Object str1,
                       Object str2,
                       Object str3,
                       Object str4,
                       Object str5,
                       Object str6,
                       Object str7,
                       Object... args)

debug

public final void debug(Object str1)

debug

public final void debug(Object str1,
                        Object str2)

debug

public final void debug(Object str1,
                        Object str2,
                        Object str3)

debug

public final void debug(Object str1,
                        Object str2,
                        Object str3,
                        Object str4)

debug

public final void debug(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5)

debug

public final void debug(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5,
                        Object str6)

debug

public final void debug(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5,
                        Object str6,
                        Object str7)

debug

public final void debug(Object str1,
                        Object str2,
                        Object str3,
                        Object str4,
                        Object str5,
                        Object str6,
                        Object str7,
                        Object... args)

bug

public final void bug(Object str1)

bug

public final void bug(Object str1,
                      Object str2)

bug

public final void bug(Object str1,
                      Object str2,
                      Object str3)

bug

public final void bug(Object str1,
                      Object str2,
                      Object str3,
                      Object str4)

bug

public final void bug(Object str1,
                      Object str2,
                      Object str3,
                      Object str4,
                      Object str5)

bug

public final void bug(Object str1,
                      Object str2,
                      Object str3,
                      Object str4,
                      Object str5,
                      Object str6)

bug

public final void bug(Object str1,
                      Object str2,
                      Object str3,
                      Object str4,
                      Object str5,
                      Object str6,
                      Object str7)

bug

public final void bug(Object str1,
                      Object str2,
                      Object str3,
                      Object str4,
                      Object str5,
                      Object str6,
                      Object str7,
                      Object... args)

close

public abstract void close()

log

public abstract void log(LogLevel level,
                         Object str1)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3,
                         Object str4)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3,
                         Object str4,
                         Object str5)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3,
                         Object str4,
                         Object str5,
                         Object str6)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3,
                         Object str4,
                         Object str5,
                         Object str6,
                         Object str7)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3,
                         Object str4,
                         Object str5,
                         Object str6,
                         Object str7,
                         Object str8)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object

log

public abstract void log(LogLevel level,
                         Object str1,
                         Object str2,
                         Object str3,
                         Object str4,
                         Object str5,
                         Object str6,
                         Object str7,
                         Object str8,
                         Object... args)
Parameters:
level - the current log level. This can be logged as well.
str1 - unless overridden in a subclass, this is the value returned by getDebugContext and is generated automatically by the warn(), info(), debug() etc., methods
str2_onwards - some arbitrary object