org.eclipse.hyades.logging.commons
Class FileLogger

java.lang.Object
  org.eclipse.hyades.logging.commons.FileLogger

All Implemented Interfaces:

org.apache.commons.logging.Log

public class FileLogger
extends java.lang.Object
implements org.apache.commons.logging.Log

Implementation of the Apache Commons org.apache.commons.logging.Log interface which represents a logger for logging messages to a local log file.

A Common Base Event start event is logged whenever this logger begins logging to the local log file. Conversely, a Common Base Event stop event is logged whenever this logger finishes logging to the local log file.

The logging level is used to filter which severity of logged messages are sent to the local log file. The logging level may be set to one of the following logging levels:

-TRACE (least serious and most verbose) -DEBUG -INFO -WARN -ERROR -FATAL (most serious and least verbose)

An instance of this class will be returned from the getLog() and/or getInstance() APIs on the default org.apache.commons.logging.LogFactory implementation. The org.apache.commons.logging.LogFactory implementation uses the following discovery process to resolve the configured org.apache.commons.logging.Log implementation:

1) Look for a system property named org.apache.commons.logging.Log or org.apache.commons.logging.log. For example, ...-Dorg.apache.commons.logging.Log=org.eclipse.hyades.logging.commons.FileLogger... - or - System.setProperty("org.apache.commons.logging.Log","org.eclipse.hyades.logging.commons.FileLogger"); 2) Look for a configuration attribute of the default org.apache.commons.logging.LogFactory implementation named org.apache.commons.logging.Log. For example, org.apache.commons.logging.LogFactory.getFactory().setAttribute("org.apache.commons.logging.Log","org.eclipse.hyades.logging.commons.FileLogger");

An instance of this class may be configured to log to a local log file (e.g. absolute or relative path to the local log file) using one of the following methods:

1) Look for a system property named org.eclipse.hyades.logging.commons.FileLogger.FileName at logger creation. For example, ...-Dorg.eclipse.hyades.logging.commons.FileLogger.FileName=/tmp/myLogFile.log... NOTE: The absolute or relative path to the local log file must be enclosed in double quotes (e.g. "") if contains one or more spaces. - or - System.setProperty("org.eclipse.hyades.logging.commons.FileLogger.FileName","/tmp/myLogFile.log"); 2) Programmatically set the absolute or relative path to the local log file. For example, logger.setFileName("/tmp/myLogFile.log");

An instance of this class may be configured with a logging level using one of the following methods (see above for the supported levels):

1) Look for a system property named org.eclipse.hyades.logging.commons.FileLogger.LoggerLevel at logger creation. For example, ...-Dorg.eclipse.hyades.logging.commons.FileLogger.Level=DEBUG... - or - System.setProperty("org.eclipse.hyades.logging.commons.FileLogger.Level","DEBUG"); 2) Programmatically set the logging level. For example, logger.setLevelAsString("DEBUG"); - or - logger.setLevel(FileLogger.DEBUG_LEVEL);

A logger instance is created and returned when the getLog() and/or getInstance() APIs on the default org.apache.commons.logging.LogFactory implementation are called. Once created, the logger is configurable (e.g. logging level). The logger is generally consulted on its configuration before every message is logged for performance reasons. For example,

System.setProperty("org.apache.commons.logging.Log", "org.eclipse.hyades.logging.commons.FileLogger"); System.setProperty("org.eclipse.hyades.logging.commons.FileLogger.Level", "DEBUG"); System.setProperty("org.eclipse.hyades.logging.commons.FileLogger.FileName", "/tmp/myLogFile.log");

Log logger = LogFactory.getLog("My Logger");

if(logger.isDebugEnabled()){ logger.debug("My first DEBUG log message."); logger.debug("My second DEBUG log message."); }

Alternatively, users may use the proxy factory specific for org.eclipse.hyades.logging.commons.FileLogger instances (see org.eclipse.hyades.logging.commons.FileLoggerFactory).

