org.peace_tools.generic
Class Log

java.lang.Object
  org.peace_tools.generic.Log

Direct Known Subclasses:

ProgrammerLog, UserLog

public abstract class Log
extends java.lang.Object

This is an abstract base class that provides the core features for managing log entries. The logging system has been developed using the Model-View-Controller (MVC) pattern. This class represents the core component of the "Model" that provides the data needed by the "Views" for display purposes. The corresponding "View" class is the LogPane. The top-level Frame that contains the views acts as the "Controller".

This base class provides the following features:

• It provides a generic place holder that is used by UserLog and ProgrammerLog classes to store log information.
• It provides a mechanism for enabling and disabling saving the logs to a given log file.

Nested Class Summary

static class

Log.LogLevel This enumeration provides a convenient mechanism for referring to different error levels when generating logs.

Field Summary

protected Log.LogLevel	currentLogLevel The current log level at which log messages are being generated.
protected javax.swing.event.EventListenerList	listeners The list of log listeners that are interested in receiving call back information whenever log information changes.
protected java.io.PrintStream	logFile The log file stream to which the data is currently being written as logs are being generated.
protected java.lang.String	logFileName The file we are writing to (if any).

Constructor Summary

protected

Log(Log.LogLevel logLevel, java.lang.String fileName) A constructor for the Log.

Method Summary

void	addLogListener(LogListener listener) Adds a log listener (typically a view derived off of LogPane) to the set of listeners to be notified whenever log information changes.
void	clearLog() This method clears the log and writes a special message to the PrintStream, if one exists.
static Log.LogLevel	decode(char code) Utility method to convert an encoded log level character (obtained via a call to the encode() method) to corresponding LogLevel enumeration value.
static char	encode(Log.LogLevel level) Utility method to convert a log level to a single character value.
java.lang.String	getFileName() Obtain the name of the file to which the user logs are being written.
Log.LogLevel	getLevel() Retrieves the current logging level.
boolean	isWritingLogs() Determine if logs are actually being written to a log file.
protected void	notifyViews(boolean logChanged, boolean fileNameChanged, boolean levelChanged) This is a helper method that is used to dispatch a call back to all interested listeners about the change in log information.
void	parseLevel(java.lang.String level) Parses a string containing a valid logging level and sets the level appropriately.
void	removeLogListener(LogListener listener) Removes a log listener (typically a view derived off of LogPane) from the set of listeners to be notified whenever log information changes.
boolean	setFileName(java.lang.String file) Set a file to which user logs are to be written for persistent storage.
void	setLevel(Log.LogLevel level) Sets the Logging level to the specified level.
void	toggleLogWriting() method to start/stop writing logs to the given log file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

currentLogLevel

protected Log.LogLevel currentLogLevel

The current log level at which log messages are being generated. Typically this value is set to LogLevel.NOTICE.

logFileName

protected java.lang.String logFileName

The file we are writing to (if any). The log file is typically set each time the program is launched.

logFile

protected java.io.PrintStream logFile

The log file stream to which the data is currently being written as logs are being generated. The file is opened and closed depending on whether the log is to be persisted or not.

listeners

protected javax.swing.event.EventListenerList listeners

The list of log listeners that are interested in receiving call back information whenever log information changes.

Constructor Detail

Log

protected Log(Log.LogLevel logLevel,
              java.lang.String fileName)

A constructor for the Log. It merely initializes all the instance variables to their default initial value.

Parameters:

logLevel - The initial/default Log level for the log messages.

fileName - An optional log file name to log to. This can be null.

Method Detail

setLevel

public void setLevel(Log.LogLevel level)

Sets the Logging level to the specified level.

Parameters:

level - The new level at which log entries must be recorded.

notifyViews

protected void notifyViews(boolean logChanged,
                           boolean fileNameChanged,
                           boolean levelChanged)

This is a helper method that is used to dispatch a call back to all interested listeners about the change in log information. This method is invoked by other methods in this class whenever the log information changes. This method walks the list of LogListener objects in the listeners list and invokes the logChanged() API method to dispatch notifications.

Parameters:

logChanged - This parameter is true if log entries were added or removed from the logs. Typically this is the common scenario for the call back to occur.

fileNameChanged - This parameter is true if the file name into which logs are written was changed by the user (via some view).

levelChanged - This parameter is true if the current logging level set for the log was changed by the user (via some view).

addLogListener

public void addLogListener(LogListener listener)

Adds a log listener (typically a view derived off of LogPane) to the set of listeners to be notified whenever log information changes.

Parameters:

listener - The listener to be notified on changes to the log.

removeLogListener

public void removeLogListener(LogListener listener)

Removes a log listener (typically a view derived off of LogPane) from the set of listeners to be notified whenever log information changes.

Parameters:

listener - The listener to be removed from the list of listeners interested in receiving log updates.

getLevel

public Log.LogLevel getLevel()

Retrieves the current logging level.

Returns:

The current logging level at which log entries are being recorded. Log entries below this specified level of severity are not recorded.

parseLevel

public void parseLevel(java.lang.String level)

Parses a string containing a valid logging level and sets the level appropriately.

Parameters:

level - The String to parse and convert to a suitable Enum value. This method throws an IllegalArgumentException if the level string is an invalid log level.

clearLog

public void clearLog()

This method clears the log and writes a special message to the PrintStream, if one exists.

setFileName

public boolean setFileName(java.lang.String file)

Set a file to which user logs are to be written for persistent storage. This method can be used to set a file to which the user logs are to be written for future reference.

Note:This method closes the existing log if one is open already.

Parameters:

file - The name of the file to which the user logs are to be written for permanent storage. If this parameter is null then any open log stream is closed and a new file is not opened.

Returns:

This method returns true if the operation was sucessful. On errors this method returns false.

getFileName

public java.lang.String getFileName()

Obtain the name of the file to which the user logs are being written. If a valid file name is not set then this method returns null.

Returns:

The name of the file to which user logs are being written.

isWritingLogs

public boolean isWritingLogs()

Determine if logs are actually being written to a log file. This method can be used to determine if the logs are currently being written to a log file.

Returns:

This method returns true if the logs are being written to the file indicated by logFileName.

toggleLogWriting

public void toggleLogWriting()

method to start/stop writing logs to the given log file. This method can be used to enable/disable writing data to a log file.

encode

public static char encode(Log.LogLevel level)

Utility method to convert a log level to a single character value. This method is used by the UserLog to combine log entries together to store information in a more compact form.

Parameters:

level - The level that must be encoded to a single character.

Returns:

A single character representing the log level.

decode

public static Log.LogLevel decode(char code)

Utility method to convert an encoded log level character (obtained via a call to the encode() method) to corresponding LogLevel enumeration value. This method is used by the UserLog to combine log entries together to store information in a more compact form.

Parameters:

code - A single character level code to be translated to corresponding log level.

Returns:

The log level enumeration representing the single character encoding for the log level.