totalcross.util

Class Logger

java.lang.Object

totalcross.util.Logger

public class Logger
extends java.lang.Object

A Logger object is used to log messages for a specific system or application component. Loggers are normally named, using a hierarchical dot-separated namespace. Logger names can be arbitrary strings, but they should normally be based on the package name or class name of the logged component, such as totalcross.net or totalcross.io. In addition it is possible to retrieve one global "anonymous" Logger that can be used in the whole system. A logger can be created or retrieved (if it already exists) by calling getLogger. To dispose a logger after using it, just call dispose and it will be permanently discarded. To log a message, you may call the log method or any of the other convenience methods (info, severe, entering, etc).

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL ALL indicates that all messages should be logged.
static int	CONFIG CONFIG is a message level for static configuration messages.
static Stream	DEBUG_CONSOLE Stream where the bytes are written to the debug console
static int	FINE FINE is a message level providing tracing information.
static int	FINER FINER indicates a fairly detailed tracing message.
static int	FINEST FINEST indicates a highly detailed tracing message.
static int	INFO INFO is a message level for informational messages.
static int	OFF OFF is a special level that can be used to turn off logging.
static int	SEVERE SEVERE is a message level indicating a serious failure.
static int	WARNING WARNING is a message level indicating a potential problem.

Method Summary

Modifier and Type	Method and Description
void	addOutputHandler(Stream output) Adds an output stream to the logger's output handler set.
void	config(java.lang.String message) Log a CONFIG message.
void	dispose(boolean closeOutputHandlers) Permanently discard this logger, removing it from the loggers registry.
void	entering(java.lang.String sourceClass, java.lang.String sourceMethod, java.lang.String params) Log a method entry.
void	exiting(java.lang.String sourceClass, java.lang.String sourceMethod) Log a method return.
void	fine(java.lang.String message) Log a FINE message.
void	finer(java.lang.String message) Log a FINER message.
void	finest(java.lang.String message) Log a FINEST message.
static int	getDefaultLevel() Returns the initial logger level, which is used when a new logger is created.
static java.lang.String	getDefaultSeparator() Returns the initial message separator, which is used when a new logger is created.
static Logger	getGlobalLogger() Returns the global anonymous logger.
int	getLevel() Returns the current logger level.
static Logger	getLogger(java.lang.String name) Returns the logger with a specific name, keeping its level and output handlers unchanged.
static Logger	getLogger(java.lang.String name, int level) Returns the logger with a specific name, setting the level specified and keeping the output handlers unchanged.
static Logger	getLogger(java.lang.String name, int level, Stream outputStream) Returns the logger with a specific name, setting the level specified and optionally adding the given stream to the list of output handlers.
java.lang.String	getName() Returns the logger name.
Stream[]	getOutputHandlers() Get the output handlers associated with this logger.
java.lang.String	getSeparator() Gets the string used to separate two log messages.
void	info(java.lang.String message) Log a INFO message.
void	log(int level, java.lang.String message, boolean prependInfo) Logs a given message.
void	logInfo(java.lang.StringBuffer message) Used internally.
boolean	removeOutputHandler(Stream output) Removes an output handler from the logger's output handler set.
static void	setDefaultLevel(int level) Sets the initial logger level, which will be used when a new logger is created.
static void	setDefaultSeparator(java.lang.String separator) Sets the initial message separator, which will be used when a new logger is created.
void	setLevel(int level) Sets the current logger level.
void	setSeparator(java.lang.String separator) Sets the string used to separate two log messages.
void	severe(java.lang.String message) Log a SEVERE message.
void	throwing(java.lang.String sourceClass, java.lang.String sourceMethod, java.lang.Throwable thrown) Log throwing an exception.
void	warning(java.lang.String message) Log a WARNING message.

Methods inherited from class java.lang.Object

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

Field Detail

OFF

public static final int OFF

OFF is a special level that can be used to turn off logging.

See Also:

Constant Field Values

FINEST

public static final int FINEST

FINEST indicates a highly detailed tracing message.

See Also:

Constant Field Values

FINER

public static final int FINER

FINER indicates a fairly detailed tracing message.

See Also:

Constant Field Values

FINE

public static final int FINE

FINE is a message level providing tracing information.

See Also:

Constant Field Values

CONFIG

public static final int CONFIG

CONFIG is a message level for static configuration messages.

See Also:

Constant Field Values

INFO

public static final int INFO

INFO is a message level for informational messages.

See Also:

Constant Field Values

WARNING

public static final int WARNING

WARNING is a message level indicating a potential problem.

See Also:

Constant Field Values

SEVERE

public static final int SEVERE

SEVERE is a message level indicating a serious failure.

See Also:

Constant Field Values

ALL

public static final int ALL

ALL indicates that all messages should be logged.

See Also:

Constant Field Values

DEBUG_CONSOLE

public static final Stream DEBUG_CONSOLE

Stream where the bytes are written to the debug console

Method Detail

getLogger

public static Logger getLogger(java.lang.String name)

Returns the logger with a specific name, keeping its level and output handlers unchanged. If the logger does not exist, it will be created and stored for future use.

Parameters:

name - The logger name.

Returns:

The logger.

Throws:

java.lang.NullPointerException - if name is null.

getLogger

public static Logger getLogger(java.lang.String name,
                               int level)

Returns the logger with a specific name, setting the level specified and keeping the output handlers unchanged. If the logger does not exist, it will be created and stored for future use.

Parameters:

name - The logger name.

level - The logger level to set or -1 to keep it unchanged.

Returns:

The logger.

Throws:

java.lang.NullPointerException - if name is null.

getLogger

public static Logger getLogger(java.lang.String name,
                               int level,
                               Stream outputStream)

