com.ls.service.log
Class Logger

java.lang.Object
  |
  +--com.ls.service.log.Logger
All Implemented Interfaces:
ILogger

public class Logger
extends Object
implements ILogger

This class is responsible for the logging of activities of agents and generates log entries.


to Class Specification
Such log file entries look like
 18-Aug-00 10:39:13.802[info][AgentTemplate][setLog()]name of logFile: '$A.log' [ -> 'D:/www/living-systems/auction/log/AgentTest@192.168.100.114-lars.log'], logLevel: trace5
 18-Aug-00 10:39:13.862[info][AgentTemplate][setRunLevel(int)]switching from run level ACTIONS_INITIALIZED to run level CONFIG_FILE_INTERPRETED
 
The date format is logged according to the UK Locale, because this format is shorter than the US locale.

There exist 8 different log levels: error (most important), warning, info and five different trace levels (trace1, .., trace5). It depends on the log level of the message and on the agent's log level, if a log message gets written: If the log level of the message is at least as important as the agent's log level, the message is written, otherwise it is ignored.
The log message gets written in a log file, if such a log file got specified and opened successfully afterwards - else the log messages are written to System.out. Specifying and opening a log file can be done in the constructor or with help of the setLogFile(java.lang.String) method.

Keep in mind, that even if the log level of the message is less important as the agent's log level, the log arguments will be handed over to the corresponding log method (which takes time, especially if the log notice has to be constructed from multiple strings). So please remove/comment log messages, that are useless in a readily developed class.

How log file names are generated:
When specifying a log file three different variables may be used in the log file's name. (Additional substitutions may be configured with help of the replacementMapPutAll() method.)

Further on it is checked, if the log file name is an absolute or a relative path. If the given log file path is recognized as a relative path, the value of the globalLogPath variable (see HT-DEV-LARS25-config-file-howto-1.doc) is prepended to the file name. (If a path is absolute or relative, is determined via File.isAbsolute(). Note, that for a Windows configuration, the path "\log" is not absolute, because there is no drive specification - you need to use something like "d:\log" or "\\networkdrive\log".)

This file name generation mechanism makes the usage of config files very flexible: If the same agent is running on more than one lars platform (e.g. for load scalability reasons) or if some agents need the same configuration parameters, all of those agents may use the same config file (and have their own logfiles even though).
Example: The String from the config file '$A.log' could become '/www/demo/demo/log/AgentInfo@192.168.100.114-lars.log' (if the globalLogPath variable is set to '/www/demo/demo/log/').

Version:
$Revision: 1.17 $
Author:
Last modified by $Author: MFehrenbach $
See Also:
"HT-DEV-LARS25-config-file-howto-1.doc"

Fields inherited from interface com.ls.service.log.ILogger
ERROR, INFO, LEVEL_INDEPENDENT, LOG_LEVEL, MAX_LOG_LEVEL, TAG_GLOBAL_LOG_PATH, TAG_LOG_FILE, TAG_LOG_LEVEL, TAG_LOG_TYPE, TRACE, TRACE1, TRACE2, TRACE3, TRACE4, TRACE5, WARNING
 
Constructor Summary
Logger()
          Empty constructor.
Logger(String logFileName, int logLevel, Map map)
          Constructor that includes trying to open the file where the log messages get stored and setting the log level.
Logger(String logFileName, Map map)
          Constructor that includes trying to open the file where the log messages get stored.
 
Method Summary
 boolean canLog(int logLevel)
          determines, if a notice with the given log level will be logged
 void closeLogFile()
          closes the logfile
protected  void finalize()
          closes the log file if this object gets deleted
 String getLogFileName()
          gets name of log file, which is currently in use
 int getLogLevel()
          Returns the current loglevel as number.
 String getLogLevelString()
          Returns gets the name of the current log level.
 byte getLogType()
          Returns the log type of this logger.
 String getLogTypeString()
          Returns the log type of this logger, as a string
 boolean hasLogFile()
          Checks, if this Logger instance uses a log file or System.out for logging.
 void log(String className, int logLevel, String methodName, Object[] logNotice)
          Logs a given notice, if the given logLevel is equal or more important than the configured agent log level.
Example: 2001-06-15 09:20:13.560[warning][AgentDemo][demoMethod()]this is a great warning log message
 void log(String className, int logLevel, String methodName, Object[] logNotice, Throwable throwable)
          Logs a given notice and a throwable (Exception or Error) including a stack trace, if the given logLevel is equal or more important than the configured agent log level.
