de.itechsoftware.itloglib2
Class ITLogMsg

Object
  |
  +--de.itechsoftware.itloglib2.ITLogMsg

public class ITLogMsg

extends Object

Logmessages are flexible container objects collecting information about the logging application.

Each logmessage is linked to a (primary) output logchannel (represented by an ITOutputLogChannel instance). The output behaviour of such output logchannels can be (re)configured at runtime (using online configuration) (using the ITConfigManager application).

ITLogMsg objects are optimized for usability and performance, for instance:

• Logmessages will (transparently) not be created if their output is prevented by the current write-out filter of their logchannel(s).
• The creation of logmessages can be controlled via online configuration.
• Logmessages don't get lost if you forget to send them. They will be sent then by later garbage collections, with a corresponding warning message added to the logmessage text. You can search for such logmessages using a filter in the ITLogBook application.

Constructor Summary

ITLogMsg()
Contructs a null (or empty) LogMsg instance.

ITLogMsg(String sModule, String sCase)
Contructs a logmessage with default loglevel (LEVEL_INFO) for the default logchannel ('StdLog').

ITLogMsg(String sModule, String sCase, short shtLogLevel)
Constructs a logmessage for the default logchannel 'StdLog'.

ITLogMsg(String sModule, String sCase, short shtLogLevel, String sLogChannel)
Constructs a logmessage for a given logchannel.

Method Summary

void	add(char c) Streams a character to the logmessage text.
void	add(double d) Streams a double to the logmessage text.
void	add(float f) Streams a float to the logmessage text.
void	add(int i) Streams an integer to the logmessage text.
void	add(String sText) Streams a string to the logmessage text.
void	addLogLevel(short shtLogLevel) Adds an additional loglevel to the current loglevel of the logmessage.
boolean	addParam(String sName, char c) Adds a named char parameter including its value to the logmessage.
boolean	addParam(String sName, char c, boolean bCopyValueToMsgText) Adds a named char parameter including its value to the logmessage.
boolean	addParam(String sName, char c, boolean bCopyValueToMsgText, boolean bCopyParamNameToMsgText) Adds a named char parameter including its value to the logmessage.
boolean	addParam(String sName, double d) Adds a named double parameter including its value to the logmessage.
boolean	addParam(String sName, double d, boolean bCopyValueToMsgText) Adds a named double parameter including its value to the logmessage.
boolean	addParam(String sName, double d, boolean bCopyValueToMsgText, boolean bCopyParamNameToMsgText) Adds a named double parameter including its value to the logmessage.
boolean	addParam(String sName, float f) Adds a named float parameter including its value to the logmessage.
boolean	addParam(String sName, float f, boolean bCopyValueToMsgText) Adds a named float parameter including its value to the logmessage.
boolean	addParam(String sName, float f, boolean bCopyValueToMsgText, boolean bCopyParamNameToMsgText) Adds a named float parameter including its value to the logmessage.
boolean	addParam(String sName, int i) Adds a named integer parameter including its value to the logmessage.
boolean	addParam(String sName, int i, boolean bCopyValueToMsgText) Adds a named integer parameter including its value to the logmessage.
boolean	addParam(String sName, int i, boolean bCopyValueToMsgText, boolean bCopyParamNameToMsgText) Adds a named integer parameter including its value to the logmessage.
boolean	addParam(String sName, String sValue) Adds a named string parameter including its value to the logmessage.
boolean	addParam(String sName, String sValue, boolean bCopyValueToMsgText) Adds a named string parameter including its value to the logmessage.
boolean	addParam(String sName, String sValue, boolean bCopyValueToMsgText, boolean bCopyParamNameToMsgText) Adds a named string parameter including its value to the logmessage.
boolean	cancel() Prevents the logmessage from sending to its output logchannel(s).
void	create(String sModule, String sCase) Creates a logmessage with default loglevel (LEVEL_INFO) for the default logchannel ('StdLog').
void	create(String sModule, String sCase, short shtLogLevel) Creates a logmessage for the default logchannel 'StdLog'.
void	create(String sModule, String sCase, short shtLogLevel, String sLogChannel) Creates a logmessage for a given logchannel.
protected void	finalize() Sends the logmessage automatically to its logchannel(s), by calling its send() method.
String	getCase() Returns the case name of the logmessage.
String	getLogChannelName() Returns the name of the (primary) logchannel as passed in the constructor or create method.
short	getLogLevel() Returns the loglevel (combination) of the logmessage.
String	getModule() Returns the module name of the logmessage.
String	getText() Returns the logmessage text.
String	getTimeAsString() Returns the timestamp (date and time) of the logmessage as a string.
boolean	isNullLogMsg() Returns whether the logmessage is the null LogMsg object, a special instance used for performance optimization of suppressed logmessages.
boolean	send() Sends the logmessage -- as it currently is -- to its output logchannel(s).
void	setLogLevel(short shtLogLevel) Sets the loglevel (combination) of the logmessage.
boolean	willBeLogged() Returns whether the logmessage will be logged by at least one of its (forwarding) logchannels.
boolean	willBeLoggedTo(String sLogChannel) Returns whether the logmessage will be logged to a special (forwarding) logchannel.

