org.openscience.cdk.tools

Interface ILoggingTool

All Known Implementing Classes:

LoggingTool, SystemOutLoggingTool

public interface ILoggingTool

Useful for logging messages. Often used as a class static variable instantiated like (see LoggingToolFactory):

 public class SomeClass {
   private static ILoggingTool logger;

   static {
     logger = LoggingToolFactory.createLoggingTool(SomeClass.class);
   }
 }
 

There is no special reason not to make the logger private and static, as the logging information is closely bound to one specific Class, not subclasses and not instances.

The logger has five logging levels:

DEBUG

Default mode. Used for information you might need to track down the cause of a bug in the source code, or to understand how an algorithm works.

WARNING

This indicates a special situation which is unlike to happen, but for which no special actions need to be taken. E.g. missing information in files, or an unknown atom type. The action is normally something user friendly.

INFO

For reporting informative information to the user that he might easily disregard. Real important information should be given to the user using a GUI element.

FATAL

This level is used for situations that should not have happened *and* that lead to a situation where this program can no longer function (rare in Java).

ERROR

This level is used for situations that should not have happened *and* thus indicate a bug.

Consider that the debugging will not always be turned on. Therefore, it is better not to concatenate string in the logger.debug() call, but have the ILoggingTool do this when appropriate. In other words, use:

 logger.debug("The String X has this value: ", someString);
 logger.debug("The int Y has this value: ", y);
 

instead of:

 logger.debug("The String X has this value: " + someString);
 logger.debug("The int Y has this value: " + y);
 

For logging calls that require even more computation you can use the isDebugEnabled() method:

 if (logger.isDebugEnabled()) {
   logger.info("The 1056389822th prime that is used is: ",
     calculatePrime(1056389822));
 }
 

In addition to the methods specific in the interfance, implementations must also implement the static method create(Class<?>) which can be used by the LoggingToolFactory to instantiate the implementation.

Source code:

master

Belongs to CDK module:

interfaces

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_STACK_LENGTH Default number of StackTraceElements to be printed by debug(Exception).

Method Summary

Methods

Modifier and Type	Method and Description
void	debug(Object object) Shows DEBUG output for the Object.
void	debug(Object object, Object... objects) Shows DEBUG output for the given Object's.
void	dumpClasspath() Outputs the system property for java.class.path.
void	dumpSystemProperties() Outputs system properties for the operating system and the java version.
void	error(Object object) Shows ERROR output for the Object.
void	error(Object object, Object... objects) Shows ERROR output for the given Object's.
void	fatal(Object object) Shows FATAL output for the Object.
void	info(Object object) Shows INFO output for the Object.
void	info(Object object, Object... objects) Shows INFO output for the given Object's.
boolean	isDebugEnabled() Use this method for computational demanding debug info.
void	setStackLength(int length) Sets the number of StackTraceElements to be printed in DEBUG mode when calling debug(Throwable).
void	warn(Object object) Shows WARN output for the Object.
void	warn(Object object, Object... objects) Shows WARN output for the given Object's.

Field Detail

DEFAULT_STACK_LENGTH

static final int DEFAULT_STACK_LENGTH

Default number of StackTraceElements to be printed by debug(Exception).

See Also:

Constant Field Values

Method Detail

dumpSystemProperties

void dumpSystemProperties()

Outputs system properties for the operating system and the java version. More specifically: os.name, os.version, os.arch, java.version and java.vendor.

setStackLength

void setStackLength(int length)

Sets the number of StackTraceElements to be printed in DEBUG mode when calling debug(Throwable). The default value is DEFAULT_STACK_LENGTH.

Parameters:

length - the new stack length

See Also:

DEFAULT_STACK_LENGTH

dumpClasspath

void dumpClasspath()

Outputs the system property for java.class.path.

debug

void debug(Object object)

Shows DEBUG output for the Object. If the object is an instanceof Throwable it will output the trace. Otherwise it will use the toString() method.

Parameters:

object - Object to apply toString() too and output

debug

void debug(Object object,
         Object... objects)

Shows DEBUG output for the given Object's. It uses the toString() method to concatenate the objects.

Parameters:

object - Object to apply toString() too and output

objects - Object... to apply toString() too and output

error

void error(Object object)

Shows ERROR output for the Object. It uses the toString() method.

Parameters:

object - Object to apply toString() too and output

error

void error(Object object,
         Object... objects)

Shows ERROR output for the given Object's. It uses the toString() method to concatenate the objects.

Parameters:

object - Object to apply toString() too and output

objects - Object... to apply toString() too and output

fatal

void fatal(Object object)

Shows FATAL output for the Object. It uses the toString() method.

Parameters:

object - Object to apply toString() too and output

info

void info(Object object)

Shows INFO output for the Object. It uses the toString() method.

Parameters:

object - Object to apply toString() too and output

info

void info(Object object,
        Object... objects)

Shows INFO output for the given Object's. It uses the toString() method to concatenate the objects.

Parameters:

object - Object to apply toString() too and output

objects - Object... to apply toString() too and output

warn

void warn(Object object)

Shows WARN output for the Object. It uses the toString() method.

Parameters:

object - Object to apply toString() too and output

warn

void warn(Object object,
        Object... objects)

Shows WARN output for the given Object's. It uses the toString() method to concatenate the objects.

Parameters:

object - Object to apply toString() too and output

objects - Object... to apply toString() too and output

isDebugEnabled

boolean isDebugEnabled()

Use this method for computational demanding debug info. For example:

 if (logger.isDebugEnabled()) {
   logger.info("The 1056389822th prime that is used is: ",
                calculatePrime(1056389822));
 }
 

Returns:

true, if debug is enabled