Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

tribble.io
Class Logger

java.lang.Object
  extended by tribble.io.Logger
All Implemented Interfaces:
LoggerI, SuspendableWriterI
public class Logger
extends java.lang.Object
implements LoggerI, SuspendableWriterI

Message logger (logging output stream).

A logging output stream is used to write diagnostic log messages to during the execution of one or more programs. Typically, the output stream is a log file on disk that is opened for a given application and execution date.

Since:
2003-01-06
Version:
$Revision: 1.4 $ $Date: 2003/03/10 03:06:42 $
Author:
David R. Tribble, david@tribble.com.
Copyright ©2003 by David R. Tribble, all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.

Field Summary
protected  java.lang.StringBuffer m_buf
          Output text line buffer.
protected  int m_filter
          Maximum message verbosity filtering level.
protected  java.lang.String m_id
          Name of this message logger.
protected  java.io.PrintWriter m_out
          Underlying output stream.
protected  int m_pfx
          Message prefixing bitflags.
protected  java.io.PrintWriter m_sus
          Suspended output stream.
(package private) static java.lang.String REV
          Revision information.
protected static java.lang.String SEV_N_DEBUG
          Severity name: Debug.
protected static java.lang.String SEV_N_ERROR
          Severity name: Error.
protected static java.lang.String SEV_N_FATAL
          Severity name: Fatal (unrecoverable) error.
protected static java.lang.String SEV_N_INFO
          Severity name: Informational.
protected static java.lang.String SEV_N_INTERNAL
          Severity name: Internal (unrecoverable) fatal error.
protected static java.lang.String SEV_N_UNKNOWN
          Severity name: Unknown.
protected static java.lang.String SEV_N_WARNING
          Severity name: Warning.
 
Fields inherited from interface tribble.io.LoggerI
PFX__DFL, PFX_DATE, PFX_LOC, PFX_NONE, PFX_TIME, SEV_DEBUG, SEV_ERROR, SEV_FATAL, SEV_INFO, SEV_INTERNAL, SEV_WARNING
 
Constructor Summary
Logger()
          Default constructor.
Logger(java.io.Writer out)
          Constructor.
 
Method Summary
 void close()
          Close this message logger.
 void debug(int verbos, java.lang.String loc, java.lang.String msg)
          Write a formatted debugging message to this message logger.
 void error(java.lang.String loc, java.lang.String msg)
          Write a formatted error message to this message logger.
 void fatal(java.lang.String loc, java.lang.String msg)
          Write a formatted fatal error message to this message logger.
static Logger getLogger(java.lang.String id)
          Retrieve a named message logger from the global logger list.
 java.lang.String getName()
          Retrieve the name of this message logger.
 java.io.PrintWriter getOutput()
          Retrieve the underlying output stream for this message logger.
 void info(int verbos, java.lang.String loc, java.lang.String msg)
          Write a formatted informational message to this message logger.
 boolean isSuspended()
          Determine if this logging stream is suspended or not.
 void log(int sev, int verbos, java.lang.String loc, java.lang.String msg)
          Write a formatted message to this message logger.
protected  void printMessage(int sev, int verbos, java.lang.String loc, java.lang.String msg)
          Write a formatted message to this message logger.
 void register(java.lang.String id)
          Register this message logger in the global logger list.
protected static void registerLogger(Logger log, java.lang.String id)
          Register a named message logger in the global logger list.
 void resume()
          Resume subsequent output written to this logging stream.
 void setOutput(java.io.Writer out)
          Establish the underlying output stream for this message logger.
 int setPrefix(int pfx)
          Establish the prefixes to be prepended to messages written to this message logger.
 int setVerbosity(int sev, int max)
          Establish the verbosity filtering level for this message logger.
protected static java.lang.String severityToString(int sev)
          Return the string corresponding to a given logging message severity level.
 void suspend()
          Suspend subsequent output written to this logging stream.
 void unregister()
          Unregister this named message logger from the global logger list.