Independent of the given log level, logSystemInformation() is called, if the throwable is an instance of java.lang.Error.
Example: 2001-06-15 09:20:13.560[error][AgentDemo][demoMethod()]cannot parse time 'null' ^^^ java.lang.NumberFormatException: null at java.lang.Long.parseLong(Long.java:284) at java.lang.Long.(Long.java:526) at com.ls.lars.AgentDemo.demoMethod(AgentDemo.java:230) at com.ls.lars.AgentDemo.interpret(AgentDemo.java:174) at com.ls.lars.AgentTemplate.executeConfigFileInterpretation(AgentTemplate.java, Compiled Code) at com.ls.lars.AgentTemplate.run(AgentTemplate.java, Compiled Code)
 void log(String className, int logLevel, String methodName, String logNotice)
          Logs a given notice, if the given logLevel is equal or more important than the configured agent log level.
Example: 2001-06-15 09:20:13.560[warning][AgentDemo][demoMethod()]this is a great warning log message
 void log(String className, int logLevel, String methodName, String logNotice, Throwable throwable)
          Logs a given notice and a throwable (Exception or Error) including a stack trace, if the given logLevel is equal or more important than the configured agent log level.
Independent of the given log level, logSystemInformation() is called, if the throwable is an instance of java.lang.Error.
Example: 2001-06-15 09:20:13.560[error][AgentDemo][demoMethod()]cannot parse time 'null' ^^^ java.lang.NumberFormatException: null at java.lang.Long.parseLong(Long.java:284) at java.lang.Long.(Long.java:526) at com.ls.lars.AgentDemo.demoMethod(AgentDemo.java:230) at com.ls.lars.AgentDemo.interpret(AgentDemo.java:174) at com.ls.lars.AgentTemplate.executeConfigFileInterpretation(AgentTemplate.java, Compiled Code) at com.ls.lars.AgentTemplate.run(AgentTemplate.java, Compiled Code)
 void log(String className, int logLevel, String methodName, Throwable throwable)
          Logs a throwable (Exception or Error) including a stack trace, if the given logLevel is equal or more important than the configured agent log level.
Independent of the given log level, logSystemInformation() is called, if the throwable is an instance of java.lang.Error.
Example: 2001-06-15 09:20:13.560[error][AgentDemo][demoMethod()] ^^^ java.lang.NumberFormatException: null at java.lang.Long.parseLong(Long.java:284) at java.lang.Long.(Long.java:526) at com.ls.lars.AgentDemo.demoMethod(AgentDemo.java:230) at com.ls.lars.AgentDemo.interpret(AgentDemo.java:174) at com.ls.lars.AgentTemplate.executeConfigFileInterpretation(AgentTemplate.java, Compiled Code) at com.ls.lars.AgentTemplate.run(AgentTemplate.java, Compiled Code)
 void logSystemInformation()
          calls logSystemInformation on all configured system error log implementations and logs the output with log level ILogger.LEVEL_INDEPENDENT to this log file
 void logThreadName(boolean loggingThreadName)
          turns on or off the thread name specification
 void replacementMapPutAll(Map map)
          Puts map to the replacement map, which is used for exchanging variables in a logfile's name with values (for example replace $A with the name of the owning agent).
 boolean setLogFile(String logFileName)
          changes the log file to another file
 void setLogLevel(int logLevel)
          Sets the agent's log level.
 void setLogLevel(String logLevel)
          Sets the agent's log level.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Logger

public Logger()
Empty constructor. If this constructor is used all log messages will be outputted to the console (as long, as the setLogFile(java.lang.String) method is not called).