Methods inherited from class Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ITLogMsg

public ITLogMsg()

Contructs a null (or empty) LogMsg instance.

Internally all these null instances refer to the same empty implementation object, which has empty add(java.lang.String), addLogLevel(short) and similar methods for performance optimization.

Depending the control flow of your programm, you may create a non-null logmessage in a subsequent call to one of the create(java.lang.String, java.lang.String) methods of this ITLogMsginstance.

ITLogMsg

public ITLogMsg(String sModule,
                String sCase)

Contructs a logmessage with default loglevel (LEVEL_INFO) for the default logchannel ('StdLog').

Note: If the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file), the object is automatically changed internally to a null logmessage (a special, performance optimized ITLogMsg instance).

Parameters:

sModule - user-defined specifier, describing a module or subsystem of the logging application.

sCase - user-defined specifier, describing a use case or operation of the logging application.

ITLogMsg

public ITLogMsg(String sModule,
                String sCase,
                short shtLogLevel)

Constructs a logmessage for the default logchannel 'StdLog'.

Note: If the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file) the object is switched automatically to a null logmessage (a special, performance optimized ITLogMsg instance).

Parameters:

sModule - user-defined specifier, describing a module or subsystem of the logging application.

sCase - user-defined specifier, describing a use case or operation of the logging application.

shtLogLevel - one or more ITLogLevel constants (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, LEVEL_ALARM), combined by '|' (bitwise or).

ITLogMsg

public ITLogMsg(String sModule,
                String sCase,
                short shtLogLevel,
                String sLogChannel)

Constructs a logmessage for a given logchannel.

Note: If the logchannel is not open or the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file) the object automatically is switched to a null logmessage (a special, performance optimized ITLogMsg instance).

Parameters:

sModule - user-defined specifier, describing a module or subsystem of the logging application.

sCase - user-defined specifier, describing a use case or operation of the logging application.

shtLogLevel - one or more ITLogLevel constants (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, LEVEL_ALARM), combined by '|' (bitwise or).

Method Detail

finalize

protected void finalize()

Sends the logmessage automatically to its logchannel(s), by calling its send() method. Please don't rely on this mechanism, as it isn't secure and also sends the logmessage very late, not at the moment it should be sent. Send logmessages yourself when they are ready to be sent!

Overrides:

finalize in class Object

See Also:

ITLogMsg.send

isNullLogMsg

public boolean isNullLogMsg()

Returns whether the logmessage is the null LogMsg object, a special instance used for performance optimization of suppressed logmessages.

Note: The write-out filter(s) of the (forwarding) logchannel(s) determine(s) during the creation of the logmessage if it will be logged or not.

Returns:

true if the logmessage is the null LogMsg object
false otherwise

See Also:

ITLogMsg.willBeLogged, ITLogMsg.willBeLoggedTo, ITLogMsg.cancel

create

public void create(String sModule,
                   String sCase)

Creates a logmessage with default loglevel (LEVEL_INFO) for the default logchannel ('StdLog').