protected static void unregisterLogger(Logger log)
          Unregister a named message logger from the global logger list.
 void warning(int verbos, java.lang.String loc, java.lang.String msg)
          Write a formatted warning message to this message logger.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REV

static final java.lang.String REV
Revision information.

See Also:
Constant Field Values

SEV_N_UNKNOWN

protected static final java.lang.String SEV_N_UNKNOWN
Severity name: Unknown.

See Also:
Constant Field Values

SEV_N_DEBUG

protected static final java.lang.String SEV_N_DEBUG
Severity name: Debug.

See Also:
Constant Field Values

SEV_N_INFO

protected static final java.lang.String SEV_N_INFO
Severity name: Informational.

See Also:
Constant Field Values

SEV_N_WARNING

protected static final java.lang.String SEV_N_WARNING
Severity name: Warning.

See Also:
Constant Field Values

SEV_N_ERROR

protected static final java.lang.String SEV_N_ERROR
Severity name: Error.

See Also:
Constant Field Values

SEV_N_FATAL

protected static final java.lang.String SEV_N_FATAL
Severity name: Fatal (unrecoverable) error.

See Also:
Constant Field Values

SEV_N_INTERNAL

protected static final java.lang.String SEV_N_INTERNAL
Severity name: Internal (unrecoverable) fatal error.

See Also:
Constant Field Values

m_out

protected java.io.PrintWriter m_out
Underlying output stream.

m_sus

protected java.io.PrintWriter m_sus
Suspended output stream.

m_id

protected java.lang.String m_id
Name of this message logger.

m_pfx

protected int m_pfx
Message prefixing bitflags.

m_filter

protected int m_filter
Maximum message verbosity filtering level.

m_buf

protected java.lang.StringBuffer m_buf
Output text line buffer.

Constructor Detail

Logger

public Logger()
Default constructor. This creates a message logger with an initially empty (null) output stream.

Since:
1.1, 2003-01-06
See Also:
setOutput(java.io.Writer)

Logger

public Logger(java.io.Writer out)
Constructor.

Parameters:
out - An output stream to be the underlying output stream for this message logger.
Since:
1.1, 2003-01-06
Method Detail

getLogger

public static Logger getLogger(java.lang.String id)
Retrieve a named message logger from the global logger list.

Parameters:
id - The name that a message logger was registered with.
Returns:
A named logger, or null if no logger was registered with the given name.
Since:
1.3, 2003-03-08
See Also:
register(java.lang.String)

severityToString

protected static java.lang.String severityToString(int sev)
Return the string corresponding to a given logging message severity level.

Parameters:
sev - The severity level of the message, which should be one of the SEV_XXX constants.
Returns:
A string corresponding to the message level sev.
Since:
1.1, 2003-01-06

registerLogger

protected static void registerLogger(Logger log,
                                     java.lang.String id)
Register a named message logger in the global logger list.

Note that if the logger is currently registered with a different name, it will first be unregistered under that name and then re-registered with the new name.

Parameters:
log - A message logger.
id - The name that the message logger is to be registered with.
Throws:
java.lang.NullPointerException - (unchecked) Thrown if log or id is null.
java.lang.IllegalArgumentException - (unchecked) Thrown if a message logger is already registered with the given name.
Since:
1.3, 2003-03-08
See Also:
getLogger(java.lang.String), unregisterLogger(tribble.io.Logger), register(java.lang.String)

unregisterLogger

protected static void unregisterLogger(Logger log)
Unregister a named message logger from the global logger list.

Parameters:
log - A message logger. If the logger has no name or is not currently registered, no operation is performed. Note that the default (unnamed) message logger cannot be unregistered.
Since:
1.3, 2003-03-08
See Also:
close(), registerLogger(tribble.io.Logger, java.lang.String), unregister()

setOutput

public void setOutput(java.io.Writer out)
Establish the underlying output stream for this message logger.

