org.grlea.log
Class SimpleLogger

java.lang.Object
  org.grlea.log.SimpleLogger

public class SimpleLogger

extends java.lang.Object

Used to create log messages for a single class or instance of a class.

SimpleLogger is where it all happens, from a client's perspective.
The easiest way to use Simple Log is to create one SimpleLogger for each class and then log to it!

1. Create a logger like this:

    private static final SimpleLogger log = new SimpleLogger(HelloWorld.class);
 

2. And then use it like this:

       log.entry("main()");
       log.debugObject("argv", argv);
       if (argv.length == 0)
       {
          log.info("No arguments. Using defaults.");
          ...
       }
       ...
       log.exit("main()");
 

SimpleLogger provides for four types of log messages:

• "db" = Debug (see SimpleLogger.db())
  Lets you log a simple log message, e.g. "Got to the point where you thought it wasn't getting to."



• "dbo" = Debug Object (see SimpleLogger.dbo())
  Debugs the name and value of an object. Specially handled variants exist for all primitives, Object[], byte[] and char[].



• "dbe" = Debug Exception (see SimpleLogger.dbe())
  Special handling of exceptions that will print a stack trace (can be turned off).



• Tracing (see SimpleLogger.entry() and SimpleLogger.exit())
  Logs entry to and exit from a method. Can be turned on/off independent of debug level.
  

as well as convenience methods, named after the various levels, as shortcuts to the above methods.

Instance-based SimpleLoggers can be used to determine, from the log output, exactly which object a log statement is coming from. This is useful when many objects of the same class are all performing logging and it is crucial to analysis to know which object logged any given message.

Here is an example of how an instance-based logger would be used:

 public class
 Test
 {
    private final SimpleLogger log;

    private final String id;

    public
    Test(String id)
    {
       log = new SimpleLogger(Test.class, id);
       this.id = id;
    }
 }

Note the following important features of this pattern and instance-based logs in general:

• The log field is not static. There is one per instance.
• <ClassName>.class is used rather than getClass(). Otherwise, if this class were subclassed, logging statements would appear with the subclass's name as the source.
• There are separate log formats for instance-based logs in the properties file.

Version:

$Revision: 1.2 $

Author:

$Author: grlea $

Constructor Summary

SimpleLogger(java.lang.Class sourceClass)
Creates a new SimpleLogger for the specified Class using the default SimpleLog.

SimpleLogger(java.lang.Class sourceClass, boolean useLongName)
Creates a new SimpleLogger for the specified Class using the default SimpleLog.

SimpleLogger(java.lang.Class sourceClass, java.lang.Object instanceId)
Creates a new SimpleLogger for the specified Class using the default SimpleLog.

SimpleLogger(java.lang.Class sourceClass, java.lang.Object instanceId, boolean useLongName)
Creates a new SimpleLogger for the specified Class using the default SimpleLog.

SimpleLogger(SimpleLog log, java.lang.Class sourceClass)
Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

SimpleLogger(SimpleLog log, java.lang.Class sourceClass, boolean useLongName)
Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

SimpleLogger(SimpleLog log, java.lang.Class sourceClass, java.lang.Object instanceId)
Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

SimpleLogger(SimpleLog log, java.lang.Class sourceClass, java.lang.Object instanceId, boolean useLongName)
Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

Method Summary