Note: If the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file) the object automatically is switched to a null logmessage (a special, performance optimized ITLogMsg instance).

Note: If the object is reused, the previous logmessage will be sent automatically.

Parameters:

sModule - user-defined specifier, describing a module or subsystem of the logging application.

sCase - user-defined specifier, describing a use case or operation of the logging application.

See Also:

ITLogMsg.send

create

public void create(String sModule,
                   String sCase,
                   short shtLogLevel)

Creates a logmessage for the default logchannel 'StdLog'.

Note: If the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file), the object automatically is switched to the a null logmessage (a special, performance optimized ITLogMsg instance).

Note: If the object is reused, the previous logmessage will be sent automatically.

Parameters:

sModule - user-defined specifier, describing a module or subsystem of the logging application.

sCase - user-defined specifier, describing a use case or operation of the logging application.

shtLogLevel - one or more ITLogLevel constants (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, LEVEL_ALARM), combined by '|' (bitwise or).

See Also:

ITLogMsg.send

create

public void create(String sModule,
                   String sCase,
                   short shtLogLevel,
                   String sLogChannel)

Creates a logmessage for a given logchannel.

Note: If the logchannel is not open or the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file), the object automatically is switched to a null logmessage (a a special, performance optimized ITLogMsg instance).

Note: If the object is reused, the previous logmessage will be sent automatically.

Parameters:

sModule - user-defined specifier, describing a module or subsystem of the logging application.

sCase - user-defined specifier, describing a use case or operation of the logging application.

shtLogLevel - one or more ITLogLevel constants (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, LEVEL_ALARM), combined by '|' (bitwise or).

See Also:

ITLogMsg.send

add

public void add(String sText)

Streams a string to the logmessage text.

Note: This method does nothing if the logmessage will not be logged.

Parameters:

sText - Text string to append to the logmessage text.

See Also:

ITLogMsg.willBeLogged

add

public void add(char c)

Streams a character to the logmessage text.

Note: This method does nothing if the logmessage will not be logged.

Parameters:

c - character to append to the logmessage text.

See Also:

ITLogMsg.willBeLogged

add

public void add(int i)

Streams an integer to the logmessage text.

Note: This method does nothing if the logmessage will not be logged.

Parameters:

i - integer value to append (as string) to the logmessage text.

See Also:

ITLogMsg.willBeLogged

add

public void add(double d)

Streams a double to the logmessage text.

Note: This method does nothing if the logmessage will not be logged.

Parameters:

d - double value to append (as string) to the logmessage text.

See Also:

ITLogMsg.willBeLogged

add

public void add(float f)

Streams a float to the logmessage text.

Note: This method does nothing if the logmessage will not be logged.

Parameters:

f - float value to append (as string) to the logmessage text.

See Also:

ITLogMsg.willBeLogged

send

public boolean send()

Sends the logmessage -- as it currently is -- to its output logchannel(s).

Note:

• After this call ITLogMsg.willBeLogged always return true
• The object can be reused by calling one of its create methods.

Returns:

true if the logmessage was sent by this call (That is, if ITLogMsg.willBeLogged returned true before the call.)
false otherwise

See Also:

ITLogMsg.cancel, ITLogMsg.isNullLogMsg, ITLogMsg.willBeLogged, ITLogMsg.willBeLoggedTo

cancel

public boolean cancel()

Prevents the logmessage from sending to its output logchannel(s).

Note:

• After this call ITLogMsg.willBeLogged always return true
• The object can be reused by calling one of its create methods.

Returns:

true if the logmessage was cancelled by this call (That is, if ITLogMsg.willBeLogged returned true before the call.)
false otherwise

See Also:

ITLogMsg.send, ITLogMsg.isNullLogMsg, ITLogMsg.willBeLogged, ITLogMsg.willBeLoggedTo

willBeLogged

public boolean willBeLogged()

Returns whether the logmessage will be logged by at least one of its (forwarding) logchannels.

Note: The write-out filter(s) of the (forwarding) logchannel(s) determin(e) during its creation if the logmessage will be logged or not.

Returns:

true if the logmessage will be logged (is created, but not cancelled or already sent)
false otherwise

See Also:

ITLogMsg.willBeLoggedTo, ITLogMsg.cancel, ITLogMsg.isNullLogMsg

willBeLoggedTo

public boolean willBeLoggedTo(String sLogChannel)

Returns whether the logmessage will be logged to a special (forwarding) logchannel.

Note: The write-out filter(s) of the (forwarding) logchannel(s) determine(s) during the creation of the logmessage if it will be logged or not. *

Parameters:

sLogChannel - name of the logchannel to test.

Returns:

true if the logmessage will be logged to this logchannel (is created, but not cancelled or already sent)
false otherwise

See Also:

ITLogMsg.willBeLogged, ITLogMsg.isNullLogMsg, ITLogMsg.cancel

getLogChannelName

public String getLogChannelName()

Returns the name of the (primary) logchannel as passed in the constructor or create method.

Returns:

logchannel name if the logmessage will be logged. (That is, if ITLogMsg.willBeLogged returned true)
empty string otherwise

See Also:

ITLogMsg.getLogLevel, ITLogMsg.getTimeAsString, ITLogMsg.getModule, ITLogMsg.getCase, ITLogMsg.getText

getLogLevel

public short getLogLevel()

Returns the loglevel (combination) of the logmessage.

Note: Use the '&' operator (bitwise AND) to extract a single loglevel bit value (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR or LEVEL_ALARM).

Returns:

loglevel if the logmessage will be logged. (That is, if ITLogMsg.willBeLogged returned true)
empty string otherwise

See Also:

ITLogMsg.getLogChannelName, ITLogMsg.getTimeAsString, ITLogMsg.getModule, ITLogMsg.getCase, ITLogMsg.getText

getTimeAsString

public String getTimeAsString()

Returns the timestamp (date and time) of the logmessage as a string.

Note: The format of the timestamp is 'DD.MM.YYYY hh:mm:ss'

Returns:

timestamp string if the logmessage will be logged. (That is, if ITLogMsg.willBeLogged returned true)
empty string otherwise

See Also:

ITLogMsg.getLogChannelName, ITLogMsg.getLogLevel, ITLogMsg.getModule, ITLogMsg.getCase, ITLogMsg.getText

getModule

public String getModule()

Returns the module name of the logmessage.

Returns:

module name if the logmessage will be logged. (That is, if ITLogMsg.willBeLogged returned true)
empty string otherwise

See Also:

ITLogMsg.getLogChannelName, ITLogMsg.getLogLevel, ITLogMsg.getTimeAsString, ITLogMsg.getCase, ITLogMsg.getText

getCase

public String getCase()

Returns the case name of the logmessage.

Returns:

case name if the logmessage will be logged. (That is, if ITLogMsg.willBeLogged returned true)
empty string otherwise

See Also:

ITLogMsg.getLogChannelName, ITLogMsg.getLogLevel, ITLogMsg.getTimeAsString, ITLogMsg.getModule, ITLogMsg.getText

getText

public String getText()

Returns the logmessage text.

Returns:

text if the logmessage will be logged. (That is, if ITLogMsg.willBeLogged returned true)
empty string otherwise

See Also:

ITLogMsg.getLogChannelName, ITLogMsg.getLogLevel, ITLogMsg.getTimeAsString, ITLogMsg.getModule, ITLogMsg.getCase

setLogLevel

public void setLogLevel(short shtLogLevel)

Sets the loglevel (combination) of the logmessage.

Parameters:

shtLogLevel - one or more Loglevel constants (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, LEVEL_ALARM), combined by '|' (bitwise OR).

See Also:

ITLogMsg.addLogLevel, ITLogMsg.getLogLevel

addLogLevel

public void addLogLevel(short shtLogLevel)

Adds an additional loglevel to the current loglevel of the logmessage.

Parameters:

shtLogLevel - one or more Loglevel constants (LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, LEVEL_ALARM), combined by '|' (bitwise OR).

See Also:

ITLogMsg.setLogLevel, ITLogMsg.getLogLevel

addParam

public boolean addParam(String sName,
                        String sValue)

