LOG Package

Document	xxxx
Authors	J. L. Abad Peiro (ZRL) C. Gulcu (ZRL) A. Fleuti (ZRL)
Editor	C. Gulcu (ZRL)
Status	Alpha Version 0.7, SEMPER internal

Abstact

The semper.util.log package exports only a single class namely Log, although it defines two other unexported classes for internal use.

The goal of the LOG package is to provide a general but simple, yet robust and flexible logging facility. A major objective is to minimize source code fiddling in order to activate/deactivate arbitrary log messages. Ideally, one should be able to write a log statement in the source code and control its activation/deactivation dynamically through some sort of preference manager.

Short Remarks

We write bytes instaed of unicode chars... (Mehdi's suggestion)

Requires

The LOG package requires the ExecInfo class defined in the "semper.util.execInfo" package. The ExecInfo class is used to print stack tracing information.

The TINGUIN and Preferences packages are required too.

Exported Constants

Gravity of Messages

The following five constants allow us to assign different levels of severity to messages. They are listed in the order of their severity.

CRITICAL

Corresponds to highly irrecuperable malfunctions. CRITICAL level errors should be used for extremely serious error conditions.

ERROR

Corresponds to serious malfunction. ERROR level errors should be used for highly serious error conditions.

WARNING

Corresponds to situations of minor malfunction or misconfiguration. WARNING level messages should be used for situations reflecting misconfigurations or probable programming errors.

INFO

Corresponds to progress report messages. INFO level is intended for high level messages, e.g. for reporting to the user/programmer on the progress of a particular run.

TRACE

Corresponds to debugging messages. TRACE level is intended for use in isolating programming erros.

Exported Methods

void init(String fullFileName)

Don't use this method anymore. There is no need for it.

This form is provided for compatibility with existing code. On Asokans request, it adds ".log" to the file name parameter.

void loadPrefs()

Log.loadPrefs() reads the saved settings from disk and overwrites the actual values. This method need a initialised Preferences.class.

void log(Sting category, int level, String message)

The Log.log() method may send a message to [LogFile] depending on the space separated categoryList and level parameters.

The categoryList parameter specifies a list of categories. Each element of this list corresponds to a specific category to which the log message belongs.

A message can belong to multiple categories.

For example the code

     Log.log("X.CONTRUCTOR PAYMENT", Log.TRACE, "Some message");

specifies that "Some Message" belongs to the "X.CONSTRUCTOR" and "PAYMENT" categories and is of level Log.TRACE.

The category values are set in the preference manager. The allowed values are (in increasing priority) CRITICAL, ERROR, WARNING, INFO and TRACE.

When a message belongs to more than one category the category with the lowest priority dominates. We say that lower severity messages subsume higher severity messages. The rationale behind this is that, if you are interested in lower severity messages then you are certainly interested in more severe messages. If a message does not belong to a known category, it is assigned a default category level as specified by the [DefaultCategoryLevel] option.

For example, if we set

    DefaultCategoryLevel = TRACE
    X = INFO
    Y = WARNING

then, in the code

   Log.log("X Y",   Log.TRACE, "Message 2"); // X dominates
   Log.log("Z",   Log.TRACE, "Message 2");   // Z is not set

"X Y" evaluates to INFO and Z evaluates to TRACE.

Once the categoryList parameter is evaluated it is compared with the actual level of the message. If the valuation of categoryList subsumes the level parameter, then the message is logged.

For example, if we set

   
    DefaultCategoryLevel = TRACE
    X = INFO
    Y = WARNING

then,

    Log.Trace("X"  , "Message 1");

will not log, since X doesn't subsume TRACE. Similarly,

 
    Log.Error("X Y", "Message 2");

will log, since "X Y" evaluates to INFO and INFO subsumes ERROR.

Remark: The order in which the categories are listed is insignificant.

By convention, a if a message pertains to a certain category it also pertains to all dot separated prefixes of that category. For example,

     Log.trace("X.Y.Z", "Some message");

means that "Some message" pertains to categories "X.Y.Z", "X.Y" and "X".

When evaluating categories the most specific category has precedence. For example, if in the preferences manager we set

X     = TRACE 
X.Y   = INFO 
X.Y.Z = WARNING

then, in the code

     Log.trace("X.Y.Z", "Some message");

"X.Y.Z" will evaluate to WARNING. Furthermore, since WARNING does not subsume TRACE the message will not log.

Similarly,

     Log.trace("X.Y.WHATEVER", "Some message");

will evaluate to the value of X.Y ("INFO") assuming X.Y.WHATEVER is unset. Consequently, the message will not log.

void log(Object object, int level, String message)

Similar to the preceding log() form except that the category is derived from the class name of the specified object,

This form is provided for compatibility with existing code. It should be phased out.

critical(String categoryList, String message)
error(String categoryList, String message)
warning(String categoryList, String message)
info(String categoryList, String message)
trace(String categoryList, String message)

Similar to log() except that the message level is deduced from the method name itself.

These new forms are provided as a syntaxic facility.

String setFullFileName(String fullFileName)

Set the log file where logging messages will go. Equivalent to setting up the [LogFile] option in the preference manager. If unset, there is no default value is an empty String. This method does not save the change to disk.

String fullFileName: The full file name for the log file.
returns: Previously used log file.

String setFullFileName(String fullFileName, boolean saveit)

String fullFileName: The full file name for the log file.
boolean saveit: if saveit is true, the change will be saved to disk.
returns: Previously used log file.

int setDefaultCategoryLevel(int level)

Sets up the default level assigned to unknown categories. Equivalent to setting up the [DefaultCategoryLevel] option in the preference manager. If unset, the default category level is INFO. This method does not save the change to disk.

int level: New default category level.
returns: The old default category level

int setDefaultCategoryLevel(int level, boolean saveit)

int level: New default category level.
boolean saveit: if saveit is true, the change will be saved to disk.
returns: The old default category level

void setCategory (String category, int value)

Configure loging categories. This method does not save the change to disk.

String category: The category to configure.
int value: The level of the category. Possible values (in decreasing severity) are CRITICAL, ERROR, WARNING, INFO and TRACE.

void setCategory (String category, int value, boolean saveit)

Configure loging categories. This method does not save the change to disk.

String category: The category to configure.
int value: The level of the category. Possible values (in decreasing severity) are CRITICAL, ERROR, WARNING, INFO and TRACE.
boolean saveit: if saveit is true, the change will be saved to disk

int setStackInfoThreshold(int level)

Set the stack information threshold. Equivalent to setting up the [StackInfoThreshold] option in the preference manager. If unset, defaults to WARNING. This method does not save the change to disk.

Stack tracing information is added for all messages of same or higher severity than the stack information threshold.

int level: The new stack info threshold. Possible values (in decreasing priority) are CRITICAL, ERROR, WARNING, INFO and TRACE.
returns: The old stack info threshold.

int setStackInfoThreshold(int level, boolean saveit)

int level: The new stack info threshold. Possible values (in decreasing priority) are CRITICAL, ERROR, WARNING, INFO and TRACE.
boolean saveit: if saveit is true, the change will be saved to disk
returns: The old stack info threshold.

boolean setDatePrinting(boolean newValue)

Sets whether date printing is enabled or not. Equivalent to setting up the [DatePrinting] option in the preference manager. If unset, defaults to TRUE. This method does not save the change to disk.

If date printing is enabled, then date information is added to all logged messages.

int level: New date printing setting.
returns: The old date printing setting.

boolean setDatePrinting(boolean newValue, boolean value)

int level: New date printing setting.
boolean saveit: if saveit is true, the change will be saved to disk
returns: The old date printing setting.

boolean setTimePrinting(boolean newValue)

Sets whether date printing is enabled or not. Equivalent to setting up the [TimePrinting] option in the preference manager. If unset, defaults to TRUE. This method does not save the change to disk.

If time printing is enabled, then time information is added to all logged messages.

boolean newValue: New time printing setting.
returns: The old time printing setting.

boolean setTimePrinting(boolean newValue, boolean saveit)

boolean newValue: New time printing setting.
boolean saveit: if saveit is true, the change will be saved to disk
returns: The old time printing setting.

boolean setThreadPrinting(boolean newValue)

Sets whether thread printing is enabled or not. Equivalent to setting up the [ThreadPrinting] option in the preference manager. If unset, defaults to TRUE. This method does not save the change to disk.

If thread printing is enabled, then the name of the current thread is added to all logged messages.

boolean newValue: New date thread setting.
returns: The old thread setting.

boolean setThreadPrinting(boolean newValue, boolean value)

boolean newValue: New date thread setting.
boolean saveit: if saveit is true, the change will be saved to disk
returns: The old thread setting.

boolean setCategoryPrefixing(boolean newValue)

Set whether category printing is enabled or not.

If time category printing is enabled, then the first category in the categoryList (see log() ) is added to all messages. This method does not save the change to disk.

boolean newValue: New category printing setting.
returns: The old category printing setting.

boolean setCategoryPrefixing(boolean newValue, boolean saveit)

boolean newValue: New category printing setting.
boolean saveit: if saveit is true, the change will be saved to disk
returns: The old category printing setting.

String setStdPrefix(String newValue)

Set the standard prefix added to all messages. Returns the old standard prefix. This method does not save the change to disk.

String setStdPrefix(String newValue, boolean saveit)

if saveit is true, the change will be saved to disk.

Preferences

[AllPowerToUser]

If this flag is set, all SetX-methods have no effect. The user might dislike that a program changes his saved settings. In this case the user can set this flag.

[LogFile]

The name of the file where messages are appended. There default is an empty string.

[DefaultCategoryLevel]

Possible values (in decreasing severity) are CRITICAL, ERROR, WARNING, INFO and TRACE.

Default value is ERROR.

The default level for unknown categories.

[StackInfoThreshold]

Possible values (in decreasing priority) are CRITICAL, ERROR, WARNING, INFO and TRACE.