Returns the logger with a specific name, setting the level specified and optionally adding the given stream to the list of output handlers. If the logger does not exist, it will be created and stored for future use.

Parameters:

name - The logger name.

level - The logger level to set or -1 to keep it unchanged.

outputStream - The stream to add to the logger's list of output handlers or null to keep it unchanged.

Returns:

The logger.

Throws:

java.lang.NullPointerException - if name is null.

getGlobalLogger

public static Logger getGlobalLogger()

Returns the global anonymous logger.

Returns:

Always return the global logger.

getName

public java.lang.String getName()

Returns the logger name.

Returns:

The name provided when this logger was created or null, if this is the global anonymous logger.

getLevel

public int getLevel()

Returns the current logger level.

Returns:

An integer number representing the current logger level. To check if the logger is set to log a specific type of message (SEVERE, WARNING, etc), just check if the level OR'ed with the message level is different than zero.

setLevel

public void setLevel(int level)

Sets the current logger level.

Parameters:

level - The logger level to set. This should be a composition of one or more of the message types constants (FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE) or OFF, if you want to disable all logging, or ALL, if you want to enable all logging.

setDefaultLevel

public static void setDefaultLevel(int level)

Sets the initial logger level, which will be used when a new logger is created.

Parameters:

level - The logger level to set. This should be a composition of one or more of the message types constants (FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE) or OFF, if you want to disable all logging, or ALL, if you want to enable all logging.

getDefaultLevel

public static int getDefaultLevel()

Returns the initial logger level, which is used when a new logger is created.

Returns:

An integer number representing the default logger level.

getSeparator

public java.lang.String getSeparator()

Gets the string used to separate two log messages.

Returns:

The string written after each log message.

setSeparator

public void setSeparator(java.lang.String separator)

Sets the string used to separate two log messages.

Parameters:

separator - The string written after each log message.

setDefaultSeparator

public static void setDefaultSeparator(java.lang.String separator)

Sets the initial message separator, which will be used when a new logger is created. A separator is a string that separates two log messages (e.g.: \n (newline), white spaces, etc).

Parameters:

separator - The separator string.

getDefaultSeparator

public static java.lang.String getDefaultSeparator()

Returns the initial message separator, which is used when a new logger is created. A separator is a string that separates two log messages (e.g.: \n (newline), white spaces, etc).

Returns:

The separator string.

addOutputHandler

public void addOutputHandler(Stream output)

Adds an output stream to the logger's output handler set. This means that every logged message (depending on the current logger level) will be written to this stream.

Parameters:

output - The output stream.

removeOutputHandler

public boolean removeOutputHandler(Stream output)

Removes an output handler from the logger's output handler set.

Parameters:

output - The output stream.

Returns:

True, if and only if, the stream was successfully removed.

getOutputHandlers

public Stream[] getOutputHandlers()

Get the output handlers associated with this logger.

Returns:

An array of all registered output handlers.

log

public void log(int level,
                java.lang.String message,
                boolean prependInfo)

Logs a given message.

Parameters:

level - The message level.

message - The message to log.

prependInfo - A flag indicating whether this log message must be prepended with the current date and time, level string, logger name, etc.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

logInfo

public void logInfo(java.lang.StringBuffer message)

Used internally.

finest

public void finest(java.lang.String message)

Log a FINEST message. If the logger is currently enabled for the FINEST message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

finer

public void finer(java.lang.String message)

Log a FINER message. If the logger is currently enabled for the FINER message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

fine

public void fine(java.lang.String message)

Log a FINE message. If the logger is currently enabled for the FINE message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

config

public void config(java.lang.String message)

Log a CONFIG message. If the logger is currently enabled for the CONFIG message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

info

public void info(java.lang.String message)

Log a INFO message. If the logger is currently enabled for the INFO message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

warning

public void warning(java.lang.String message)

Log a WARNING message. If the logger is currently enabled for the WARNING message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

severe

public void severe(java.lang.String message)

Log a SEVERE message. If the logger is currently enabled for the SEVERE message level then the given message is written to all the registered output handler streams.

Parameters:

message - The message to log.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

entering

public void entering(java.lang.String sourceClass,
                     java.lang.String sourceMethod,
                     java.lang.String params)

Log a method entry. This is a convenience method that can be used to log entry to a method. A record with message "ENTRY", log level FINER, and the given sourceMethod and sourceClass is logged.

Parameters:

sourceClass - The name of class that issued the logging request.

sourceMethod - name of method that is being entered.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

exiting

public void exiting(java.lang.String sourceClass,
                    java.lang.String sourceMethod)

Log a method return. This is a convenience method that can be used to log entry to a method. A record with message "RETURN", log level FINER, and the given sourceMethod and sourceClass is logged.

Parameters:

sourceClass - The name of class that issued the logging request.

sourceMethod - The name of method that is being returned.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

throwing

public void throwing(java.lang.String sourceClass,
                     java.lang.String sourceMethod,
                     java.lang.Throwable thrown)

Log throwing an exception. This is a convenience method to log that a method is terminating by throwing an exception. The logging is done using the FINER level. If the logger is currently enabled for the given message level then the record is forwarded to all registered output handlers. The record's message is set to "THROW".

Parameters:

sourceClass - he name of class that issued the logging request.

sourceMethod - The name of method that is throwing the exception.

thrown - The Throwable that is being thrown.

Throws:

java.lang.NullPointerException - if one or more registered output handler streams are null or this logger has been disposed.

dispose

public void dispose(boolean closeOutputHandlers)

Permanently discard this logger, removing it from the loggers registry.

Parameters:

closeOutputHandlers - If true, all output handler streams will be closed before disposing this logger.