jpl.eda.io
Class Log

java.lang.Object
  jpl.eda.io.Log

public class Log

extends java.lang.Object

The log. This class represents the application- or applet-wide logging facility. If your application needs to log messages, here's your class.

To log a message, you call one of the get methods of this class to yield a LogWriter object. You can then call methods like LogWriter.println(String) to log a line of text. A typical invocation is

Log.get().println("Buffer of length " + length + " allocated.");

This logs the given text using the default source string, and under the default category, and timestamped with the current time. You can reuse the LogWriter, but the timestamp, source, and category won't change. You should get a fresh LogWriter.

Sources identify independent origins of log messages, such as independent threads in a program, or independent programs. Sources are just strings. If you don't specify a source, you get a default source. You can set the default source with setDefaultSource(java.lang.String). You always get a source with every message, even if it's a default source. If you don't otherwise set a default source string, the source is "app".

Categories identify different classes or priorites of messages. Categories can be simple strings like "warning" or "debug", or they can be complex objects. You get to define your categories. Your group ought to agree on categories, though. If you don't specify a category, you get a default category. You can set the default category with setDefaultCategory(java.lang.Object). If you don't call that method, the default category is the String object "message".

Streams identify independent activities within a program, which often have transient lifespans. They're not separate output streams, but instead are separate, named entities representing separate activities (although a LogListener may put messages into separate output streams identified by each stream). Activity streams are identified by strings. To indicate the start and stop of streams, call startStream(java.lang.String, java.util.Date, java.lang.String) and stopStream(java.lang.String). These send stream-started and stream-stopped events to the log listeners, who may choose to pay attention to them or ignore them. You can use streams to indicate to the log the start and the stop of activities such as an analyst examining the system, or a server handling a particular client.

All messages logged with this class go to one or more LogListener objects. A LogListener accepts logging events, such as a message being logged, and does something with it, such as writing the message to a file. Call addLogListener(jpl.eda.io.LogListener) to add a log listener. Logging of a message, starting a stream, and stopping a stream all get turned into LogEvents and are multicasted to every registered listener.

The logging facility bootstraps itself with one or more log listeners specified by the system property jpl.eda.io.Log.loggers. This property must be a space-separated list of complete class names. The logging facility will create an object of each class listed and add it as if you had called addLogListener. (You can specify system properties on the command line or in the applet tag.)

Author:

Kelly

See Also:

LogListener, LogWriter

Method Summary

static void	addLogListener(LogListener listener) Add a log listener.
static LogWriter	get() Get a writer to log messages.
static LogWriter	get(java.util.Date timestamp, java.lang.String source, java.lang.Object category) Get a writer to log messages.
static LogWriter	get(java.lang.Object category) Get a writer to log messages.
static java.lang.Object	getDefaultCategory() Get the default category.
static java.lang.String	getDefaultSource() Get the default source.
static void	removeLogListener(LogListener listener) Remove a log listener.
static void	setDefaultCategory(java.lang.Object category) Set the default category.
static void	setDefaultSource(java.lang.String source) Set the default source.
static void	startStream(java.lang.String stream, java.util.Date timestamp, java.lang.String source) Start a new log stream.
static void	stopStream(java.lang.String stream) Stop a stream.

Methods inherited from class java.lang.Object

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

Method Detail

get

public static LogWriter get()

Get a writer to log messages. The writer will log messages with the current time, default category, and default source. Messages will go into the general log.

Returns:

A writer with which you can log messages.

get

public static LogWriter get(java.lang.Object category)

Get a writer to log messages. The writer will log messages with the current time, specified category, and default source. Messages will go into the general log.

Parameters:

category - The messages' category.

Returns:

A writer with which you can log messages.

get

public static LogWriter get(java.util.Date timestamp,
                            java.lang.String source,
                            java.lang.Object category)

Get a writer to log messages. The writer will log messages with the specified time, specified category, and specified source.

Parameters:

timestamp - The time for messages logged with the returned writer.

source - The source of the log message.

category - The messages' category.

Returns:

A writer with which you can log messages.

startStream

public static void startStream(java.lang.String stream,
                               java.util.Date timestamp,
                               java.lang.String source)

Start a new log stream. This method notifies the LogListeners that a new logging stream has started.

Parameters:

stream - The name of the stream.

timestamp - The time the stream started. To use the current time, pass a new Date object.

source - A string identifying who or what started the stream.

stopStream

public static void stopStream(java.lang.String stream)

Stop a stream. This method notifies the LogListeners that a logging stream has stopped.

Parameters:

stream - The name of the stream that stopped.

setDefaultSource

public static void setDefaultSource(java.lang.String source)

Set the default source. This sets the default source label used for logging.

Parameters:

source - The new default source label.

getDefaultSource

public static java.lang.String getDefaultSource()

Get the default source.

Returns:

The default source label.

setDefaultCategory

public static void setDefaultCategory(java.lang.Object category)

Set the default category. This sets the category object that's used by default for logging.

Parameters:

category - The new default category object.

getDefaultCategory

public static java.lang.Object getDefaultCategory()

Get the default category.

Returns:

The default category object.

addLogListener

public static void addLogListener(LogListener listener)

Add a log listener. The listener will be notified whenever a message is logged, a stream started, or a stream stopped.

Parameters:

listener - The listener to add.

removeLogListener

public static void removeLogListener(LogListener listener)

Remove a log listener. The listener won't receive anymore events unless it's added back.

Parameters:

listener - The listener to remove.