com.rapidminer.tools
Class LogService

java.lang.Object
  com.rapidminer.tools.LogService

All Implemented Interfaces:

LoggingHandler

public class LogService
extends java.lang.Object
implements LoggingHandler

Utility class providing static methods for logging.
Parameters read from the XML process configuration file:

• logfile (filename or "stdout" or "stderr")
• logverbosity (possible values are in LOG_VERBOSITY_NAMES

Beside the local log service associated with a concrete process and which will be automatically initialized during the setup phase, one global log service exist which is used for generic log messages not bound to the operators used in a process. This global log service is usually initialized to log messages on system out (at least during the basic initialization phase of RapidMiner). After the basic intialization phase, the global messages will be presented in the message viewer (if the RapidMiner GUI is used) or still printed to system out or in any other stream defined via the method initGlobalLogging(OutputStream, int). Alternatively, one could also define an environment variable named RapidMiner.PROPERTY_RAPIDMINER_GLOBAL_LOG_FILE.

Usually, operators should only use the log verbosities MINIMUM for messages with a low priority and STATUS for normal information messages. In rare cases, the verbosity level NOTE could be used for operators stating some message more important then STATUS (hence the user should see the message for the default log verbosity level of INIT) but not as important then WARNING. The verbosity levels WARNING, EXCEPTION, and ERROR should be used in error cases. All other log verbosity levels should only be used by internal RapidMiner classes and not by user written operators.

We recommend to set the parameter for the log verbosity level to INIT for the process design phase (eventually STATUS for debugging) and to the log verbosity level WARNING in the production phase. This way it is ensured that not too many logging messages are produced in the production phase.

Log messages can be formatted by using the following macros:

• "$b" and "^b" start and end bold mode respectively
• "$i" and "^i" start and end italic mode respectively
• "$m" and "^m" start and end monospace mode respectively
• "$n" and "^n" start and end note color mode respectively
• "$w" and "^w" start and end warning color mode respectively
• "$e" and "^e" start and end error color mode respectively

Author:

Ingo Mierswa

Field Summary

static int	ERROR Use this log verbosity for logging of errors.
static int	FATAL Use this log verbosity for logging of fatal errors which will stop process running somewhere in the future.
static java.lang.String	GLOBAL_PREFIX The prefix used to indicate the global logger.
static int	INIT Only the most important logging messaged should use this log verbosity.
static int	IO Indicates log messages concerning in- and output.
static java.lang.String[]	LOG_VERBOSITY_NAMES
static int	MAXIMUM Normally this log verbosity should not be used by operators.
static int	MINIMUM Indicates the lowest log verbosity.
static int	NOTE Use this log verbosity for logging of important notes, i.e. things less important than warnings but important enough to see for all not interested in the detailed status messages.
static int	OFF For switching off logging during testing.
static int	STATUS The default log verbosity for all logging purposes of operators.
static int	UNKNOWN_LEVEL Indicates an unknown verbosity level.
static int	WARNING Use this log verbosity for logging of warnings.

Constructor Summary

LogService(Process process)
Creates a log service for this process.

LogService(Process process, int logVerbosity)
Creates a log service for this process.

Method Summary

void	flush() Flush the streams.
static LogService	getGlobal() Returns the global logging.
java.io.File	getLogFile() Returns the current log file or null.
int	getVerbosityLevel()
static void	initGlobalLogging(java.io.OutputStream out, int logVerbosity) Initializes the global logging, i.e. the global log service not bound to a concrete process.
void	initGUI()
boolean	isSufficientLogVerbosity(int level)
void	log(java.lang.String message) Logs a status message with the correct log service.
void	log(java.lang.String message, int verbosityLevel) Writes the message to the output stream if the verbosity level is high enough.
void	logError(java.lang.String message) Logs an error message with the correct log service.
void	logFinalException(java.lang.String message, Process process, java.lang.Throwable exception, boolean debugMode) Writes the message and the stack trace of the exception.
static void	logMessage(java.lang.String message, int verbosityLevel) Deprecated. please do not use this log method any longer, use the method log(String, int) instead
void	logNote(java.lang.String message) Logs a note message with the correct log service.
void	logWarning(java.lang.String message) Logs a warning message with the correct log service.
void	setVerbosityLevel(int level)

Methods inherited from class java.lang.Object

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

Field Detail

GLOBAL_PREFIX

public static final java.lang.String GLOBAL_PREFIX

The prefix used to indicate the global logger.

See Also:

Constant Field Values

UNKNOWN_LEVEL

public static final int UNKNOWN_LEVEL

Indicates an unknown verbosity level.

See Also:

Constant Field Values

MINIMUM

public static final int MINIMUM

Indicates the lowest log verbosity. Should only be used for very detailed but not necessary logging.

See Also:

Constant Field Values

IO

public static final int IO

Indicates log messages concerning in- and output. Should only be used by the class Operator itself and not by its subclasses.

See Also:

Constant Field Values

STATUS

public static final int STATUS

The default log verbosity for all logging purposes of operators.

See Also:

Constant Field Values

INIT

public static final int INIT

Only the most important logging messaged should use this log verbosity. Currently used only by the LogService itself.

See Also:

Constant Field Values

NOTE

public static final int NOTE

Use this log verbosity for logging of important notes, i.e. things less important than warnings but important enough to see for all not interested in the detailed status messages.

See Also:

Constant Field Values

WARNING

public static final int WARNING

Use this log verbosity for logging of warnings.

See Also:

Constant Field Values

ERROR

public static final int ERROR

Use this log verbosity for logging of errors.

See Also:

Constant Field Values

FATAL

public static final int FATAL

Use this log verbosity for logging of fatal errors which will stop process running somewhere in the future.

See Also:

Constant Field Values

MAXIMUM

public static final int MAXIMUM

Normally this log verbosity should not be used by operators. Messages with this verbosity will always be displayed.

See Also:

Constant Field Values

OFF

public static final int OFF

For switching off logging during testing.

See Also:

Constant Field Values

LOG_VERBOSITY_NAMES

public static final java.lang.String[] LOG_VERBOSITY_NAMES

Constructor Detail

LogService

public LogService(Process process)
           throws UndefinedParameterError

Creates a log service for this process. The properties (possible log file and log verbosity) are taken from the process parameters.

Throws:

UndefinedParameterError

LogService

public LogService(Process process,
                  int logVerbosity)
           throws UndefinedParameterError

Creates a log service for this process. The properties (possible log file and log verbosity) are taken from the process parameters. If the given logVerbosity is a valid verbosity level, then this level is used instead of the level defined in the process. Otherwise, the given log verbosity must have value UNKNOWN_LEVEL and the process level will be used.

Throws:

UndefinedParameterError

Method Detail

getGlobal

public static LogService getGlobal()

Returns the global logging. If no logging was otherwise create, this method creates the default standard out log service if no log file was defined in the property RapidMiner.PROPERTY_RAPIDMINER_GLOBAL_LOG_FILE. Alternatively, developers can invoke the method initGlobalLogging(OutputStream, int).

initGlobalLogging

public static void initGlobalLogging(java.io.OutputStream out,
                                     int logVerbosity)

Initializes the global logging, i.e. the global log service not bound to a concrete process. Usually, system out or the message viewer (GUI) are used for global log messages.

initGUI

public void initGUI()
             throws UndefinedParameterError

Throws:

UndefinedParameterError

flush

public void flush()

Flush the streams.

setVerbosityLevel

public void setVerbosityLevel(int level)

getVerbosityLevel

public int getVerbosityLevel()

isSufficientLogVerbosity

public boolean isSufficientLogVerbosity(int level)

logMessage

@Deprecated
public static void logMessage(java.lang.String message,
                                         int verbosityLevel)

Deprecated. please do not use this log method any longer, use the method log(String, int) instead

Writes the message to the output stream if the verbosity level is high enough.

log

public void log(java.lang.String message,
                int verbosityLevel)

Writes the message to the output stream if the verbosity level is high enough.

logFinalException

public void logFinalException(java.lang.String message,
                              Process process,
                              java.lang.Throwable exception,
                              boolean debugMode)

Writes the message and the stack trace of the exception. This method should not be used from operators but only at the end of processes. This will be ensured by RapidMiner itself. If RapidMiner is not used in debug mode, the stack trace will not be shown.

getLogFile

public java.io.File getLogFile()

Returns the current log file or null.

log

public void log(java.lang.String message)

Description copied from interface: LoggingHandler

Logs a status message with the correct log service.

Specified by:

log in interface LoggingHandler

logError

public void logError(java.lang.String message)

Description copied from interface: LoggingHandler

Logs an error message with the correct log service.

Specified by:

logError in interface LoggingHandler

logNote

public void logNote(java.lang.String message)

Description copied from interface: LoggingHandler

Logs a note message with the correct log service.

Specified by:

logNote in interface LoggingHandler

logWarning

public void logWarning(java.lang.String message)

Description copied from interface: LoggingHandler

Logs a warning message with the correct log service.

Specified by:

logWarning in interface LoggingHandler