Class Log

java.lang.Object

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(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

Fields

Modifier and Type	Field	Description
static final LogLevel	DEBUG
static LogLevel	DEFAULT_LEVEL	The default level used for new logs.
static final LogLevel	ERROR
static final LogLevel	INFO
static final LogLevel	OFF
static final LogLevel	WARN

Method Summary

Modifier and Type	Method	Description
final void	bug(Object str1)
final void	bug(Object str1, Object str2)
final void	bug(Object str1, Object str2, Object str3)
final void	bug(Object str1, Object str2, Object str3, Object str4)
final void	bug(Object str1, Object str2, Object str3, Object str4, Object str5)
final void	bug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
final void	bug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
final 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
final void	debug(Object str1)
final void	debug(Object str1, Object str2)
final void	debug(Object str1, Object str2, Object str3)
final void	debug(Object str1, Object str2, Object str3, Object str4)
final void	debug(Object str1, Object str2, Object str3, Object str4, Object str5)
final void	debug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
final void	debug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
final void	debug(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
final void	error(Object str1)
final void	error(Object str1, Object str2)
final void	error(Object str1, Object str2, Object str3)
final void	error(Object str1, Object str2, Object str3, Object str4)
final void	error(Object str1, Object str2, Object str3, Object str4, Object str5)
final void	error(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
final void	error(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
final void	error(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)
static final Log	get(Class c)	Convenience method that returns the log named after the package that the specified class belong to.
static final 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.
final 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.
final void	info(Object str1)
final void	info(Object str1, Object str2)
final void	info(Object str1, Object str2, Object str3)
final void	info(Object str1, Object str2, Object str3, Object str4)
final void	info(Object str1, Object str2, Object str3, Object str4, Object str5)
final void	info(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
final void	info(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
final 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()
final void	warn(Object str1)
final void	warn(Object str1, Object str2)
final void	warn(Object str1, Object str2, Object str3)
final void	warn(Object str1, Object str2, Object str3, Object str4)
final void	warn(Object str1, Object str2, Object str3, Object str4, Object str5)
final void	warn(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6)
final void	warn(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7)
final void	warn(Object str1, Object str2, Object str3, Object str4, Object str5, Object str6, Object str7, Object... args)

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

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 Details

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

invalid reference

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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) 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(fc.io.LogLevel,int) and is generated automatically by the warn(), info(), debug() etc., methods

str2_onwards - some arbitrary object