com.hp.hpl.jena.util
Class Log

java.lang.Object
  |
  +--com.hp.hpl.jena.util.Log

public class Log
extends java.lang.Object

Simple logging abstraction for use within the Jena core. We have a general need to log debug and diagnostic information, but we don't want to introduce another dependency for Jena users by building on, say, Log4J (good though that package is). Furthermore, the upcoming JDK 1.4 release will contain a standard logging API java.util.logging. We won't standardise on this API, since that would require all Jena users to upgrade to a new JDK release. However, this class is designed so that users who want to can interface this simple logger to more sophisticated mechanisms, including the new standard.

Following common practice among logging packages, a number of levels of severity are defined. Each log call is at one of these levels, and the logger has a state variable that indicates the lowest level it will accept. Log entries at this level or higher will be logged, those below this level will be silently ignored. The levels are taken from the new java.util.logging API:

In addition, for compatability with other packages, DEBUG is defined as an alias for FINE.

While the JDK 1.4 logger contains a great deal of flexibility for directing output to different destinations, formatting, and localising, this class has deliberately much simpler capabilities. A log handler interface is defined (see LogHandler), which can publish a log message as it sees fit. This logger supports the use of a single log handler at a time, which will consume all log messages. Two standard handlers are defined, one for console output via System.err, and one for outputting to a file. However, another log handler, with arbitrary formatting capability, can be defined via setHandler(com.hp.hpl.jena.util.LogHandler).

There is one global logger, implemented via a singleton pattern. Convenience static methods are provided for programmers to have simple access to logging capability.

Basic usage patterns:
Log a warning to the default output (console):

     Log.warning( "Frimble count below threshold: " + nFrimbles );
 
Direct log output to a file, and log a severe level exception (with stacktrace):
     Log.getInstance().setDefaultFileHandler();
     Log.severe( "IOException while frimbling: " + frimEx, frimEx );
 
Debug output, without timestamp:
     Log.getInstance().setShowDate( false );
     Log.getInstance().setLevel( Log.FINE );
     Log.debug( "Frimble count: " + nFrimbles,
                Frimbler.class.getName(), "countFrimbles" );
 

Version:
CVS info: $Id: Log.java,v 1.3 2001/08/31 15:04:51 ijd Exp $
Author:
Ian Dickinson, HP Labs (email)

Field Summary
static int CONFIG
          Message level, representing the level below INFO
static int DEBUG
          Convenience alias for FINE
static int DEFAULT_LEVEL
          The default message level for the logger (CONFIG)
static java.lang.String DEFAULT_LOG_FILE_NAME
          The default file name for the Jena log file
static int FINE
          Message level, representing the level below CONFIG
static int FINER
          Message level, representing the level below FINE
static int FINEST
          Message level, representing the lowest level (least important) messages
static int INFO
          Message level, representing the level below WARNING
static java.lang.String[] LEVEL_NAMES
          Set of names corresponding to the well-known levels
static int OFF
          Message level used to suppress all messages.
static int SEVERE
          Message level, representing the highest level (most important) messages
static int WARNING
          Message level, representing the level below SEVERE
 
Method Summary
static void config(java.lang.String msg)
          Log the given message at log level CONFIG.