Specified by:
setOutput in interface LoggerI
Parameters:
out - A logging output stream. This can be null. If the stream is not an instance of a java.io.PrintWriter object, one will be created internally.
Since:
1.3, 2003-03-08

getOutput

public java.io.PrintWriter getOutput()
Retrieve the underlying output stream for this message logger.

Specified by:
getOutput in interface LoggerI
Returns:
The underlying output stream for this logging output stream. The stream can be null, which effectively disables logging output for this logger.
Since:
1.1, 2003-01-06

close

public void close()
Close this message logger.

Note that the default (unnamed) message logger cannot be closed.

Although this operation close the underlying output stream for this logger, it does not unregister it. To change the underlying output stream for this logger without closing the current output stream, use setOutput(java.io.Writer) instead of this method.

Note that this method does not throw any checked exceptions, especially java.io.IOException.

Specified by:
close in interface LoggerI
Specified by:
close in interface SuspendableWriterI
Since:
1.1, 2003-01-06
See Also:
setOutput(java.io.Writer), unregister()

suspend

public void suspend()
Suspend subsequent output written to this logging stream.

Output to this stream can be resumed by calling resume().

This method may be called multiple times without any intervening call to resume() without any ill effects.

Specified by:
suspend in interface SuspendableWriterI
Since:
1.4, 2003-03-09
See Also:
resume()

resume

public void resume()
Resume subsequent output written to this logging stream.

Output to this stream can be suspended by calling suspend().

This method may be called multiple times without any previous or intervening call to suspend() without any ill effects.

Specified by:
resume in interface SuspendableWriterI
Since:
1.4, 2003-03-09
See Also:
suspend()

isSuspended

public boolean isSuspended()
Determine if this logging stream is suspended or not.

Specified by:
isSuspended in interface SuspendableWriterI
Returns:
True if this logging stream is currently suspended, otherwise false.
Since:
1.4, 2003-03-09
See Also:
suspend()

getName

public java.lang.String getName()
Retrieve the name of this message logger.

Returns:
The name of this logger, which may be null. If the logger is registered in the global logger list, this is the name with which it was registered. Note that the default (unnamed) message logger has an empty name ("").
Since:
1.3, 2003-03-08

register

public void register(java.lang.String id)
Register this message logger in the global logger list.

Note that if this logger is currently registered with a different name, it will first be unregistered under that name and then re-registered with the new name.

Parameters:
id - The name that the message logger is to be registered with. The logger is assigned this name (until it is registered with a different name).
Throws:
java.lang.NullPointerException - (unchecked) Thrown if log or id is null.
java.lang.IllegalArgumentException - (unchecked) Thrown if a message logger is already registered with the given name.
Since:
1.3, 2003-03-08
See Also:
unregister(), getLogger(java.lang.String), getName()

unregister

public void unregister()
Unregister this named message logger from the global logger list.

If this logger is not currently registered, no operation is performed.

Note that the default (unnamed) message logger cannot be unregistered.

Since:
1.3, 2003-03-08
See Also:
register(java.lang.String), close()

setPrefix

public int setPrefix(int pfx)
Establish the prefixes to be prepended to messages written to this message logger.

Specified by:
setPrefix in interface LoggerI
Parameters:
pfx - Zero or more of the PFX_XXX prefixing bitflag constants or-ed together.
Returns:
The previous prefix setting.
Since:
1.1, 2003-01-08

setVerbosity

public int setVerbosity(int sev,
                        int max)
Establish the verbosity filtering level for this message logger.

Specified by:
setVerbosity in interface LoggerI
Parameters:
sev - The severity of the messages to be filtered. This should be one of the SEV_XXX constants, or zero to specify all message severities.
max - The maximum verbosity filtering level for messages written to this message logger. Log messages with a verbosity level not greater than this value will be written to the logging output stream; those with a verbosity level greater than this value will be ignored.
Returns:
The previous verbosity level setting.
Since:
1.2, 2003-02-16

log

public void log(int sev,
                int verbos,
                java.lang.String loc,
                java.lang.String msg)
