de.itechsoftware.itloglib2
Class ITLogLib

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

public class ITLogLib

extends Object

This class represents a singleton which provides the administrative methods of the logging library. All methods are static
ITLogLib is used to:

• initialize/deinitialize the library
• open/close user-defined logchannels
• get detailled information about occurred errors
• provide some useful global helper methods

Method Summary

static boolean	closeLogChannel(String sLogChannelName) Closes the designated logchannel - if open an flushes all pending logmessages.
static boolean	deinitialize() Deinitializes the logging library - if not already deinitialized.
static String	getConfigFile() Returns the name of the configuration file.
static int	getLastErrorCode() Returns the error code of the last error.
static String	getLastErrorDescription() Returns details about the last unsuccessful method call.
static ITOutputLogChannel	getLogChannel(String sLogChannelName) Returns an instance for the designated logchannel.
static String	getRegistrySettingCurrentUser(String sKeyName, String sValueName) Helper method - Reads Windows registry string data from HKEY_CURRENT_USER.
static String	getRegistrySettingLocalMachine(String sKeyName, String sValueName) Helper method - Reads Windows registry string data from HKEY_LOCAL_MACHINE.
static boolean	initialize(String sAppName, String sConfigFile, String sLicenseKey) Initializes the logging library - if not already initialized.
static boolean	isInitialized() Returns the initialization status of the logging library.
static ITOutputLogChannel	openLogChannel(String sLogChannelName) Opens a logchannel - if not already opened.
static void	quickLog(String sModule, String sCase, String sText) Creates a logmessage with default loglevel (LEVEL_INFO) and sends it to the default logchannel ('StdLog') (in a single statement).
static void	quickLog(String sModule, String sCase, String sText, short shtLogLevel) Creates a logmessage and send it to the default logchannel 'StdLog'.
static void	quickLog(String sModule, String sCase, String sText, short shtLogLevel, String sLogChannelName) Creates a logmessage and sends it to the specified logchannel.
static boolean	runApplication(String sApplication) Helper method - Calls runApplication(sApplication, "", "")
static boolean	runApplication(String sApplication, String sParameters) Helper method - Calls runApplication(sApplication, sParameters, "")
static boolean	runApplication(String sApplication, String sParameters, String sDefaultDir) Helper method - Starts an external application like ITLogBook, ITConfigManager or any other program.

Methods inherited from class Object

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

Method Detail

initialize

public static boolean initialize(String sAppName,
                                 String sConfigFile,
                                 String sLicenseKey)

Initializes the logging library - if not already initialized.
It loads the configuration file and opens the standard logchannel ('StdLog') according to the settings in the configuration file.

Parameters:

sAppName - the name of your logging application.

sConfigFile - the name of the logging configuration file (*.icf). If necessary, include the path. (The path can be absolute or relative to the working directory of your application.)

sLicenseKey - the license key for the logging library.

Returns:

true after successful initialization (You get this return value too, if the logging library already was initialized before the call.)
false if an error occurred.

Possible errors:

• The configuration file couldn't be found or doesn't contain an entry for the StdLog logchannel or this entry is incomplete.
• The license key is invalid.
• As always, in case of an error a detailed error description is available by calling ITLogLib.getLastErrorDescription

See Also:

ITLogLib.deinitialize, ITLogLib.isInitialized

deinitialize

public static boolean deinitialize()

Deinitializes the logging library - if not already deinitialized.
It closes all logchannels and thus flushing all pending logmessages.

Note that this method endlessly tries to flush the buffered logmessages and returns only after succeeding.

Returns:

true after successful deinitialization (You get this return value too if the logging library was not initialized before the call.)
false if an error occurred.

See Also:

ITLogLib.initialize, ITLogLib.isInitialized

isInitialized

public static boolean isInitialized()

Returns the initialization status of the logging library.

Returns:

true if the logging library initialized successfully
false otherwise

See Also:

ITLogLib.initialize, ITLogLib.deinitialize

openLogChannel

public static ITOutputLogChannel openLogChannel(String sLogChannelName)

Opens a logchannel - if not already opened.
If the logchannel isn't already open, it tries to open it according to the settings in the configuration file.

Note that the standard logchannel (StdLog) is already opened as part of a successful initialization of the logging library.

Parameters:

sLogChannelName - the name of the logchannel (case sensitive), as defined in the configuration file.

Returns:

the instance of the opened logchannel if successful, null otherwise.

Possible errors:

• The configuration file doesn't contain an entry for this logchannel or the entry is incomplete.

See Also:

ITLogLib.closeLogChannel, ITLogLib.getLogChannel, ITOutputLogChannel.isOpen

getLogChannel

public static ITOutputLogChannel getLogChannel(String sLogChannelName)

Returns an instance for the designated logchannel.
The logchannel must be opened before.

Parameters:

sLogChannelName - the name of the logchannel (case sensitive).

Returns:

the instance of the opened logchannel if successful
null otherwise.

See Also:

ITLogLib.openLogChannel, ITLogLib.closeLogChannel, ITOutputLogChannel.isOpen

closeLogChannel

public static boolean closeLogChannel(String sLogChannelName)

Closes the designated logchannel - if open an flushes all pending logmessages. This method endlessly tries to flush the buffered logmessages and returns only after succeeding.

Note that the standard logchannel 'StdLog' can not be closed explicitely.

Parameters:

sLogChannelName - the name of the logchannel (case sensitive).

Returns:

true if the logchannel closed successfully (You get this return value too if the logchannel wasn't open before the call.)
false otherwise

See Also:

ITLogLib.openLogChannel, ITLogLib.getLogChannel, ITOutputLogChannel.isOpen

getConfigFile

public static String getConfigFile()

Returns the name of the configuration file.

Returns:

the filename as passed in ITLogLib.initialize

See Also:

ITLogLib.initialize

getLastErrorCode

public static int getLastErrorCode()

Returns the error code of the last error.

Returns:

the error code of the last operation (0 if the last operation was successful)

See Also:

ITLogLib.getLastErrorDescription

getLastErrorDescription

public static String getLastErrorDescription()

Returns details about the last unsuccessful method call.

Returns:

the error description of the last operation (an empty string if the last operation was successful)

See Also:

ITLogLib.getLastErrorCode

quickLog

public static void quickLog(String sModule,
                            String sCase,
                            String sText)

Creates a logmessage with default loglevel (LEVEL_INFO) and sends it to the default logchannel ('StdLog') (in a single statement).

Note: If the logchannel was not open successfully or the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file), the logmessage will not be generated.

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.

sText - logmessage text.

quickLog

public static void quickLog(String sModule,
                            String sCase,
                            String sText,
                            short shtLogLevel)

Creates a logmessage and send it to the default logchannel 'StdLog'. (As a single statement)

Note: If the logchannel was not open successfully or the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file), the logmessage will not be generated.

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.

sText - logmessage text.

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

quickLog

public static void quickLog(String sModule,
                            String sCase,
                            String sText,
                            short shtLogLevel,
                            String sLogChannelName)

Creates a logmessage and sends it to the specified logchannel. (in a single statement)

Note: If the logchannel was not open successfully or the Module/Case combination does not pass the write-out filter condition (currently defined for the logchannel in the configuration file), the logmessage will not be generated.

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.

sText - logmessage text.

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

sLogChannelName - logchannel name.

runApplication

public static boolean runApplication(String sApplication,
                                     String sParameters,
                                     String sDefaultDir)

Helper method - Starts an external application like ITLogBook, ITConfigManager or any other program.
Use this function within your code to view the logfiles with the appropriate program (ITLogBook, web browser or text editor).

Sample:
To view the current logfile: ITLogLib.runApplication( ITLogLib.getLogChannel("StdLog").getCurrentLogFile(), "", "")
To view the current configuration file: ITLogLib.runApplication(ITLogLib.getConfigFile(), "", "")

Parameters:

sApplication - name of the application to start or name of a file (in the latter case the extension of the file must be associated with a program to start)

sParameters - parameters required by the started application (optional)

sDefaultDir - path to the default directory the application should work with (optional)

Returns:

true if successful
false otherwise.

runApplication

public static boolean runApplication(String sApplication,
                                     String sParameters)

Helper method - Calls runApplication(sApplication, sParameters, "")

runApplication

public static boolean runApplication(String sApplication)

Helper method - Calls runApplication(sApplication, "", "")

getRegistrySettingLocalMachine

public static String getRegistrySettingLocalMachine(String sKeyName,
                                                    String sValueName)

Helper method - Reads Windows registry string data from HKEY_LOCAL_MACHINE.

Parameters:

sKeyName - registry key (may include subkeys, separated by '\')

sValueName - registry value ("" to read the default value of the key)

Returns:

non-empty (or empty) string if data was found in the registry
empty string otherwise

See Also:

ITLogLib.getRegistrySettingCurrentUser

getRegistrySettingCurrentUser

public static String getRegistrySettingCurrentUser(String sKeyName,
                                                   String sValueName)

Helper method - Reads Windows registry string data from HKEY_CURRENT_USER.

Parameters:

sKeyName - registry key (may include subkeys, separated by '\')

sValueName - registry value ("" to read the default value of the key)

Returns:

non-empty (or empty) string if data was found in the registry
empty string otherwise

See Also:

ITLogLib.getRegistrySettingLocalMachine