Package org.openscience.cdk.tools

Interface ILoggingTool

All Known Implementing Classes:
SystemOutLoggingTool
public interface ILoggingTool
Useful for logging messages. Recommended to be used as a private static variable instantiated using LoggingToolFactory.createLoggingTool(Class): 
 public class SomeClass {
   private static ILoggingTool logger = LoggingToolFactory.createLoggingTool(SomeClass.class);
 }

The logger has six logging levels:

TRACE
Emits the largest number of log entries.
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.
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.
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.
ERROR
This level is used for situations that should not have happened *and* thus indicate a bug.
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).

Logging library might implement less logging levels than the six levels defined here. This may result in logging levels being merged. For example, slf4j has five logging levels. Logging level fatal is not supported so that calls to error and fatal are both logged with slf4j logging level error.

Consider that 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 interface, implementations must also implement the static method create(Class<?>) which is called by LoggingToolFactory to instantiate the implementation.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEBUG
    Debug, Info, Warn, Error, and Fatal messages will be emitted.
    static final int
    DEFAULT_STACK_LENGTH
    Default number of StackTraceElements to be printed by debug(Exception).
    static final int
    ERROR
    Error, and Fatal messages will be emitted.
    static final int
    FATAL
    Only Fatal messages will be emitted.
    static final int
    INFO
    Info, Warn, Error, and Fatal messages will be emitted.
    static final int
    OFF
    Logging is OFF
    static final int
    TRACE
    Trace, Debug, Info, Warn, Error, and Fatal messages will be emitted.
    static final int
    WARN
    Warn, Error, and Fatal messages will be emitted.

  • Method Summary

    Modifier and Type
    Method
    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.
    int
    getLevel()
    Get the current level of this logger.
    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
    setLevel(int level)
    Set the level of this logger.
    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 Details

    • TRACE

      static final int TRACE
      Trace, Debug, Info, Warn, Error, and Fatal messages will be emitted.
      See Also:

    • DEBUG

      static final int DEBUG
      Debug, Info, Warn, Error, and Fatal messages will be emitted.
      See Also:

    • INFO

      static final int INFO
      Info, Warn, Error, and Fatal messages will be emitted.
      See Also:

    • WARN

      static final int WARN
      Warn, Error, and Fatal messages will be emitted.
      See Also:

    • ERROR

      static final int ERROR
      Error, and Fatal messages will be emitted.
      See Also:

    • FATAL

      static final int FATAL
      Only Fatal messages will be emitted.
      See Also:

    • OFF

      static final int OFF
      Logging is OFF
      See Also:

    • DEFAULT_STACK_LENGTH

      static final int DEFAULT_STACK_LENGTH
      Default number of StackTraceElements to be printed by debug(Exception).
      See Also:

  • Method Details

    • 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:

    • 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() to 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() to and output
      objects - Object... to apply toString() to and output

    • error

      void error(Object object)
      Shows ERROR output for the Object. It uses the toString() method.
      Parameters:
      object - Object to apply toString() to 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() to and output
      objects - Object... to apply toString() to and output

    • fatal

      void fatal(Object object)
      Shows FATAL output for the Object. It uses the toString() method.
      Parameters:
      object - Object to apply toString() to and output

    • info

      void info(Object object)
      Shows INFO output for the Object. It uses the toString() method.
      Parameters:
      object - Object to apply toString() to 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() to and output
      objects - Object... to apply toString() to and output

    • warn

      void warn(Object object)
      Shows WARN output for the Object. It uses the toString() method.
      Parameters:
      object - Object to apply toString() to 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() to and output
      objects - Object... to apply toString() to 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

    • setLevel

      void setLevel(int level)
      Set the level of this logger. The level is provided in one of the constants: TRACE, DEBUG, INFO, WARN , ERROR, FATAL. After setting the level only messages above the specified level will be emitted.
      Parameters:
      level - the level

    • getLevel

      int getLevel()
      Get the current level of this logger. The level is provided in one of the constants: TRACE, DEBUG, INFO, WARN , ERROR, FATAL.
      Returns:
      the current level