Adds a named string parameter including its value to the logmessage.

Parameters:

sName - parameter name

sValue - parameter value

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        String sValue,
                        boolean bCopyValueToMsgText)

Adds a named string parameter including its value to the logmessage.

Parameters:

sName - parameter name

sValue - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended to the logmessage text.

Note:

• if the parameter value will be appended no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        String sValue,
                        boolean bCopyValueToMsgText,
                        boolean bCopyParamNameToMsgText)

Adds a named string parameter including its value to the logmessage.

Parameters:

sName - parameter name

sValue - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended to the logmessage text.

bCopyParamNameToMsgText - indicates if the parameter name will additionally be appended to the logmessage text.

Note:

• If both option flags are set, the appendings will be made in the following form: Name=Value
• In any case, no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        char c)

Adds a named char parameter including its value to the logmessage.

Parameters:

sName - parameter name

c - parameter value

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        char c,
                        boolean bCopyValueToMsgText)

Adds a named char parameter including its value to the logmessage.

Parameters:

sName - parameter name

c - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended to the logmessage text.

Note:

• if the parameter value will be appended no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        char c,
                        boolean bCopyValueToMsgText,
                        boolean bCopyParamNameToMsgText)

Adds a named char parameter including its value to the logmessage.

Parameters:

sName - parameter name

c - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended to the logmessage text.

bCopyParamNameToMsgText - indicates if the parameter name will additionally be appended to the logmessage text.

Note:

• If both option flags are set, the appendings will be made in the following form: Name=Value
• In any case, no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        int i)

Adds a named integer parameter including its value to the logmessage.

Parameters:

sName - parameter name

i - parameter value

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        int i,
                        boolean bCopyValueToMsgText)

Adds a named integer parameter including its value to the logmessage.

Parameters:

sName - parameter name

i - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended as a string to the logmessage text.

Note:

• if the parameter value will be appended no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        int i,
                        boolean bCopyValueToMsgText,
                        boolean bCopyParamNameToMsgText)

Adds a named integer parameter including its value to the logmessage.

Parameters:

sName - parameter name

i - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended as a string to the logmessage text.

bCopyParamNameToMsgText - indicates if the parameter name will additionally be appended to the logmessage text.

Note:

• If both option flags are set, the appendings will be made in the following form: Name=Value
• In any case, no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        double d)

Adds a named double parameter including its value to the logmessage.

Parameters:

sName - parameter name

d - parameter value

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        double d,
                        boolean bCopyValueToMsgText)

Adds a named double parameter including its value to the logmessage.

Parameters:

sName - parameter name

d - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended as a string to the logmessage text.

Note:

• if the parameter value will be appended no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        double d,
                        boolean bCopyValueToMsgText,
                        boolean bCopyParamNameToMsgText)

Adds a named double parameter including its value to the logmessage.

Parameters:

sName - parameter name

d - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended as a string to the logmessage text.

bCopyParamNameToMsgText - indicates if the parameter name will additionally be appended to the logmessage text.

Note:

• If both option flags are set, the appendings will be made in the following form: Name=Value
• In any case, no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        float f)

Adds a named float parameter including its value to the logmessage.

Parameters:

sName - parameter name

f - parameter value

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        float f,
                        boolean bCopyValueToMsgText)

Adds a named float parameter including its value to the logmessage.

Parameters:

sName - parameter name

f - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended as a string to the logmessage text.

Note:

• if the parameter value will be appended no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true

addParam

public boolean addParam(String sName,
                        float f,
                        boolean bCopyValueToMsgText,
                        boolean bCopyParamNameToMsgText)

Adds a named float parameter including its value to the logmessage.

Parameters:

sName - parameter name

f - parameter value

bCopyValueToMsgText - indicates if the parameter value will additionally be appended as a string to the logmessage text.

bCopyParamNameToMsgText - indicates if the parameter name will additionally be appended to the logmessage text.

Note:

• If both option flags are set, the appendings will be made in the following form: Name=Value
• In any case, no spaces or whitespace will be added to the logmessage text.

Returns:

currently always true