All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class iBus.Log

java.lang.Object
   |
   +----iBus.Log

public class Log
extends Object
class Log implements a simple logging facility. Applications use the Log class for logging informative messages, warnings, and panic messages. Those messages are directed to System.err or to any other output stream, according to how the Log object is initialized. The Log object can be configured to filter out non-critical messages.

The logging facility consists of a default stream (typically set to System.err or to a file output stream) and of an optional bus stream. The bus stream is used to redirect Log output to an iBus channel.

You can also filter on a per-module basis. Typically a Log object is created per module or per protocol object. The Log objects are maintained in a global hash table. You can then turn the individual Log objects on. For example, you can look at the Log messages produced by the NAK layer without getting confused by the Log messages that are generated by the other protocol objects.

Four severity levels are implemented: junk, info, warn, and panic. In addition there is a debug level for testing and debugging applications.

junk is used mostly for verbose tracing information.

info prints informative tracing messages, this level is much more terse than the junk level.

warn prints warnings that might lead to the failure of the application.

panic prints a panic message and terminates the application.

debug is typically used when debugging and testing an application. Once the application is stable, its debug messages are turned into junk and info messages.


Variable Index

 o infoLevel
Informative output only
 o junkLevel
All output, including debugging and tracing information
 o LOGCHANNEL
the default iBus channel used for log-to-channel property
 o LOGFILE
the default file used for log-to-file property
 o warnLevel
Warnings and panics only

Constructor Index

 o Log(String)
Create a Log object for a given module name.
 o Log(String, boolean)
Create a Log object for a given module name.

Method Index

 o debug(String)
Log a debugging message.
 o getBusStream()
return the bus stream.
 o getDefaultStream()
return the default stream used by the Log facility.
 o getLogLevel()
Returns the current log level.
 o getTimeStamp()
Return a time stamp.
 o info(String)
Log an info message.
 o isAppIds()
Checks whether host and application name are turned on.
 o isTimeStamps()
Checks whether time stamps are turned on.
 o junk(String)
Log a junk message.
 o logMessage(String, String, boolean, boolean)
Format a log message and write it to the log streams
 o moduleOff(String)
Turn logging off for a certain module.
 o moduleOn(String)
Turn logging on for a certain module.
 o panic(String)
Log a panic message and terminate the application by calling exit(1).
 o setAppIds(boolean)
Turn printing of host and application name on and off.
 o setBusStream(PrintWriter)
setBusStream can be used to set a PrintWriter which transmits output via the bus.
 o setDefaultStream(PrintWriter)
Use out instead of System.err for the output stream.
 o setLogLevel(int)
Modify the log level.
 o setTimeStamps(boolean)
Turn time stamps on and off.
 o warn(String)
Log a warning message.

Variables

 o junkLevel
 public static final int junkLevel
All output, including debugging and tracing information

 o infoLevel
 public static final int infoLevel
Informative output only

 o warnLevel
 public static final int warnLevel
Warnings and panics only

 o LOGCHANNEL
 public static iBusURL LOGCHANNEL
the default iBus channel used for log-to-channel property

 o LOGFILE
 public static final String LOGFILE
the default file used for log-to-file property

Constructors

 o Log
 public Log(String module)
Create a Log object for a given module name. The module name typically corresponds to a protocol object name, an application name, etc. It is used for turning logging on on a per-module basis.

Parameters:
module - the name of the module the object is created for. This is the name of a protocol object, for example.
 o Log
 public Log(String module,
            boolean prohibitBus)
Create a Log object for a given module name. The module name typically corresponds to a protocol object name, an application name, etc. It is used for turning logging on on a per-module basis. This constructor also allows to specify whether loging output may be directed to a bus channel or not.

Parameters:
module - the name of the module the object is created for. This is the name of a protocol object, for example.
prohibitBus - specifies whether loging output may be directed to a bus channel or not

Methods

 o setLogLevel
 public static void setLogLevel(int level)
Modify the log level. If, for example, the log level is set to Log.warn, only warnings and panics are logged. junk and info messages are discarded. A log level of Log.junk logs every message. Warnings and panics cannot be turned off.

Parameters:
level - specifies the loglevel (either Log.junkLevel, Log.infoLevel, Log.warnLevel, or Log.panicLevel)
 o getLogLevel
 public static int getLogLevel()
Returns the current log level.

Returns:
the current log level
 o setDefaultStream
 public static void setDefaultStream(PrintWriter out)
Use out instead of System.err for the output stream. The out stream should not redirect its output to an iBus channel. Use setBusStream if aou want to redirect output to a stream. The default stream can also be set via the Application.PROP_LOGTOFILE system property.

Parameters:
out - the stream to log messages to.
 o getDefaultStream
 public static PrintWriter getDefaultStream()
return the default stream used by the Log facility.

Returns:
the stream used by the Log facility
 o setBusStream
 public static void setBusStream(PrintWriter out)
setBusStream can be used to set a PrintWriter which transmits output via the bus. However, a fatal recursion might result if loging output of low-level protocol objects such as IPMCAST were to be directed to an iBus channel. Such protocol objects should create a Log object by passing prohibitBus=true in the Log constructor. Those Log objects will use the default stream only.

Parameters:
out - the bus stream to log messages to.
 o getBusStream
 public static PrintWriter getBusStream()
return the bus stream.

Returns:
the bus stream or null if none was set.
 o setTimeStamps
 public static void setTimeStamps(boolean on)
Turn time stamps on and off.

Parameters:
on - whether time stamps are to be turned on
 o isTimeStamps
 public boolean isTimeStamps()
Checks whether time stamps are turned on.

Returns:
whether time stamps are turned on
 o setAppIds
 public static void setAppIds(boolean on)
Turn printing of host and application name on and off.

Parameters:
on - whether host and application name are to be turned on
 o isAppIds
 public boolean isAppIds()
Checks whether host and application name are turned on.

Returns:
whether host and application name are turned on
 o junk
 public void junk(String msg)
Log a junk message. Junk messages are typically used in the early stages of the implementation of a protocol object. As the object matures, the log level is set to Log.info, and finally to Log.warn.

Parameters:
msg - the string to be written to the log.
 o info
 public void info(String msg)
Log an info message. Those messages can be filtered out by setting the log level to Log.warn. Info messages occur less frequently than junk messages and are more informative.

Parameters:
msg - the string to be written to the log.
 o warn
 public void warn(String msg)
Log a warning message.

Parameters:
msg - the string to be written to the log.
 o panic
 public void panic(String msg)
Log a panic message and terminate the application by calling exit(1).

Parameters:
msg - the string to be written to the log.
 o debug
 public void debug(String msg)
Log a debugging message. Those messages can *not* be filtered out. It is just an alternative approach to calling System.err.println.

Parameters:
msg - the string to be written to the log.
 o moduleOn
 public static synchronized void moduleOn(String module)
Turn logging on for a certain module.

Parameters:
module - the name of the module to activate
 o moduleOff
 public static synchronized void moduleOff(String module)
Turn logging off for a certain module.

Parameters:
module - the name of the module to deactivate
 o logMessage
 protected synchronized void logMessage(String level,
                                        String msg,
                                        boolean stackTrace,
                                        boolean panic)
Format a log message and write it to the log streams

Parameters:
level - the String representing the log level
msg - the message to log
stackTrace - whether a stack trace shall be printed
panic - whether this is a panic message
 o getTimeStamp
 protected String getTimeStamp()
Return a time stamp.

Returns:
a time stamp with the current time and date.

All Packages  Class Hierarchy  This Package  Previous  Next  Index