void	db(DebugLevel level, java.lang.String message) Logs a simple debug message.
void	dbe(DebugLevel level, java.lang.Throwable t) Logs a message containing an exception (or throwable).
void	dbo(DebugLevel level, java.lang.String objectName, boolean val) Logs a message containing a boolean's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, byte val) Logs a message containing a byte's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, byte[] val) Logs a message containing a byte array's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, char val) Logs a message containing a char's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, char[] val) Logs a message containing a char array's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, double val) Logs a message containing a double's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, float val) Logs a message containing a float's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, int val) Logs a message containing an int's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, long val) Logs a message containing a long's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, java.lang.Object value) Logs a message containing an object's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, java.lang.Object[] val) Logs a message containing an object array's name and value.
void	dbo(DebugLevel level, java.lang.String objectName, short val) Logs a message containing a short's name and value.
void	debug(java.lang.String message) Logs a debug message at the Debug level.
void	debugObject(java.lang.String objectName, boolean val) Convenience method for logging a boolean's name and value at the Debug level.
void	debugObject(java.lang.String objectName, int val) Convenience method for logging an int's name and value at the Debug level.
void	debugObject(java.lang.String objectName, java.lang.Object val) Convenience method for logging an object's name and value at the Debug level.
void	entry(java.lang.String methodName) Logs an entry message.
void	error(java.lang.String message) Logs a debug message at the Error level.
void	errorException(java.lang.Throwable t) Convenience method for logging an exception (or throwable) at the Error level.
void	exit(java.lang.String methodName) Logs an exit message.
void	fatal(java.lang.String message) Logs a debug message at the Fatal level.
void	fatalException(java.lang.Throwable t) Convenience method for logging an exception (or throwable) at the Fatal level.
java.lang.String	getConfigName() Returns this SimpleLogger's config name, the name used to specify and look up its configuration.
DebugLevel	getDebugLevel() Returns the current debug level of this SimpleLogger.
java.lang.Object	getInstanceID() Returns the #instanceId of this SimpleLogger, or null if it does not have one (i.e.
java.lang.Class	getSourceClass() Returns the source class of this SimpleLogger.
void	info(java.lang.String message) Logs a debug message at the Info level.
void	infoObject(java.lang.String objectName, boolean val) Convenience method for logging a boolean's name and value at the Info level.
void	infoObject(java.lang.String objectName, int val) Convenience method for logging an int's name and value at the Info level.
void	infoObject(java.lang.String objectName, java.lang.Object val) Convenience method for logging an object's name and value at the Info level.
boolean	isInstanceDebugger() Returns true if this SimpleLogger is a logger for one instance of the source class rather than for the class as a whole.
boolean	isTracing() Returns whether this SimpleLogger is currently reporting tracing or not.
void	ludicrous(java.lang.String message) Logs a debug message at the Ludicrous level.
void	ludicrousObject(java.lang.String objectName, boolean val) Convenience method for logging a boolean's name and value at the Ludicrous level.
void	ludicrousObject(java.lang.String objectName, int val) Convenience method for logging an int's name and value at the Ludicrous level.
void	ludicrousObject(java.lang.String objectName, java.lang.Object val) Convenience method for logging an object's name and value at the Ludicrous level.
void	setDebugLevel(DebugLevel debugLevel) Sets the current debug level of this SimpleLogger.
void	setInstanceID(java.lang.Object instanceId) Sets the #instanceId of this SimpleLogger instance.
void	setTracing(boolean tracing) Sets this SimpleLogger's tracing flag.
void	verbose(java.lang.String message) Logs a debug message at the Verbose level.
void	verboseObject(java.lang.String objectName, boolean val) Convenience method for logging a boolean's name and value at the Verbose level.
void	verboseObject(java.lang.String objectName, int val) Convenience method for logging an int's name and value at the Verbose level.
void	verboseObject(java.lang.String objectName, java.lang.Object val) Convenience method for logging an object's name and value at the Verbose level.
void	warn(java.lang.String message) Logs a debug message at the Warn level.
void	warnException(java.lang.Throwable t) Convenience method for logging an exception (or throwable) at the Warn level.
boolean	wouldLog(DebugLevel level) A convenience method for testing whether a message logged at the specified level would be logged by this SimpleLogger.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleLogger

public SimpleLogger(java.lang.Class sourceClass)

Creates a new SimpleLogger for the specified Class using the default SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(SimpleLog.defaultInstance(), sourceClass)

Parameters:

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

SimpleLogger

public SimpleLogger(java.lang.Class sourceClass,
                    java.lang.Object instanceId)

Creates a new SimpleLogger for the specified Class using the default SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(SimpleLog.defaultInstance(), sourceClass, instanceId)

