Using Commons Logging

To use Commons Logging in a Java class:

1) Import the commons logging classes

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

2) Create a static variable to hold the logger. In the Java class, add the following:

private static final Log log = LogFactory.getLog( <category> );
private static final boolean isDebugging = log.isDebugEnabled();

<category> is a string representing the logging category, which is an "identifier" used for filtering logging output. A common practice is to use MyClassName.class.getName() for the <category>, thus allowing you to filter by different granularities (org, org.kepler, org.kepler.gui, org.kepelr.gui.MyClassName, etc). Alternatively, if you have multiple classes in the same 'logical category', but in different packages, you can assign them all the same category string. For example, xml/svg icon classes might want to log everything to a single category called "GUI.svg".

3) Call the logger methods to issue a diagnostic message:

log.debug( "Here is a debug message");

or

if (isDebugging) {
  log.error("Error - the file cannot be found: " + fileName);
}

4) Customize the logging output

At runtime, the classpath is searched for the 'log4j.properties' file which is used to customize the logging output.

The 'log4j.properties' file found in the highest module is used when kepler is run.  Typically, kepler/resources/log4j.properties is the file that is read.  To customize the ouput, edit this file.

You can debug using one of five methods, depending on the level of severity:

  log.fatal(String msg);
  log.error(String msg); 
  log.warn(String msg); 
  log.info(String msg); 
  log.debug(String msg);

Severity levels are as follows (in decreasing order of severity and increasing frequency of usage):

FATAL designates very severe error events that will presumably lead the application to abort.
EXAMPLE >> Use this just before you do a System.exit(1)

ERROR designates error events that might still allow the application to continue running.
EXAMPLE >> Use this when you catch an exception

WARN designates potentially harmful situations.
EXAMPLE >> If something happens that isn't critical, but may make the software misbehave

INFO designates informational messages that highlight the progress of the application at coarse-grained level.
EXAMPLE >> When "milestone" events occur. This would be the default level for development when not debugging. Show restraint when using "info" - otherwise printouts cause information overload

DEBUG designates fine-grained informational events that are most useful to debug an application.
EXAMPLE >> use for all other printouts of minutiae that are interesting only to someone who is specifically debugging the app. Preferred level, unless you have a good reason for going higher.

Further Reading

The commons-logging user guide has some suggestions about using code guards when the arguments require computation, and also lists available logging methods. These methods take either an Object (on which it calls toString()), or an Object and a Throwable. The Throwable will be used to print a stack trace, for example:

log.warn(Object message, Throwable t);