Note: variable substitution for logfile names cannot work the way you expect (e.g. exchanging $A with the agents' name) as long as you do not call replacementMapPutAll().


Logger

public Logger(String logFileName,
              Map map)
Constructor that includes trying to open the file where the log messages get stored.
Parameters:
logFileName - name of the log file
map - a Map containing variable/value pairs needed for variable substitution in log file names (e.g. for exchanging $A with the agent's name)

Logger

public Logger(String logFileName,
              int logLevel,
              Map map)
Constructor that includes trying to open the file where the log messages get stored and setting the log level.
Parameters:
logFileName - name of the log file
logLevel - determines which messages should be logged
map - a Map containing variable/value pairs needed for variable substitution in log file names (e.g. for exchanging $A with the agent's name)
Method Detail

closeLogFile

public void closeLogFile()
closes the logfile
Specified by:
closeLogFile in interface ILogger
Following copied from interface: com.ls.service.log.ILogger
Throws:
LogException - If any error occures while closing the log file

logSystemInformation

public void logSystemInformation()
calls logSystemInformation on all configured system error log implementations and logs the output with log level ILogger.LEVEL_INDEPENDENT to this log file
Specified by:
logSystemInformation in interface ILogger
See Also:
LoggerFactory.clearSystemErrorLogs(), LoggerFactory.addSystemErrorLog(ISystemErrorLog), LoggerFactory.getSystemErrorLogNames()

canLog

public boolean canLog(int logLevel)
determines, if a notice with the given log level will be logged
Specified by:
canLog in interface ILogger
Parameters:
logLevel - log level to compare against the configured log level
Returns:
true, if the given logLevel is equal or more important than the configured agent log level; false else

log

public void log(String className,
                int logLevel,
                String methodName,
                String logNotice,
                Throwable throwable)
Logs a given notice and a throwable (Exception or Error) including a stack trace, if the given logLevel is equal or more important than the configured agent log level.
Independent of the given log level, logSystemInformation() is called, if the throwable is an instance of java.lang.Error.
Example:
 2001-06-15 09:20:13.560[error][AgentDemo][demoMethod()]cannot parse time 'null'
 ^^^ java.lang.NumberFormatException: null
	at java.lang.Long.parseLong(Long.java:284)
	at java.lang.Long.(Long.java:526)
	at com.ls.lars.AgentDemo.demoMethod(AgentDemo.java:230)
	at com.ls.lars.AgentDemo.interpret(AgentDemo.java:174)
	at com.ls.lars.AgentTemplate.executeConfigFileInterpretation(AgentTemplate.java, Compiled Code)
	at com.ls.lars.AgentTemplate.run(AgentTemplate.java, Compiled Code)
 
Specified by:
log in interface ILogger
Parameters:
className - name of the class in which the log message was created
logLevel - level of the message (ILogger.TRACE5 ... ILogger.ERROR) determining, if the notice gets logged or ignored
methodName - name of the method in which the log message was created
logNotice - content of the log message
throwable - Throwable (Exception or Error) that should be logged

log

public void log(String className,
                int logLevel,
                String methodName,
                Object[] logNotice,
                Throwable throwable)
Logs a given notice and a throwable (Exception or Error) including a stack trace, if the given logLevel is equal or more important than the configured agent log level.
Independent of the given log level, logSystemInformation() is called, if the throwable is an instance of java.lang.Error.
Example:
 2001-06-15 09:20:13.560[error][AgentDemo][demoMethod()]cannot parse time 'null'
 ^^^ java.lang.NumberFormatException: null
	at java.lang.Long.parseLong(Long.java:284)
	at java.lang.Long.(Long.java:526)
	at com.ls.lars.AgentDemo.demoMethod(AgentDemo.java:230)
	at com.ls.lars.AgentDemo.interpret(AgentDemo.java:174)
	at com.ls.lars.AgentTemplate.executeConfigFileInterpretation(AgentTemplate.java, Compiled Code)
	at com.ls.lars.AgentTemplate.run(AgentTemplate.java, Compiled Code)
 
Specified by:
log in interface ILogger
Parameters:
className - name of the class in which the log message was created
logLevel - level of the message (ILogger.TRACE5 ... ILogger.ERROR) determining, if the notice gets logged or ignored
methodName - name of the method in which the log message was created
logNotice - content of the log message
throwable - Throwable (Exception or Error) that should be logged

log

public void log(String className,
                int logLevel,
                String methodName,
                Throwable throwable)
Logs a throwable (Exception or Error) including a stack trace, if the given logLevel is equal or more important than the configured agent log level.
Independent of the given log level, logSystemInformation() is called, if the throwable is an instance of java.lang.Error.
Example:
 2001-06-15 09:20:13.560[error][AgentDemo][demoMethod()]
 ^^^ java.lang.NumberFormatException: null
	at java.lang.Long.parseLong(Long.java:284)
	at java.lang.Long.(Long.java:526)
	at com.ls.lars.AgentDemo.demoMethod(AgentDemo.java:230)
	at com.ls.lars.AgentDemo.interpret(AgentDemo.java:174)
	at com.ls.lars.AgentTemplate.executeConfigFileInterpretation(AgentTemplate.java, Compiled Code)
	at com.ls.lars.AgentTemplate.run(AgentTemplate.java, Compiled Code)
 
Specified by:
log in interface ILogger
Parameters:
className - Name of the class in which the log message was created
logLevel - level of the message (ILogger.TRACE5 ... ILogger.ERROR) determining, if the notice gets logged or ignored
methodName - Name of the method in which the log message was created
throwable - Throwable (Exception or Error) that should be logged

log

public void log(String className,
                int logLevel,
                String methodName,
                String logNotice)
Logs a given notice, if the given logLevel is equal or more important than the configured agent log level.
Example:
 2001-06-15 09:20:13.560[warning][AgentDemo][demoMethod()]this is a great warning log message
 
Specified by:
log in interface ILogger
Parameters:
className - Name of the class in which the logMessage was created
logLevel - level of the message (ILogger.TRACE5 ... ILogger.ERROR) determining, if the notice gets logged or ignored
methodName - Name of the method in which the logMessage was created
logNotice - Content of the logMessage

log

public void log(String className,
                int logLevel,
                String methodName,
                Object[] logNotice)
Logs a given notice, if the given logLevel is equal or more important than the configured agent log level.
Example:
 2001-06-15 09:20:13.560[warning][AgentDemo][demoMethod()]this is a great warning log message
 
Specified by:
log in interface ILogger
Parameters:
className - Name of the class in which the logMessage was created
logLevel - level of the message (ILogger.TRACE5 ... ILogger.ERROR) determining, if the notice gets logged or ignored
methodName - Name of the method in which the logMessage was created
logNotice - Content of the logMessage

finalize

protected void finalize()
closes the log file if this object gets deleted
Overrides:
finalize in class Object

replacementMapPutAll

public void replacementMapPutAll(Map map)
Puts map to the replacement map, which is used for exchanging variables in a logfile's name with values (for example replace $A with the name of the owning agent).
Note: The new key/value pairs will not be used until the next log file is opened!
Specified by:
replacementMapPutAll in interface ILogger
Parameters:
map - a Map containing replacement variables as keys and replacements as values
See Also:
HashMap.putAll(Map)

setLogLevel

public void setLogLevel(int logLevel)
Sets the agent's log level. The agent's log level is used to specify if message of a cretain level has to be logged: If the log level of a log message is at least as important the agent's log level, the message is written, otherwise it is ignored.
Specified by:
setLogLevel in interface ILogger
Parameters:
logLevel - log level as an integer (use defined constants like ILogger.WARNING)

setLogLevel

public void setLogLevel(String logLevel)
                 throws LogException
Sets the agent's log level. The agent's log level is used to specify if message of a cretain level has to be logged: If the log level of a log message is at least as important the agent's log level, the message is written, otherwise it is ignored.
Specified by:
setLogLevel in interface ILogger
Parameters:
logLevel - name of one of the defined constants (e.g. "error"), case is ignored
Throws:
LogException - If given log level is null or unknown
See Also:
LoggerFactory.translateLogLevel(String)

getLogLevel

public int getLogLevel()
Returns the current loglevel as number. Example: 0=ERROR, 1=WARNING, 2=INFO, 3=TRACE ...
Specified by:
getLogLevel in interface ILogger
Returns:
the current loglevel

getLogLevelString

public String getLogLevelString()
Returns gets the name of the current log level. Example: ERROR, WARNING, INFO, TRACE ....
Specified by:
getLogLevelString in interface ILogger
Returns:
Name of the current loglevel

logThreadName

public void logThreadName(boolean loggingThreadName)
turns on or off the thread name specification
Specified by:
logThreadName in interface ILogger
Parameters:
loggingThreadName - specifies if the name of the thread is gona be logged

setLogFile

public boolean setLogFile(String logFileName)
changes the log file to another file
Specified by:
setLogFile in interface ILogger
Parameters:
logFileName - name of the file to be used as log file
Returns:
false, if the new log file could not be opened or the old one could not be closed; true else

hasLogFile

public boolean hasLogFile()
Checks, if this Logger instance uses a log file or System.out for logging.
Specified by:
hasLogFile in interface ILogger
Returns:
true, if a log file is in use; false if System.out is in use

getLogFileName

public String getLogFileName()
gets name of log file, which is currently in use
Specified by:
getLogFileName in interface ILogger
Returns:
log file's name or "System.out", if no log file is in use

getLogType

public byte getLogType()
Returns the log type of this logger.
Specified by:
getLogType in interface ILogger
Returns:
The log type of this logger (LARS)

getLogTypeString

public String getLogTypeString()
Returns the log type of this logger, as a string
Specified by:
getLogTypeString in interface ILogger
Returns:
The log type of this logger (LARS)