Log (Core com.ccg Classes 1.1.6-SNAPSHOT API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ccg.util
Class Log

java.lang.Object
  com.ccg.util.Log

public class Log
extends Object
extends Object

Class to facilitate a general purpose message logging system. In our C++ libraries we had a handy message logging mechanism which enabled us to easily log messages when error, warning, information, and other types of conditions occurred. This class is designed to implement the same type of environment, but also enable the localization of the log messages. Please refer to the LogDebug example program (and its source code) for a decent working example of using this class with localization values.

NOTE:This class is really intended for non-debugging output. The Debug class has been provided (which makes use of this class) for logging debugging type of information.

UNFORTUNATELY, after thorough use of this class, it was discovered that its method to localize messages to be inadequate. To realistically use this class for localization purposes, a Log object should be created with its own resource bundle. The static methods should not be doing any of the localization themselves. Unfortunately to change this would have ramifications for a lot of existing code. New users of the Log() class should use the following methods for logging messages (and localize the messages themselves):

Log.always("Message");
Log.info("Message");
Log.error("Message");
Log.error("Message",exception);
Log.warning("Message");
if (Debug.isEnabledFor(level)) Debug.out("Message");
Debug.log(level,"Message"); // for simple messages

Since:: 1.0
Version:: $Revision: 1.1.1.1 $
Author:: $Author: pkb $
See Also:: Debug, log(int,String,String,Object[])

Field Summary
`static int`	`ALWAYS` Log level for messages which should ALWAYS be logged.
`static int`	`DEBUG` Log level for messages which provide debugging information.
`static int`	`ERROR` Log level for messages which indicate an error condition.
`static int`	`INFO` Log level for messages which provide information to the user.
`static int`	`WARNING` Log level for messages which indicate an warning condition.

Constructor Summary
`Log()`

Method Summary
`static void`	`addLogViewer(Observer o)` Add an additional log viewer object.
`static void`	`always(String msg)` Wrapper function to log a message at the `ALWAYS` level.
`static void`	`always(String key, String dMsg, Object[] args)` Wrapper function to log a message at the `ALWAYS` level.
`static void`	`error(String msg)` Wrapper function to log a message at the `ERROR` level.
`static void`	`error(String key, String dMsg, Object[] args)` Wrapper function to log a message at the `ERROR` level.
`static void`	`error(String msg, Throwable e)` Wrapper function to log a message at the `ERROR` level.
`static String`	`format(int ll, int dl)` Format a log level (and possibly a debug verbosity) as a string.
`static int`	`getLevel()` Examine the current level of output.
`static String[]`	`getLogLevelStrings()` Get all of the possible (recognized) log level settings (in their string representation).
`static int[]`	`getLogLevelValues()` Get all of the possible (recognized) log level settings (in their integer form).
`static void`	`info(String msg)` Wrapper function to log a message at the `INFO` level.
`static void`	`info(String key, String dMsg, Object[] args)` Wrapper function to log a message at the `INFO` level.
`static void`	`init(String basename, Lookup cl)` Initialize the properties of logging based on command line options.
`static void`	`init(String basename, Lookup l, Observer o)` Initialize the properties of logging based on command line options.
`static void`	`log(int lev, String key, String dMsg, Object[] args)` Log a message.
`static String`	`logLevelToString(int ll, String badVal)` Convert a log level to a string representation.
`static void`	`removeLogViewer(Observer o)` Remove a single log viewer object.
`static void`	`setLevel(int new_level)` Set the output log level.
`static void`	`setLogViewer(Observer o)` Set the log viewer object.
`static void`	`setResourceBundle(ResourceBundle bundle)` Set the resource bundle to use for language translations.
`int`	`stringToLogLevel(String llstr, int badVal)` Convert a string value to its corresponding log level.
`static boolean`	`validateDebugLevel(int ll)` Verify a debug verbosity level.
`static boolean`	`validateLogLevel(int ll)` Verify a log level value is valid.
`static void`	`warning(String msg)` Wrapper function to log a message at the `WARNING` level.
`static void`	`warning(String key, String dMsg, Object[] args)` Wrapper function to log a message at the `WARNING` level.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

ALWAYS

public static final int ALWAYS

Log level for messages which should ALWAYS be logged. Note, logging at this level can be used for important informational messages which you want the user to see (it doesn't necessarily indicate a severe error condition).

Since:: 1.0
See Also:: setLevel(int), log(int,String,String,Object[]), Constant Field Values

ERROR

public static final int ERROR

Log level for messages which indicate an error condition.

Since:: 1.0
See Also:: setLevel(int), log(int,String,String,Object[]), Constant Field Values

INFO

public static final int INFO

Log level for messages which provide information to the user.

Since:: 1.0
See Also:: setLevel(int), log(int,String,String,Object[]), Constant Field Values

WARNING

public static final int WARNING

Log level for messages which indicate an warning condition. This level is used to indicate that the message being logged is important to tell the user (the user will benefit from seeing the information). The message should be considered as informational (not a ERROR or WARNING condition).

Since:: 1.0
See Also:: setLevel(int), log(int,String,String,Object[]), Constant Field Values

DEBUG

public static final int DEBUG

Log level for messages which provide debugging information. Typically, this level is not directly used. Use the Debug.log() function for debug output instead.

Since:: 1.0
See Also:: setLevel(int), Debug.isEnabledFor(int), Debug.out(java.lang.String, java.lang.String, java.lang.Object[]), log(int,String,String,Object[]), Constant Field Values

Constructor Detail

Log

public Log()

Method Detail

always

public static void always(String key,
                          String dMsg,
                          Object[] args)

Wrapper function to log a message at the ALWAYS level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do the following:

 Log.always("key","Default output message",null);

Instead of the following:

 Log.log(Log.ALWAYS,"key","Default output message",null);

Parameters:: key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.; dMsg - Default string message (if key is null or locale specific message isn't found).; args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.
Since:: 1.0
See Also:: log(int,String,String,Object[])

always

public static void always(String msg)

Wrapper function to log a message at the ALWAYS level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do something like the following:

 String msg = myResourceBundle.getString("ALWAYS.210");
 Log.always(msg);

It should be noted that this version does not attempt any localization of the message for you (you will need to do that yourself).

Parameters:: msg - Message to log - it should already be localized for the locale.
Since:: 1.0
See Also:: log(int, java.lang.String, java.lang.String, java.lang.Object[])

error

public static void error(String key,
                         String dMsg,
                         Object[] args)

Wrapper function to log a message at the ERROR level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do the following:

 Log.error("key","Default output message",null);

Instead of the following:

 Log.log(Log.ERROR,"key","Default output message",null);

Parameters:: key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.; dMsg - Default string message (if key is null or locale specific message isn't found).; args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.
Since:: 1.0
See Also:: log(int,String,String,Object[])

error

public static void error(String msg)

Wrapper function to log a message at the ERROR level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do something like the following:

 String msg = myResourceBundle.getString("ERR.101");
 Log.error(msg);

It should be noted that this version does not attempt any localization of the message for you (you will need to do that yourself).

Parameters:: msg - Message to log - it should already be localized for the locale.
Since:: 1.0
See Also:: error(String,Throwable), log(int, java.lang.String, java.lang.String, java.lang.Object[])

error

public static void error(String msg,
                         Throwable e)

Wrapper function to log a message at the ERROR level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do something like the following:

 String msg = myResourceBundle.getString("ERR.101");
 Log.error(msg);

It should be noted that this version does not attempt any localization of the message for you (you will need to do that yourself).

Parameters:: msg - Message to log - it should already be localized for the locale - it is OK to pass null.; e - Any Throwable object (which all java.lang.Exceptions are). If non-null, the stack trace will be appended to the 'msg'.
Since:: 1.0
See Also:: error(String,Throwable), log(int, java.lang.String, java.lang.String, java.lang.Object[])

info

public static void info(String key,
                        String dMsg,
                        Object[] args)

Wrapper function to log a message at the INFO level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do the following:

 Log.info("key","Default output message",null);

Instead of the following:

 Log.log(Log.INFO,"key","Default output message",null);

Parameters:: key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.; dMsg - Default string message (if key is null or locale specific message isn't found).; args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.
Since:: 1.0
See Also:: log(int,String,String,Object[])

info

public static void info(String msg)

Wrapper function to log a message at the INFO level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do something like the following:

 String msg = myResourceBundle.getString("INFO.014");
 Log.info(msg);

It should be noted that this version does not attempt any localization of the message for you (you will need to do that yourself).

Parameters:: msg - Message to log - it should already be localized for the locale.
Since:: 1.0
See Also:: log(int, java.lang.String, java.lang.String, java.lang.Object[])

warning

public static void warning(String key,
                           String dMsg,
                           Object[] args)

Wrapper function to log a message at the WARNING level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do the following:

 Log.warning("key","Default output message",null);

Instead of the following:

 Log.log(Log.WARNING,"key","Default output message",null);

Parameters:: key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.; dMsg - Default string message (if key is null or locale specific message isn't found).; args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.
Since:: 1.0
See Also:: log(int,String,String,Object[])

warning

public static void warning(String msg)

Wrapper function to log a message at the WARNING level. This function provides a wrapper around the log() function. It is intended to save typing and enables you to do something like the following:

 String msg = myResourceBundle.getString("WARN.012");
 Log.warning(msg);

It should be noted that this version does not attempt any localization of the message for you (you will need to do that yourself).

Parameters:: msg - Message to log - it should already be localized for the locale.
Since:: 1.0
See Also:: log(int, java.lang.String, java.lang.String, java.lang.Object[])

setResourceBundle

public static void setResourceBundle(ResourceBundle bundle)

Set the resource bundle to use for language translations. This routine allows one to specify a resource bundle to be used by the log(int,String,String,Object[]) function when it performs language translations. This will enable future "log" messages the ability to be translated to the proper locale.

Parameters:: bundle - New resource bundle to use for language translations.
Since:: 1.0
See Also:: log(int,String,String,Object[])

setLevel

public static void setLevel(int new_level)

Set the output log level. This routine allows one to change the output log level. By setting a specific level, you permit that level and ALL of the levels above it to be logged. The current level heirarchy is as follows:

Parameters:: int - New log level to use.
Since:: 1.0
See Also:: log(int,String,String,Object[])

init

public static void init(String basename,
                        Lookup cl)

Initialize the properties of logging based on command line options. This routine is intended to be invoked near the startup of the application (or applet). It initializes much of the basic opertation of the logging environment based on run time configured variables (typically from the command line). This is probably the simplest way to setup the logger.

If a resource bundle hasn't been loaded yet for the logger (via setResourceBundle), then an attempt will be made to load the resource bundle associated with the application for the current locale.

This routine will look for a set of common command line options and use those options to setup the output logging environment. The current command line options which are looked for include:

-debug [LEVEL]: This option will automatically set the logger to the DEBUG level for output. In addition, if the optional debug LEVEL (as a number from 0-9) is specified, it will also set the debug verbosity level to the level specified or the default value of 3 if not specified.
-log_level LEVEL: Specify the log level (similar to setLevel(int). The LEVEL must be one of the following "always", "error", "info", "warning", or "debug". This option is only checked if -debug [LEVEL] is not set.

In the future options will probably be added to allow for redirection of the output log messages.

Parameters:: basename - Base name of application used when trying to fetch the appropriate resource bundle for the logger.; cl - Command line arguments.
Since:: 1.0
See Also:: log(int,String,String,Object[])

init

public static void init(String basename,
                        Lookup l,
                        Observer o)

If a resource bundle hasn't been loaded yet for the logger (via setResourceBundle), then an attempt will be made to load the resource bundle associated with the application for the current locale.

This routine will look for a set of common command line options and use those options to setup the output logging environment. The current command line options which are looked for include:

-debug [LEVEL]: This option will automatically set the logger to the DEBUG level for output. In addition, if the optional debug LEVEL (as a number from 0-9) is specified, it will also set the debug verbosity level to the level specified or the default value of 3 if not specified.
-log_level LEVEL: Specify the log level (similar to setLevel(int). The LEVEL must be one of the following "always", "error", "info", "warning", or "debug". This option is only checked if -debug [LEVEL] is not set.

In the future options will probably be added to allow for redirection of the output log messages.

Parameters:: basename - Base name of application used when trying to fetch the appropriate resource bundle for the logger.; cl - Command line arguments (or null if none).; logger - The actual object used to record the text log. By default (if you pass null), a object will be created that puts the log contents to System.err.
Since:: 1.0
See Also:: log(int,String,String,Object[])

setLogViewer

public static void setLogViewer(Observer o)

Set the log viewer object. The Log class is designed to allow maximum flexibility in where the log message are displayed and/or recorded. If a application (and user) doesn't specify any specific log viewer, then the log messages will simply be written to System.err. For more advanced applications (and GUI applications), it may be desirable to do something fancy with the log messages (so they don't go scrolling by on your console). This routine allows one to specify their own special handler for processing the log messages. The handlers are implemented in a standard java.lang.Observable form. The following demonstrates how one might construct their own custom handler:

 class MyLogViewer implements Observable {

   public void update(Observable o, Object logThis) {
         if (logThis != null) System.out.println(logThis.toString());
   }

                         // Install as only log viewer when created
   MyLogViewer() { Log.setLogViewer(this); }
   
 }

Parameters:: arg1 - New observer that will monitor (and possibly record) the log messages that pass through the logger. NOTE: It is OK to pass null, it will effectively turn off ALL logging.
Since:: 1.0
See Also:: init(String,Lookup,Observer), addLogViewer(java.util.Observer)

addLogViewer

public static void addLogViewer(Observer o)

Add an additional log viewer object. The Log class is designed to allow maximum flexibility in where the log message are displayed and/or recorded. If a application (and user) doesn't specify any specific log viewer, then the log messages will simply be written to System.err. For more advanced applications (and GUI applications), it may be desirable to do something fancy with the log messages (so they don't go scrolling by on your console). This routine allows one to add an additional special handler for processing the log messages.

This routine is particularily useful for those circumstances when you want to "peek" at the log messages which are occurring. You can use this method to look at the messages for awhile with your handler and then use removeLogViewer(java.util.Observer) to remove them when you are done - all without affecting any of the other registered log viewers.

The handlers are implemented in a standard java.lang.Observable form. Once you've added a viewer, you can later remove it if desired by using removeLogViewer(java.util.Observer). The following demonstrates how one might construct their own custom handler:

 class MyLogViewer implements Observable {

   public void update(Observable o, Object logThis) {
         if (logThis != null) System.out.println(logThis.toString());
   }

   public void remove() {       // allow the viewer to be removed
     Log.removeLogViewer(this);
   }

                         // Install as additional
                             // log viewer when created
   MyLogViewer() { Log.addLogViewer(this); }
   
 }

Parameters:: arg1 - New observer that will also monitor (and possibly record) the log messages that pass through the logger. NOTE: passing null is OK (but it doesn't affect anything).
Since:: 1.0
See Also:: init(String,Lookup,Observer), setLogViewer(java.util.Observer), removeLogViewer(java.util.Observer)

removeLogViewer

public static void removeLogViewer(Observer o)

Remove a single log viewer object. This method is used to remove a log viewer which was previously added via addLogViewer(java.util.Observer).

Parameters:: arg1 - Observer object to remove (that had been previously added). NOTE: It is OK to pass null, it just doesn't do anything.
Since:: 1.0
See Also:: addLogViewer(java.util.Observer)

log

public static void log(int lev,
                       String key,
                       String dMsg,
                       Object[] args)

Log a message. This static routine can be invoked whenever one wants to log a message. If the log level associated with your message is less than or equal to the current log level, then your message will be logged. This log level feature enables the user to control how much information to see. The log level output is controlled by the setLevel(int) member.

Typically you will not invoke this function directly, you would instead use one of the wrapper functions:

Log.always() - to log very important information.
Log.error() - to log severe error messages.
Log.info() - to log information messages.
Log.warning() - to log warning type messages.
Debug.log - to log debug output messages.

NOTE: Do NOT use this function directly for debug output. Use the Debug class instead. It will indirectly use this class, but has the option to optimize out a lot of code when you don't need a debug build.

Parameters:: vlev - Verbosity level. This should be in the range of [0-9]. Output will only be logged if this level is less than the current verbosity level. This was done to mimic a lot of GNU code.; key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.; dMsg - Default string message (if key is null or locale specific message isn't found).; args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.
Since:: 1.0
See Also:: setLevel(int), always(java.lang.String, java.lang.String, java.lang.Object[]), error(java.lang.String, java.lang.String, java.lang.Object[]), info(java.lang.String, java.lang.String, java.lang.Object[]), warning(java.lang.String, java.lang.String, java.lang.Object[]), Debug.log(int,String,String,Object[])

getLevel

public static int getLevel()

Examine the current level of output.

Returns:: Integer value last set by setLevel(int)
Since:: 1.0
See Also:: setLevel(int)

validateLogLevel

public static boolean validateLogLevel(int ll)

Verify a log level value is valid.

Parameters:: ll - A "log level" that you would like to have verified.
Returns:: true if a recognized log level is specified
Since:: 1.0

validateDebugLevel

public static boolean validateDebugLevel(int ll)

Verify a debug verbosity level.

Parameters:: ll - A "debug level" that you would like to have verified.
Returns:: true if the debug level is in the range of [0,9].
Since:: 1.0

getLogLevelStrings

public static String[] getLogLevelStrings()

Get all of the possible (recognized) log level settings (in their string representation).

Returns:: An array of the valid log level's as strings - there is a one to one correspondence to the associated ID's in the array returned by getLogLevelValues().
Since:: 1.0
See Also:: getLogLevelValues()

getLogLevelValues

public static int[] getLogLevelValues()

Get all of the possible (recognized) log level settings (in their integer form).

Returns:: An array of the valid log level's as their integer constant values - there is a one to one correspondence to the associated ID's in the array returned by getLogLevelStrings().
Since:: 1.0
See Also:: getLogLevelStrings()

logLevelToString

public static String logLevelToString(int ll,
                                      String badVal)

Convert a log level to a string representation.

Parameters:: ll - The log level to convert to string representation - should be one of the standard log level constants defined (like: Log.ERROR.; badVal - What to return if the log level passed is not valid.
Returns:: The string representation of the log level, or the 'badValue' if it isn't recognized.
Since:: 1.0
See Also:: format(int, int)

stringToLogLevel

public int stringToLogLevel(String llstr,
                            int badVal)

Convert a string value to its corresponding log level.

Parameters:: llstr - The log level as a string (like "error") to convert to a log level constant (note we are case insensitive). However, you must not pass null.; badVal - The value to return (typically one of the standard log mode constants - or -1) if the string could not be converted.
Returns:: One of the constant log level values defined in this class, or 'badValue' if string isn't recognized.
Since:: 1.0
See Also:: format(int, int)

format

public static String format(int ll,
                            int dl)

Format a log level (and possibly a debug verbosity) as a string.

This method takes a log level setting and a debug verbosity value and produces a single string representation. The string representation produced will only include the debug verbosity if the log level passed is Log.DEBUG.

For example, you might get strings like: "error", "debug 3", "warning" out of this method.

Parameters:: ll - The log level.; dl - Debug level verbosity (only used if the log level is Log.DEBUG.
Returns:: String representation of log mode.
Since:: 1.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ccg.util Class Log

ALWAYS

ERROR

INFO

WARNING

DEBUG

Log

always

always

error

error

error

info

info

warning

warning

setResourceBundle

setLevel

init

init

setLogViewer

addLogViewer

removeLogViewer

log

getLevel

validateLogLevel

validateDebugLevel

getLogLevelStrings

getLogLevelValues

logLevelToString

stringToLogLevel

format

com.ccg.util
Class Log