org.eclipse.hyades.logging.commons
Class Logger

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

All Implemented Interfaces:

IPreemptedLogger, org.apache.commons.logging.Log

public class Logger

extends java.lang.Object

implements org.apache.commons.logging.Log, IPreemptedLogger

Implementation of the Apache Commons org.apache.commons.logging.Log interface which represents a logger for logging messages to a Logging Agent with the same name as the logger.

The logging level is used to filter which severity of logged messages are sent to the Logging Agent with the same name as the logger. 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 default 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.Logger... - or - System.setProperty("org.apache.commons.logging.Log","org.eclipse.hyades.logging.commons.Logger"); 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.Logger");

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.Logger.LoggerLevel at logger creation. For example, ...-Dorg.eclipse.hyades.logging.commons.Logger.Level=DEBUG... - or - System.setProperty("org.eclipse.hyades.logging.commons.Logger.Level","DEBUG"); 2) Programmatically set the logging level. For example, logger.setLevelAsString("DEBUG"); - or - logger.setLevel(Logger.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.Logger"); System.setProperty("org.eclipse.hyades.logging.commons.Logger.Level", "DEBUG");

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.Logger instances (see org.eclipse.hyades.logging.commons.LoggerFactory).

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 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 Logger 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

Since:

April 1, 2003

See Also:

Log, LogFactory, LoggingAgent, LoggerFactory

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.
protected LoggingAgent	loggingAgent The Logging Agent with the same name as the logger to which successfully logged messages are sent.
static int	TRACE_LEVEL Trace logging level value.
static int	WARN_LEVEL Warning logging level value.

Constructor Summary

Logger(java.lang.String name)
Constructor to create a logger instance with a Logging Agent using the parameter name.

Method Summary

void	debug(java.lang.Object record) Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger 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 Logging Agent with the same name as the logger if DEBUG logging is currently enabled.
void	error(java.lang.Object record) Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger 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 Logging Agent with the same name as the logger if ERROR logging is currently enabled.
void	fatal(java.lang.Object record) Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger 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 Logging Agent with the same name as the logger if FATAL logging is currently enabled.
void	finalize() De-registers this Logging Agent instance from the Agent Controller.
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 Logging Agent with the same name as the logger 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 Logging Agent with the same name as the logger 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 Logging Agent is logging (e.g.
boolean	isTraceEnabled() Checks if TRACE logging is currently enabled.
boolean	isWarnEnabled() Checks if WARN logging is currently enabled.
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 Logging Agent with the same name as the logger 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 Logging Agent with the same name as the logger if TRACE logging is currently enabled.
boolean	waitUntilLogging(long maxTime) Suspends the current thread until the Logging Agent is monitored or the the parameter maximum time (milliseconds) has expired.
void	warn(java.lang.Object record) Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger 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 Logging Agent with the same name as the logger if WARN logging is currently enabled.

Methods inherited from class java.lang.Object

clone, 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

loggingAgent

protected LoggingAgent loggingAgent

The Logging Agent with the same name as the logger to which successfully logged messages are sent.

Constructor Detail

Logger

public Logger(java.lang.String name)

Constructor to create a logger instance with a Logging Agent using 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 Logging Agent with the same name as the logger if TRACE logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

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 Logging Agent with the same name as the logger if TRACE logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent. The parameter java.lang.Object log record is first logged and then the java.lang.Throwable exception is logged to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

throwable - The exception to be logged to the Logging Agent.

debug

public void debug(java.lang.Object record)

Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger if DEBUG logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

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 Logging Agent with the same name as the logger if DEBUG logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent. The parameter java.lang.Object log record is first logged and then the java.lang.Throwable exception is logged to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

throwable - The exception to be logged to the Logging Agent.

info

public void info(java.lang.Object record)

Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger if INFO logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

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 Logging Agent with the same name as the logger if INFO logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent. The parameter java.lang.Object log record is first logged and then the java.lang.Throwable exception is logged to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

throwable - The exception to be logged to the Logging Agent.

warn

public void warn(java.lang.Object record)

Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger if WARN logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

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 Logging Agent with the same name as the logger if WARN logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent. The parameter java.lang.Object log record is first logged and then the java.lang.Throwable exception is logged to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

throwable - The exception to be logged to the Logging Agent.

error

public void error(java.lang.Object record)

Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger if ERROR logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

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 Logging Agent with the same name as the logger if ERROR logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent. The parameter java.lang.Object log record is first logged and then the java.lang.Throwable exception is logged to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

throwable - The exception to be logged to the Logging Agent.

fatal

public void fatal(java.lang.Object record)

Logs the parameter java.lang.Object log record to the Logging Agent with the same name as the logger if FATAL logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

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 Logging Agent with the same name as the logger if FATAL logging is currently enabled. The log record is first converted to XML and then sent to the Logging Agent. The parameter java.lang.Object log record is first logged and then the java.lang.Throwable exception is logged to the Logging Agent.

Specified by:

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

Parameters:

record - The log record to be logged to the Logging Agent.

throwable - The exception to be logged to the Logging Agent.

getName

public java.lang.String getName()

Retrieves the name of this logger.

Returns:

Name of this logger.

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.

finalize

public final void finalize()

De-registers this Logging Agent instance from the Agent Controller.

Specified by:

finalize in interface IPreemptedLogger

See Also:

Object.finalize()

waitUntilLogging

public boolean waitUntilLogging(long maxTime)

Suspends the current thread until the Logging Agent is monitored or the the parameter maximum time (milliseconds) has expired.

Specified by:

waitUntilLogging in interface IPreemptedLogger

Parameters:

maxTime - the maximum amount of time (milliseconds) to suspend the current thread

Returns:

true if the logger is being monitored

isLogging

public boolean isLogging()

Checks if the Logging Agent is logging (e.g. Agent Controller is available and the Logging Agent is being monitored).

Specified by:

isLogging in interface IPreemptedLogger

Returns:

True if the Logging Agent is logging, otherwise false.