Parameters:

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

instanceId - An object uniquely identifying the instance of sourceClass that this SimpleLogger is specifically for. Can be null if this SimpleLogger instance is for all instances of sourceClass rather than for a particular instance (this is the norm).

SimpleLogger

public SimpleLogger(java.lang.Class sourceClass,
                    boolean useLongName)

Creates a new SimpleLogger for the specified Class using the default SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(SimpleLog.defaultInstance(), sourceClass, useLongName)

Parameters:

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

useLongName - A boolean indicating whether the fully-qualified name of the specified class should be printed in each message (when set to true), or just the name of the class within it's package (ie. the package will not be printed when set to false).

SimpleLogger

public SimpleLogger(java.lang.Class sourceClass,
                    java.lang.Object instanceId,
                    boolean useLongName)

Creates a new SimpleLogger for the specified Class using the default SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(SimpleLog.defaultInstance(), sourceClass, instanceId, useLongName)

Parameters:

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

instanceId - An object uniquely identifying the instance of sourceClass that this SimpleLogger is specifically for. Can be null if this SimpleLogger instance is for all instances of sourceClass rather than for a particular instance (this is the norm).

useLongName - A boolean indicating whether the fully-qualified name of the specified class should be printed in each message (when set to true), or just the name of the class within it's package (ie. the package will not be printed when set to false).

SimpleLogger

public SimpleLogger(SimpleLog log,
                    java.lang.Class sourceClass)

Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(log, sourceClass, false)

Parameters:

log - the SimpleLog instance that this SimpleLogger should log to and be configured by.

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

SimpleLogger

public SimpleLogger(SimpleLog log,
                    java.lang.Class sourceClass,
                    java.lang.Object instanceId)

Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(SimpleLog.defaultInstance(), sourceClass, instanceId, false)

Parameters:

log - the SimpleLog instance that this SimpleLogger should log to and be configured by.

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

instanceId - An object uniquely identifying the instance of sourceClass that this SimpleLogger is specifically for. Can be null if this SimpleLogger instance is for all instances of sourceClass rather than for a particular instance (this is the norm).

SimpleLogger

public SimpleLogger(SimpleLog log,
                    java.lang.Class sourceClass,
                    boolean useLongName)

Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

This constructor is the equivalent of calling:
new SimpleLogger(SimpleLog.defaultInstance(), sourceClass, null, useLongName)

Parameters:

log - the SimpleLog instance that this SimpleLogger should log to and be configured by.

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

useLongName - A boolean indicating whether the fully-qualified name of the specified class should be printed in each message (when set to true), or just the name of the class within it's package (ie. the package will not be printed when set to false).

SimpleLogger

public SimpleLogger(SimpleLog log,
                    java.lang.Class sourceClass,
                    java.lang.Object instanceId,
                    boolean useLongName)

Creates a new SimpleLogger for the specified Class that will log to, and be configured by, the provided SimpleLog.

Parameters:

log - the SimpleLog instance that this SimpleLogger should log to and be configured by.

sourceClass - The class that this SimpleLogger object is for, the name of which will be printed out as part of every message.

instanceId - An object uniquely identifying the instance of sourceClass that this SimpleLogger is specifically for. Can be null if this SimpleLogger instance is for all instances of sourceClass rather than for a particular instance (this is the norm).

useLongName - A boolean indicating whether the fully-qualified name of the specified class should be printed in each message (when set to true), or just the name of the class within it's package (ie. the package will not be printed when set to false).

Method Detail

isInstanceDebugger

public boolean isInstanceDebugger()

Returns true if this SimpleLogger is a logger for one instance of the source class rather than for the class as a whole.

getInstanceID

public java.lang.Object getInstanceID()

Returns the #instanceId of this SimpleLogger, or null if it does not have one (i.e. it is a class logger, not an instance logger).

setInstanceID

public void setInstanceID(java.lang.Object instanceId)

Sets the #instanceId of this SimpleLogger instance.

Throws:

java.lang.IllegalArgumentException - if instanceId is null

java.lang.IllegalStateException - if this SimpleLogger is for a class, not an instance. (See the javadoc for the class for more information.)

getConfigName

public java.lang.String getConfigName()

Returns this SimpleLogger's config name, the name used to specify and look up its configuration.

Currently, the config name is the fully-qualified name of the source class of the logger, plus, if the logger is an instance logger, a period ('.') followed by the string representation (toString()) of the logger's instance ID. Additionally, any dollar signs appearing in the name are changed to periods.

getDebugLevel

public DebugLevel getDebugLevel()

Returns the current debug level of this SimpleLogger.

wouldLog

public boolean wouldLog(DebugLevel level)

A convenience method for testing whether a message logged at the specified level would be logged by this SimpleLogger.

Parameters:

level - the level of the hypothetical message being logged

Returns:

true if a message at the specified level would be logged given this SimpleLogger's current log level, false if it would not.

See Also:

getDebugLevel(), DebugLevel#shouldLog

setDebugLevel

public void setDebugLevel(DebugLevel debugLevel)

Sets the current debug level of this SimpleLogger.

Parameters:

debugLevel - the new debug level

Throws:

java.lang.IllegalArgumentException - if debugLevel is null.

isTracing

public boolean isTracing()

Returns whether this SimpleLogger is currently reporting tracing or not.

Returns:

true if this logger is reporting tracing, false otherwise.

setTracing

public void setTracing(boolean tracing)

Sets this SimpleLogger's tracing flag.

Parameters:

tracing - true if this logger should report tracing, false if it should not.

getSourceClass

public java.lang.Class getSourceClass()

Returns the source class of this SimpleLogger.

fatal

public void fatal(java.lang.String message)

Logs a debug message at the Fatal level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

error

public void error(java.lang.String message)

Logs a debug message at the Error level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

warn

public void warn(java.lang.String message)

Logs a debug message at the Warn level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

info

public void info(java.lang.String message)

Logs a debug message at the Info level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

debug

public void debug(java.lang.String message)

Logs a debug message at the Debug level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

verbose

public void verbose(java.lang.String message)

Logs a debug message at the Verbose level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

ludicrous

public void ludicrous(java.lang.String message)

Logs a debug message at the Ludicrous level.

Parameters:

message - the message to log.

See Also:

db(org.grlea.log.DebugLevel, java.lang.String)

db

public void db(DebugLevel level,
               java.lang.String message)

Logs a simple debug message.

The message will be printed if the given debug level is less than or equal to the current debug level of this SimpleLogger.

Parameters:

message - The debug message to print.

See Also:

fatal(java.lang.String), error(java.lang.String), warn(java.lang.String), info(java.lang.String), debug(java.lang.String), verbose(java.lang.String)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                java.lang.Object value)

Logs a message containing an object's name and value.

The object name and value will be printed only if the given debug level is less than or equal to the current debug level of this SimpleLogger.

Note that, if the given object is an instance of Object[], byte[] or char[], this method will route the call to the corresponding variation of dbo() (each of which performs special formatting for the particualr type), eliminating the need to perform pre-logging type checks and casts.

Note that passing a Throwable to this method does not behave in the same way as dbe(org.grlea.log.DebugLevel, java.lang.Throwable). I.e. passing an exception in as the object value will not result in a stack trace being printed.

Parameters:

objectName - The name of the object whose value is being given.

value - The value of the object.

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                java.lang.Object[] val)

Logs a message containing an object array's name and value.

The array name and value will be printed only if the given debug level is less than or equal to the current debug level of this SimpleLogger.

Parameters:

objectName - The name of the array whose value is being given.

val - The array.

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                short val)

Logs a message containing a short's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                int val)

Logs a message containing an int's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                long val)

Logs a message containing a long's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                boolean val)

Logs a message containing a boolean's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                float val)

Logs a message containing a float's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                double val)

Logs a message containing a double's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                byte val)

Logs a message containing a byte's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                byte[] val)

Logs a message containing a byte array's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                char val)

Logs a message containing a char's name and value.

See Also:

dbo(DebugLevel,String,Object)

dbo

public void dbo(DebugLevel level,
                java.lang.String objectName,
                char[] val)

Logs a message containing a char array's name and value.

See Also:

dbo(DebugLevel,String,Object)

infoObject

public void infoObject(java.lang.String objectName,
                       java.lang.Object val)

Convenience method for logging an object's name and value at the Info level.

See Also:

dbo(DebugLevel,String,Object)

infoObject

public void infoObject(java.lang.String objectName,
                       boolean val)

Convenience method for logging a boolean's name and value at the Info level.

See Also:

dbo(DebugLevel,String,boolean)

infoObject

public void infoObject(java.lang.String objectName,
                       int val)

Convenience method for logging an int's name and value at the Info level.

See Also:

dbo(DebugLevel,String,int)

debugObject

public void debugObject(java.lang.String objectName,
                        java.lang.Object val)

Convenience method for logging an object's name and value at the Debug level.

See Also:

dbo(DebugLevel,String,Object)

debugObject

public void debugObject(java.lang.String objectName,
                        boolean val)

Convenience method for logging a boolean's name and value at the Debug level.

See Also:

dbo(DebugLevel,String,boolean)

debugObject

public void debugObject(java.lang.String objectName,
                        int val)

Convenience method for logging an int's name and value at the Debug level.

See Also:

dbo(DebugLevel,String,int)

verboseObject

public void verboseObject(java.lang.String objectName,
                          java.lang.Object val)

Convenience method for logging an object's name and value at the Verbose level.

See Also:

dbo(DebugLevel,String,Object)

verboseObject

public void verboseObject(java.lang.String objectName,
                          boolean val)

Convenience method for logging a boolean's name and value at the Verbose level.

See Also:

dbo(DebugLevel,String,boolean)

verboseObject

public void verboseObject(java.lang.String objectName,
                          int val)

Convenience method for logging an int's name and value at the Verbose level.

See Also:

dbo(DebugLevel,String,int)

ludicrousObject

public void ludicrousObject(java.lang.String objectName,
                            java.lang.Object val)

Convenience method for logging an object's name and value at the Ludicrous level.

See Also:

dbo(DebugLevel,String,Object)

ludicrousObject

public void ludicrousObject(java.lang.String objectName,
                            boolean val)

Convenience method for logging a boolean's name and value at the Ludicrous level.

See Also:

dbo(DebugLevel,String,boolean)

ludicrousObject

public void ludicrousObject(java.lang.String objectName,
                            int val)

Convenience method for logging an int's name and value at the Ludicrous level.

See Also:

dbo(DebugLevel,String,int)

dbe

public void dbe(DebugLevel level,
                java.lang.Throwable t)

Logs a message containing an exception (or throwable).

The exception will be printed only if the given debug level is less than or equal to the current debug level of this SimpleLogger. This method will result in the stack trace of the exception being printed if this option is turned on in the properties (which it is by default).

Parameters:

t - the throwable to log.

fatalException

public void fatalException(java.lang.Throwable t)

Convenience method for logging an exception (or throwable) at the Fatal level.

See Also:

dbe(DebugLevel,Throwable)

errorException

public void errorException(java.lang.Throwable t)

Convenience method for logging an exception (or throwable) at the Error level.

See Also:

dbe(DebugLevel,Throwable)

warnException

public void warnException(java.lang.Throwable t)

Convenience method for logging an exception (or throwable) at the Warn level.

See Also:

dbe(DebugLevel,Throwable)

entry

public void entry(java.lang.String methodName)

Logs an entry message.

The message will be printed only if the this SimpleLogger's tracing flag is set to true.

Parameters:

methodName - The method name to include in the entry message.

exit

public void exit(java.lang.String methodName)

Logs an exit message.

The message will be printed only if the this SimpleLogger's tracing flag is set to true.