Logged java.lang.Object messages are converted to Common Base Event XML based on a generic serialization algorithm as implemented in org.eclipse.hyades.logging.events.cbe.util.EventHelpers#convertObjectToCommonBaseEvent(Object,int) before being logged to the Logging Agent.

Callers may provide a Common Base Event XML file template (see org.eclipse.hyades.logging.core/schema/templateEvent.xsd) to configure the newly created Common Base Event before serialization to XML. The template Event XML file is a well-formed XML document conforming to a predefined XML schema (e.g. templateEvent.xsd). The naming convention used for the template Event XML file is:

<logger name>.event.xml

where <logger name> is the name of this file logger. For example, the template event XML file for the myLogger logger factory would be named myLogger.event.xml.

The desired event configuration template XML file must by on the classpath and accessible by this class. The event configuration template XML file is loaded using the following look-up sequence:

1. The FileLogger class' class loader is queried for the event configuration template XML file.
2. The system's class loader is queried for the event configuration template XML file.
3. The current thread's context class loader is queried for the event configuration template XML file.

NOTE: The Apache Commons logging classes must be on the CLASSPATH at runtime to utilize this logging class

See Also:

Log, LogFactory, FileLoggerFactory

Field Summary

static int	DEBUG_LEVEL Debug logging level value.
static int	ERROR_LEVEL Error logging level value.
static int	FATAL_LEVEL Fatal logging level value.
static int	INFO_LEVEL Information logging level value.
static int	TRACE_LEVEL Trace logging level value.
static int	WARN_LEVEL Warning logging level value.

Constructor Summary

FileLogger(java.lang.String name)
Constructor to create a logger instance with the parameter name.

Method Summary

void	debug(java.lang.Object record) Logs the parameter java.lang.Object log record to the local log file if DEBUG logging is currently enabled.
void	debug(java.lang.Object record, java.lang.Throwable throwable) Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if DEBUG logging is currently enabled.
void	error(java.lang.Object record) Logs the parameter java.lang.Object log record to the local log file if ERROR logging is currently enabled.
void	error(java.lang.Object record, java.lang.Throwable throwable) Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if ERROR logging is currently enabled.
void	fatal(java.lang.Object record) Logs the parameter java.lang.Object log record to the local log file if FATAL logging is currently enabled.
void	fatal(java.lang.Object record, java.lang.Throwable throwable) Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if FATAL logging is currently enabled.
void	finalize() Closes the file handle to the local log file.
java.lang.String	getFileName() Returns the absolute or relative path to the local log file.
int	getLevel() Retrieves the integer level of this logger.
java.lang.String	getLevelAsString() Retrieves the string level of this logger.
java.lang.String	getName() Retrieves the name of this logger.
void	info(java.lang.Object record) Logs the parameter java.lang.Object log record to the local log file if INFO logging is currently enabled.
void	info(java.lang.Object record, java.lang.Throwable throwable) Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if INFO logging is currently enabled.
boolean	isDebugEnabled() Checks if DEBUG logging is currently enabled.
boolean	isErrorEnabled() Checks if ERROR logging is currently enabled.
boolean	isFatalEnabled() Checks if FATAL logging is currently enabled.
boolean	isInfoEnabled() Checks if INFO logging is currently enabled.
boolean	isLogging() Checks if the logger is logging to a local log file.
boolean	isTraceEnabled() Checks if TRACE logging is currently enabled.
boolean	isWarnEnabled() Checks if WARN logging is currently enabled.
void	setFileName(java.lang.String fileName) Sets the absolute or relative path to the local log file.
void	setLevel(int level) Sets the logging level to one of the integer logging levels (i.e.
void	setLevelAsString(java.lang.String stringLevel) Sets the logging level to one of the string logging levels (i.e.
void	trace(java.lang.Object record) Logs the parameter java.lang.Object log record to the local log file if TRACE logging is currently enabled.
void	trace(java.lang.Object record, java.lang.Throwable throwable) Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if TRACE logging is currently enabled.
void	warn(java.lang.Object record) Logs the parameter java.lang.Object log record to the local log file if WARN logging is currently enabled.
void	warn(java.lang.Object record, java.lang.Throwable throwable) Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if WARN logging is currently enabled.

Methods inherited from class java.lang.Object

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

Field Detail

TRACE_LEVEL

public static final int TRACE_LEVEL

Trace logging level value.

See Also:

Constant Field Values

DEBUG_LEVEL

public static final int DEBUG_LEVEL

Debug logging level value.

See Also:

Constant Field Values

INFO_LEVEL

public static final int INFO_LEVEL

Information logging level value.

See Also:

Constant Field Values

WARN_LEVEL

public static final int WARN_LEVEL

Warning logging level value.

See Also:

Constant Field Values

ERROR_LEVEL

public static final int ERROR_LEVEL

Error logging level value.

See Also:

Constant Field Values

FATAL_LEVEL

public static final int FATAL_LEVEL

Fatal logging level value.

See Also:

Constant Field Values

Constructor Detail

FileLogger

public FileLogger(java.lang.String name)

Constructor to create a logger instance with the parameter name. NOTE: The default logging level is set to WARN until explicitly set.

Parameters:

name - The name of the newly created logger.

Method Detail

isTraceEnabled

public boolean isTraceEnabled()

Checks if TRACE logging is currently enabled. TRACE logging infers the logging level is currently set at TRACE or lower. This API permits an inexpensive check on logging level.

Specified by:

isTraceEnabled in interface org.apache.commons.logging.Log

Returns:

True if TRACE logging is currently enabled, otherwise false.

isDebugEnabled

public boolean isDebugEnabled()

Checks if DEBUG logging is currently enabled. DEBUG logging infers the logging level is currently set at DEBUG or lower. This API permits an inexpensive check on logging level.

Specified by:

isDebugEnabled in interface org.apache.commons.logging.Log

Returns:

True if DEBUG logging is currently enabled, otherwise false.

isInfoEnabled

public boolean isInfoEnabled()

Checks if INFO logging is currently enabled. INFO logging infers the logging level is currently set at INFO or lower. This API permits an inexpensive check on logging level.

Specified by:

isInfoEnabled in interface org.apache.commons.logging.Log

Returns:

True if INFO logging is currently enabled, otherwise false.

isWarnEnabled

public boolean isWarnEnabled()

Checks if WARN logging is currently enabled. WARN logging infers the logging level is currently set at WARN or lower. This API permits an inexpensive check on logging level.

Specified by:

isWarnEnabled in interface org.apache.commons.logging.Log

Returns:

True if WARN logging is currently enabled, otherwise false.

isErrorEnabled

public boolean isErrorEnabled()

Checks if ERROR logging is currently enabled. ERROR logging infers the logging level is currently set at ERROR or lower. This API permits an inexpensive check on logging level.

Specified by:

isErrorEnabled in interface org.apache.commons.logging.Log

Returns:

True if ERROR logging is currently enabled, otherwise false.

isFatalEnabled

public boolean isFatalEnabled()

Checks if FATAL logging is currently enabled. FATAL logging infers the logging level is currently set at FATAL or lower. This API permits an inexpensive check on logging level.

Specified by:

isFatalEnabled in interface org.apache.commons.logging.Log

Returns:

True if FATAL logging is currently enabled, otherwise false.

trace

public void trace(java.lang.Object record)

Logs the parameter java.lang.Object log record to the local log file if TRACE logging is currently enabled. The log record is first converted to XML and then written to the local log file.

Specified by:

trace in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

trace

public void trace(java.lang.Object record,
                  java.lang.Throwable throwable)

Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if TRACE logging is currently enabled. The log record and exception are first converted to XML and then written to the local log file.

Specified by:

trace in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

throwable - The exception to be logged to the local log file.

debug

public void debug(java.lang.Object record)

Logs the parameter java.lang.Object log record to the local log file if DEBUG logging is currently enabled. The log record is first converted to XML and then written to the local log file.

Specified by:

debug in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

debug

public void debug(java.lang.Object record,
                  java.lang.Throwable throwable)

Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if DEBUG logging is currently enabled. The log record and exception are first converted to XML and then written to the local log file.

Specified by:

debug in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

throwable - The exception to be logged to the local log file.

info

public void info(java.lang.Object record)

Logs the parameter java.lang.Object log record to the local log file if INFO logging is currently enabled. The log record is first converted to XML and then written to the local log file.

Specified by:

info in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

info

public void info(java.lang.Object record,
                 java.lang.Throwable throwable)

Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if INFO logging is currently enabled. The log record and exception are first converted to XML and then written to the local log file.

Specified by:

info in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

throwable - The exception to be logged to the local log file.

warn

public void warn(java.lang.Object record)

Logs the parameter java.lang.Object log record to the local log file if WARN logging is currently enabled. The log record is first converted to XML and then written to the local log file.

Specified by:

warn in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

warn

public void warn(java.lang.Object record,
                 java.lang.Throwable throwable)

Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if WARN logging is currently enabled. The log record and exception are first converted to XML and then written to the local log file.

Specified by:

warn in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

throwable - The exception to be logged to the local log file.

error

public void error(java.lang.Object record)

Logs the parameter java.lang.Object log record to the local log file if ERROR logging is currently enabled. The log record is first converted to XML and then written to the local log file.

Specified by:

error in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

error

public void error(java.lang.Object record,
                  java.lang.Throwable throwable)

Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if ERROR logging is currently enabled. The log record and exception are first converted to XML and then written to the local log file.

Specified by:

error in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

throwable - The exception to be logged to the local log file.

fatal

public void fatal(java.lang.Object record)

Logs the parameter java.lang.Object log record to the local log file if FATAL logging is currently enabled. The log record is first converted to XML and then written to the local log file.

Specified by:

fatal in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

fatal

public void fatal(java.lang.Object record,
                  java.lang.Throwable throwable)

Logs the parameter java.lang.Object log record and java.lang.Throwable exception to the local log file if FATAL logging is currently enabled. The log record and exception are first converted to XML and then written to the local log file.

Specified by:

fatal in interface org.apache.commons.logging.Log

Parameters:

record - The log record to be logged to the local log file.

throwable - The exception to be logged to the local log file.

getName

public java.lang.String getName()

Retrieves the name of this logger.

Returns:

Name of this logger.

setFileName

public void setFileName(java.lang.String fileName)
                 throws java.lang.IllegalArgumentException

Sets the absolute or relative path to the local log file.

Parameters:

fileName - The absolute or relative path to the local log file.

Throws:

java.lang.IllegalArgumentException - Attempting to set an illegal absolute or relative path to the local log file.

getFileName

public java.lang.String getFileName()

Returns the absolute or relative path to the local log file.

Returns:

The absolute or relative path to the local log file.

finalize

public final void finalize()

Closes the file handle to the local log file.

Overrides:

finalize in class java.lang.Object

See Also:

Object.finalize()

isLogging

public boolean isLogging()

Checks if the logger is logging to a local log file.

Returns:

True if the logger is logging to a local log file, otherwise false.

getLevel

public int getLevel()

Retrieves the integer level of this logger.

Returns:

Integer logging level of this logger (i.e. TRACE_LEVEL - FATAL_LEVEL).

getLevelAsString

public java.lang.String getLevelAsString()

Retrieves the string level of this logger.

Returns:

String logging level of this logger (i.e. "TRACE" - "FATAL").

setLevel

public void setLevel(int level)
              throws java.lang.IllegalArgumentException

Sets the logging level to one of the integer logging levels (i.e. TRACE_LEVEL - FATAL_LEVEL).

Parameters:

level - The new integer logging level (i.e. TRACE_LEVEL - FATAL_LEVEL).

Throws:

java.lang.IllegalArgumentException - Attempting to set an illegal integer logging level.

setLevelAsString

public void setLevelAsString(java.lang.String stringLevel)
                      throws java.lang.IllegalArgumentException

Sets the logging level to one of the string logging levels (i.e. "TRACE" - "FATAL").

Parameters:

stringLevel - The new string logging level (i.e. "TRACE" - "FATAL").

Throws:

java.lang.IllegalArgumentException - Attempting to set an illegal string logging level.