Write a formatted message to this message logger.

Note that this method does not throw any checked exceptions, specifically java.io.IOException.

Specified by:
log in interface LoggerI
Parameters:
sev - The severity of the message, which should be one of the SEV_XXX constants.
verbos - The verbosity level of the message. The higher the level, the more verbose the message (i.e., the more frequently the message is logged) and thus the more likely it will be filtered and not written to the output stream; messages with a level of zero will always be written to the output stream.
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no location is written.
msg - A text message to log.
Since:
1.2, 2003-01-16

debug

public void debug(int verbos,
                  java.lang.String loc,
                  java.lang.String msg)
Write a formatted debugging message to this message logger. Debugging messages have an implied severity of SEV_DEBUG.

Note that this method does not throw any checked exceptions, specifically java.io.IOException.

Specified by:
debug in interface LoggerI
Parameters:
verbos - The verbosity level of the message. The higher the level, the more verbose the message (i.e., the more frequently the message is logged) and thus the more likely it will be filtered and not written to the output stream; messages with a level of zero will always be written to the output stream.
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no location is written.
msg - A text message to log.
Since:
1.2, 2003-01-16

info

public void info(int verbos,
                 java.lang.String loc,
                 java.lang.String msg)
Write a formatted informational message to this message logger. Informational messages have an implied severity of SEV_INFO.

Note that this method does not throw any checked exceptions, specifically java.io.IOException.

Specified by:
info in interface LoggerI
Parameters:
verbos - The verbosity level of the message. The higher the level, the more verbose the message (i.e., the more frequently the message is logged) and thus the more likely it will be filtered and not written to the output stream; messages with a level of zero will always be written to the output stream.
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no location is written.
msg - A text message to log.
Since:
1.2, 2003-01-16

warning

public void warning(int verbos,
                    java.lang.String loc,
                    java.lang.String msg)
Write a formatted warning message to this message logger. Warning messages have an implied severity of SEV_WARNING.

Note that this method does not throw any checked exceptions, specifically java.io.IOException.

Specified by:
warning in interface LoggerI
Parameters:
verbos - The verbosity level of the message. The higher the level, the more verbose the message (i.e., the more frequently the message is logged) and thus the more likely it will be filtered and not written to the output stream; messages with a level of zero will always be written to the output stream.
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no location is written.
msg - A text message to log.
Since:
1.2, 2003-01-16

error

public void error(java.lang.String loc,
                  java.lang.String msg)
Write a formatted error message to this message logger. Error messages have an implied severity of SEV_ERROR.

Note that this method does not throw any checked exceptions, specifically java.io.IOException.

Specified by:
error in interface LoggerI
Parameters:
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no location is written.
msg - A text message to log.
Since:
1.2, 2003-01-16

fatal

public void fatal(java.lang.String loc,
                  java.lang.String msg)
Write a formatted fatal error message to this message logger. Fatal error messages have an implied severity of SEV_FATAL.

Note that this method does not throw any checked exceptions, specifically java.io.IOException.

Specified by:
fatal in interface LoggerI
Parameters:
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no location is written.
msg - A text message to log.
Since:
1.2, 2003-01-16

printMessage

protected void printMessage(int sev,
                            int verbos,
                            java.lang.String loc,
                            java.lang.String msg)
Write a formatted message to this message logger.

Note that this method does not throw any checked exceptions, especially java.io.IOException.

Parameters:
sev - The severity level of the message, which should be one of the SEV_XXX constants.
verbos - The verbosity level of the message. The higher the level, the more verbose the message (i.e., the more frequently the message is logged) and thus the more likely it will be filtered and not written to the output stream; messages with a level of zero will always be written to the output stream.
loc - The name of the location (typically a thread or class name) from where the log message originates. This serves as a label to prefix the message with in the logging output stream. This can be empty ("") or null, in which case no prefix is written.
msg - A text message to log. Note that this message should not have a terminating newline character.
Since:
1.1, 2003-01-06
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD