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:

• SEVERE (highest value)
• WARNING
• INFO
• CONFIG
• FINE
• FINER
• FINEST (lowest value)
• OFF (turns off logging altoghether)

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.