static void config(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level CONFIG.
static void config(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level CONFIG.
static void config(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level CONFIG.
static void debug(java.lang.String msg)
          Log the given message at log level DEBUG (alias FINE).
static void debug(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level DEBUG (alias FINE).
static void debug(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level DEBUG (alias FINE).
static void debug(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level DEBUG (alias FINE).
static void fine(java.lang.String msg)
          Log the given message at log level FINE.
static void fine(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level FINE.
static void fine(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level FINE.
static void fine(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level FINE.
static void finer(java.lang.String msg)
          Log the given message at log level FINER.
static void finer(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level FINER.
static void finer(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level FINER.
static void finer(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level FINER.
static void finest(java.lang.String msg)
          Log the given message at log level FINEST.
static void finest(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level FINEST.
static void finest(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level FINEST.
static void finest(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level FINEST.
static java.lang.String formatDate()
          Answer a string representing the date and time, formatted for output to the console.
static Log getInstance()
          Answer a reference to the singleton (global) instance of the logger.
 int getLevel()
          Answer the current logging level.
static java.lang.String getLevelName(int level)
          Answer a readable string for the given level identifier
 boolean getShowDate()
          Answer whether the date is shown in console output.
static void info(java.lang.String msg)
          Log the given message at log level INFO.
static void info(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level INFO.
static void info(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level INFO.
static void info(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level INFO.
 void setConsoleHandler()
          Set the current output handler to one that writes to System.err
 void setDefaultFileHandler()
          Set the current output handler to one that writes to the default log file (see DEFAULT_LOG_FILE_NAME), overwriting any existing contents.
 void setDefaultFileHandler(boolean append)
          Set the current output handler to one that writes to the default log file (see DEFAULT_LOG_FILE_NAME), optionally appending to any existing log file contents.
 void setFileHandler(java.lang.String fileName)
          Set the current output handler to one that writes to the given file, overwriting the current contents, if any.
 void setFileHandler(java.lang.String fileName, boolean append)
          Set the current output handler to one that writes to the given file, optionally appending to the existing contents of the logfile.
 void setHandler(LogHandler handler)
          Set the current output handler to be the given object.
 void setLevel(int level)
          Set the current loggin level to the given value.
 void setShowDate(boolean showDate)
          Set a flag to control whether the date is shown in the console log.
static void severe(java.lang.String msg)
          Log the given message at log level SEVERE.
static void severe(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level SEVERE.
static void severe(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level SEVERE.
static void severe(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level SEVERE.
static void warning(java.lang.String msg)
          Log the given message at log level WARNING.
static void warning(java.lang.String msg, java.lang.String cls, java.lang.String method)
          Log the given message at log level WARNING.
static void warning(java.lang.String msg, java.lang.String cls, java.lang.String method, java.lang.Throwable ex)
          Log the given message at log level WARNING.
static void warning(java.lang.String msg, java.lang.Throwable ex)
          Log the given message at log level WARNING.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SEVERE

public static final int SEVERE
Message level, representing the highest level (most important) messages

WARNING

public static final int WARNING
Message level, representing the level below SEVERE

INFO

public static final int INFO
Message level, representing the level below WARNING

CONFIG

public static final int CONFIG
Message level, representing the level below INFO

FINE

public static final int FINE
Message level, representing the level below CONFIG

FINER

public static final int FINER
Message level, representing the level below FINE

FINEST

public static final int FINEST
Message level, representing the lowest level (least important) messages

OFF

public static final int OFF
Message level used to suppress all messages.

DEBUG

public static final int DEBUG
Convenience alias for FINE

DEFAULT_LOG_FILE_NAME

public static final java.lang.String DEFAULT_LOG_FILE_NAME
The default file name for the Jena log file

DEFAULT_LEVEL

public static final int DEFAULT_LEVEL
The default message level for the logger (CONFIG)

LEVEL_NAMES

public static final java.lang.String[] LEVEL_NAMES
Set of names corresponding to the well-known levels
Method Detail

getInstance

public static final Log getInstance()
Answer a reference to the singleton (global) instance of the logger.
Returns:
the single global log object.

setLevel

public void setLevel(int level)
Set the current loggin level to the given value.
Parameters:
level - The new logging level

getLevel

public int getLevel()
Answer the current logging level.
Returns:
the log level as an integer.

getLevelName

public static java.lang.String getLevelName(int level)
Answer a readable string for the given level identifier
Parameters:
level - The level number
Returns:
the level name

setHandler

public void setHandler(LogHandler handler)
Set the current output handler to be the given object. The old handler will be closed first.
Parameters:
handler - The new output handler.

setDefaultFileHandler

public void setDefaultFileHandler()
                           throws java.io.IOException
Set the current output handler to one that writes to the default log file (see DEFAULT_LOG_FILE_NAME), overwriting any existing contents.
Throws:
Throws - IOException if the default log file cannot be opened for writing.

setDefaultFileHandler

public void setDefaultFileHandler(boolean append)
                           throws java.io.IOException
Set the current output handler to one that writes to the default log file (see DEFAULT_LOG_FILE_NAME), optionally appending to any existing log file contents.
Parameters:
append - If true, append to the end of the existing log file; otherwise overwrite it.
Throws:
Throws - IOException if the default log file cannot be opened for writing.

setFileHandler

public void setFileHandler(java.lang.String fileName)
                    throws java.io.IOException
Set the current output handler to one that writes to the given file, overwriting the current contents, if any.
Parameters:
fileName - The name of the file to write to.
Throws:
java.io.IOException - if the file cannot be opened for writing.

setFileHandler

public void setFileHandler(java.lang.String fileName,
                           boolean append)
                    throws java.io.IOException
Set the current output handler to one that writes to the given file, optionally appending to the existing contents of the logfile.
Parameters:
fileName - The name of the file to write to.
append - If true, append to the end of the file; otherwise overwrite it.
Throws:
java.io.IOException - if the file cannot be opened for writing.

setConsoleHandler

public void setConsoleHandler()
Set the current output handler to one that writes to System.err

setShowDate

public void setShowDate(boolean showDate)
Set a flag to control whether the date is shown in the console log. Default true.
Parameters:
showDate - If true, the date and time will be prepended to console log output.

getShowDate

public boolean getShowDate()
Answer whether the date is shown in console output.
Returns:
true if the date and time are prepended to console output (default true).

formatDate

public static java.lang.String formatDate()
Answer a string representing the date and time, formatted for output to the console.
Returns:
a string encoding the date and time.

severe

public static void severe(java.lang.String msg)
Log the given message at log level SEVERE.
Parameters:
msg - The message text

severe

public static void severe(java.lang.String msg,
                          java.lang.Throwable ex)
Log the given message at log level SEVERE.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

severe

public static void severe(java.lang.String msg,
                          java.lang.String cls,
                          java.lang.String method)
Log the given message at log level SEVERE.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

severe

public static void severe(java.lang.String msg,
                          java.lang.String cls,
                          java.lang.String method,
                          java.lang.Throwable ex)
Log the given message at log level SEVERE.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

warning

public static void warning(java.lang.String msg)
Log the given message at log level WARNING.
Parameters:
msg - The message text

warning

public static void warning(java.lang.String msg,
                           java.lang.Throwable ex)
Log the given message at log level WARNING.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

warning

public static void warning(java.lang.String msg,
                           java.lang.String cls,
                           java.lang.String method)
Log the given message at log level WARNING.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

warning

public static void warning(java.lang.String msg,
                           java.lang.String cls,
                           java.lang.String method,
                           java.lang.Throwable ex)
Log the given message at log level WARNING.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

info

public static void info(java.lang.String msg)
Log the given message at log level INFO.
Parameters:
msg - The message text

info

public static void info(java.lang.String msg,
                        java.lang.Throwable ex)
Log the given message at log level INFO.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

info

public static void info(java.lang.String msg,
                        java.lang.String cls,
                        java.lang.String method)
Log the given message at log level INFO.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

info

public static void info(java.lang.String msg,
                        java.lang.String cls,
                        java.lang.String method,
                        java.lang.Throwable ex)
Log the given message at log level INFO.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

config

public static void config(java.lang.String msg)
Log the given message at log level CONFIG.
Parameters:
msg - The message text

config

public static void config(java.lang.String msg,
                          java.lang.Throwable ex)
Log the given message at log level CONFIG.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

config

public static void config(java.lang.String msg,
                          java.lang.String cls,
                          java.lang.String method)
Log the given message at log level CONFIG.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

config

public static void config(java.lang.String msg,
                          java.lang.String cls,
                          java.lang.String method,
                          java.lang.Throwable ex)
Log the given message at log level CONFIG.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

fine

public static void fine(java.lang.String msg)
Log the given message at log level FINE.
Parameters:
msg - The message text

fine

public static void fine(java.lang.String msg,
                        java.lang.Throwable ex)
Log the given message at log level FINE.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

fine

public static void fine(java.lang.String msg,
                        java.lang.String cls,
                        java.lang.String method)
Log the given message at log level FINE.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

fine

public static void fine(java.lang.String msg,
                        java.lang.String cls,
                        java.lang.String method,
                        java.lang.Throwable ex)
Log the given message at log level FINE.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

finer

public static void finer(java.lang.String msg)
Log the given message at log level FINER.
Parameters:
msg - The message text

finer

public static void finer(java.lang.String msg,
                         java.lang.Throwable ex)
Log the given message at log level FINER.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

finer

public static void finer(java.lang.String msg,
                         java.lang.String cls,
                         java.lang.String method)
Log the given message at log level FINER.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

finer

public static void finer(java.lang.String msg,
                         java.lang.String cls,
                         java.lang.String method,
                         java.lang.Throwable ex)
Log the given message at log level FINER.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

finest

public static void finest(java.lang.String msg)
Log the given message at log level FINEST.
Parameters:
msg - The message text

finest

public static void finest(java.lang.String msg,
                          java.lang.Throwable ex)
Log the given message at log level FINEST.
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

finest

public static void finest(java.lang.String msg,
                          java.lang.String cls,
                          java.lang.String method)
Log the given message at log level FINEST.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

finest

public static void finest(java.lang.String msg,
                          java.lang.String cls,
                          java.lang.String method,
                          java.lang.Throwable ex)
Log the given message at log level FINEST.
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.

debug

public static void debug(java.lang.String msg)
Log the given message at log level DEBUG (alias FINE).
Parameters:
msg - The message text

debug

public static void debug(java.lang.String msg,
                         java.lang.Throwable ex)
Log the given message at log level DEBUG (alias FINE).
Parameters:
msg - The message text.
ex - A throwable (exception or error) that triggered the log event.

debug

public static void debug(java.lang.String msg,
                         java.lang.String cls,
                         java.lang.String method)
Log the given message at log level DEBUG (alias FINE).
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event

debug

public static void debug(java.lang.String msg,
                         java.lang.String cls,
                         java.lang.String method,
                         java.lang.Throwable ex)
Log the given message at log level DEBUG (alias FINE).
Parameters:
msg - The message text.
cls - The class name of the originator of the log event
method - The method name of the originator of the log event
ex - A throwable (exception or error) that triggered the log event.


Copyright 2001 Hewlett-Packard. All Rights Reserved.