Projects‎ > ‎

Logging

Introduction

This design document describes the new OpenPTK Logging centralized service to be used by all OpenPTK objects to log messages of different logging levels.  The initial implementation will log to the levels of:

  • ERROR
  • WARNING
  • INFO (default)

In general, the Java Logger utilities makes use of 7 different levels of logging and these may be used in future releases if requested.

The OpenPTK Logger also includes the ability to manage several logging instances at one time.  When an OpenPTK LoggingIF is created, a name can be used to refer to that instance at a later time.

Requirements

Creating a new logging instance

When a logging instance (LoggingIF) is created, a name can be given to it at that time.  If no name is passed to the LoggingIF constructor, then the name used will be Logger.DEFAULT (currently set to DEFAULT).

Example LoggingIF Create
Description 

new SimpleLogger("JDBC", "/var/tmp/jdbc-connection.log")

This example will create a SimpleLogger() that writes messages to the file "/var/tmp/jdbc-connection.log".  To log messages to it, the logging id of "JDBC" will be used.

Logging a Message

The basic requirements is to support an easy to use logging mechanism that can be called with 1 line of code to emit logging messages.  The 4 logging methods that will be implemented for OpenPTK 2.0 include:

OpenPTK Logging Method
Description 

Logger.logError("...")

Emits the passed message to the Logger at logging level of ERROR.  These messages should represent messages that are of a urgent nature that pertain to system errors or failures.

In this case (as opposed to the next line), since no logging name is used, the "DEFAULT" logging id will be used to log this message. 

Logger.logError("JDBC", "...")

Same logging method as line above, except the logging instance refer to as "JDBC" will be used.

Note: The same example can be used for all other logging methods. 

Logger.logWarning("...")

Emits the passed message to the Logger at logging level of WARNING.  These messages should represent messages that communicate a potential problem or missing data. 

Logger.logInfo("...")

Emits the passed message to the Logger at logging level of INFO.  These messages are purely informational and used for debugging reasons.  In future releases, these messages will most likely be broken out to other more granular levels (i.e. DEBUG, FINE, FINER, FINEST) 

Logger.log("...")

Emits the passed message to the Logger at logging level of INFO.  Although INFO isn't specified, this is the default logging level if no specific level is called.

Usage

The usage of the Logger is intended to be extremely simple to use.  At any place withing some Java code, the developer should not be required to set anything up.  The only thing they need to do is simply call the log....() message on the Logger.  See example below:

import org.openptk.logging.Logger;

  ...
  Logger.logInfo("HelloWorld!");
  ...

By default, the logger is initialized with an OpenPTK SysoutLogger() which simply emits messages to the standard SYSOUT for that platform.  Other optional Loggers available with OpenPTK include:

  • JavaLogger
  • SimpleLogger (extends JavaLogger with no changes)
  • AtomicLogger (extends JavaLogger.  Every log message emitted will open/close the log file, making every log message an atomic operation)

An example of setting up a new CustomLogger is shown below:

import org.openptk.logging.Logger;
import org.openptk.logging.LoggingIF;
import ....CustomLogger;             // Written by developer (must implement LoggingIF)

...
{
   ...
   LoggingIF  myLogger = new CustomLogger(...);

   Logger.setLogger(myLogger);

   Logger.logInfo("HelloWorld! Using the new CustomLogger()");
}

Architecture

Configuration

openptk.xml

OpenPTK Logging is defined it the openptk.xml file.  The components that define the logging facility is shown below.

Loggers.Properties

<Loggers default="UnixLogFile">
  <Logger id="UnixLogFile" classname="org.openptk.provision.logging.AtomicLogger">
   ...
  </Logger>
  ...
</Loggers>

Attributes

Name Required Description Example
default Yes Specifies the default logger to use, from the list of available loggers.  This value should be one of the id's from the available loggers.
default="UnixLogFile"

Arguments

Name Required Description Example
id Yes A unique identifier for the Logger id="MyLogger"
classname Yes The fully qualified classname that implements the Loggin interface. classname="org.openptk.provision.logging.AtomicLogger"

Loggers.Logger.Properties

Properties that are used by the Logger.

Syntax

<Properties>
  <Property name="file" value="/var/tmp/openptk.log"/>
</Properties>

Arguments

Name Required Description Example
name Yes The name of the Property name="foo"
value Yes The value of the Property value="bar"

Implementation Notes

This is being tracked by OpenPTK Issue OPENPTK-220 .  The major steps to completing this issue are identified below.

  • Remove the subclass of Component for existing Loggers (SimpleLogger and AtomicLogger)
  • Add an abstract Logging.java class that implements the majority of current methods in SimpleLogger and AtomicLogger
  • Implement a SysoutLogger that will emit all messages to sysout.  This logger will be used should there be a non-existent or invalid logger in the openptk.xml configuration.
  • Implement a Logger.java singleton class with the 4 main methods as described above.
  • Begin the replacement of all logging calls in OpenPTK with the new Logger class.