cern.cmw
Class Logger

java.lang.Object
  cern.cmw.Logger

public abstract class Logger
extends Object

Defines a general API for message logging and allows to connect it to a system specific logging facility. An application can create an arbitrary number of named Logger objects, each logger can be used to log message for an application component or a specific activity in the application. Logger objects may be obtained by calls to the getLogger(java.lang.String) factory method.

 //
 // Get a logger for the "poller" subsystem
 //
 Logger pollerLog = Logger.getLogger("poller");
 //
 // Get a logger to trace timing events
 //
 Logger timingLog = Logger.getLogger("timing");
 

A logger can be used to log text messages at different levels. On each logging call the logger performs a check of the message level against a log level maintained by the logger. If the message level is higher than the log level, the logging call returns immediately, otherwise the message will be forwarded to the log output.

 //
 // Enable ERROR, WARNING and INFO messages
 //
 pollerLog.setLevel(Logger.LOG_INFO);
 //
 // This message will be not logged
 //
 pollerLog.debug("Entering Poller.init()");
 //
 // This message will be logged
 //
 pollerLog.info("Initializing poller");
 //
 // This message will be not logged
 //
 pollerLog.trace("Connecting to timing");
 //
 // This message will be logged
 //
 pollerLog.warning("Event source undefined, using default");
 //
 // This message will be logged
 //
 pollerLog.error("Can't connect to timing, exiting");
 

See also the main(java.lang.String[]) function of this class for an example of how to use loggers.

By default, Logger sends messages to the standard output. This default behaviour can be modified, and the messages can be forwarded to a system specific logging mechanism: see init(java.lang.String) and LoggerFactory for more details.

See Also:

"log4j"

Constructor Summary

protected

Logger(String name) Constructor.

Method Summary

void	debug(String message) Logs a DEBUG message.
static void	destroy() Calling this method will safely close the logging system and release all related resources.
void	error(String message) Logs an ERROR message.
static LogLevel	getDefaultLevel() Returns the default log level.
LogLevel	getLevel() Returns the log level maintained by this logger.
static Logger	getLogger(String name) Returns a logger identified by the name.
static Enumeration	getLoggers() Returns an enumeration of known loggers.
static String	getLoggingType() Returns a string identifier of the underlying logging mechanism, e.g. the string "default" for default logging.
String	getName() Returns the name of this logger.
void	info(String message) Logs an INFO message.
static void	init() Initializes the logging API and connects it to a system specific logging mechanism.
static void	init(String factory) Initializes the logging API and connects it to a system specific logging mechanism.
static boolean	initialized() Returns true if the logging system has been initialized.
boolean	isLoggable(LogLevel level) Returns true if a message of the given level would actually be logged by this logger.
protected abstract void	log(LogLevel level, String message) Forwards the message to the log output.
static void	main(String[] args) For tests.
static void	setDefaultLevel(LogLevel level) Sets the default log level to the specified level.
void	setLevel(LogLevel level) Sets the log level maintained by this logger.
static void	setLevels(LogLevel level) Sets the specified level in all loggers in the system.
void	trace(String message) Logs a TRACE message.
void	warning(String message) Logs a WARNING message.

Methods inherited from class java.lang.Object

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

Constructor Detail

Logger

protected Logger(String name)

Constructor.

Parameters:

name - the logger name

Method Detail

init

public static void init(String factory)

Initializes the logging API and connects it to a system specific logging mechanism. The logger objects created by the specified factory will be used to log messages. This method does nothing if the logging system has already been initialized.

Parameters:

factory - the fully qualified class name of the factory object

Throws:

CmwInternalError - thrown if the factory class cannot be loaded, or the class does not implement the LoggerFactory interface.

See Also:

LoggerFactory

init

public static void init()

Initializes the logging API and connects it to a system specific logging mechanism. The concrete LoggerFactory that will be used to instantiate logger objects is determined by the value of the cmw.loggerFactory config property. The value shall be a fully qualified name of the factory class, for example: cmw.loggerFactory=cmw.logging.L4JLoggerFactory If this property is not defined then the default logging will be used. This method does nothing if the logging system has already been initialized.

Throws:

CmwInternalError - thrown if the factory class specified by the property cannot be loaded, or the class does not implement the LoggerFactory interface.

See Also:

LoggerFactory

initialized

public static boolean initialized()

Returns true if the logging system has been initialized.

destroy

public static void destroy()

Calling this method will safely close the logging system and release all related resources.

getLogger

public static Logger getLogger(String name)

Returns a logger identified by the name. If such a logger does not exist it will be created. Calls to this method with the same name will always return the same object. A prefix may be prepended to the name based on cmw.logger.sourceType and cmw.logger.ID properties. This possibility is interesting when used with central logging systems. If a new logger is created its log level will be set from the class default log level. The initial value of the default log level is set at the initialization time from the cmw.defaultLogLevel property. If the property is not defined or has an invalid value, then the default level is LogLevel.OFF. The default level can be checked and changed at run time by calling the getDefaultLevel() and setDefaultLevel(cern.cmw.LogLevel) methods.

Throws:

CmwInternalError - thrown if the logging system is not initialized.

See Also:

"log4j"

getDefaultLevel

public static LogLevel getDefaultLevel()

Returns the default log level.

See Also:

getLogger

setDefaultLevel

public static void setDefaultLevel(LogLevel level)

Sets the default log level to the specified level.

See Also:

getLogger

getLevel

public LogLevel getLevel()

Returns the log level maintained by this logger.

setLevel

public void setLevel(LogLevel level)

Sets the log level maintained by this logger.

setLevels

public static void setLevels(LogLevel level)

Sets the specified level in all loggers in the system.

isLoggable

public boolean isLoggable(LogLevel level)

Returns true if a message of the given level would actually be logged by this logger.

getName

public String getName()

Returns the name of this logger.

error

public void error(String message)

Logs an ERROR message. If the logger is currently enabled for the LogLevel.ERROR level then the specified message is forwarded to the log output.

warning

public void warning(String message)

Logs a WARNING message. If the logger is currently enabled for the LogLevel.WARNING level then the specified message is forwarded to the log output.

info

public void info(String message)

Logs an INFO message. If the logger is currently enabled for the LogLevel.INFO level then the specified message is forwarded to the log output.

trace

public void trace(String message)

Logs a TRACE message. If the logger is currently enabled for the LogLevel.TRACE level then the specified message is forwarded to the log output.

debug

public void debug(String message)

Logs a DEBUG message. If the logger is currently enabled for the LogLevel.DEBUG level then the specified message is forwarded to the log output.

log

protected abstract void log(LogLevel level,
                            String message)

Forwards the message to the log output. This abstract method shall be implemented in all concrete loggers. Implementations don't need to filter message by level: this is already done in the logging methods of this class.

getLoggers

public static Enumeration getLoggers()

Returns an enumeration of known loggers. Loggers may be added dynamically as new classes are loaded. This method only reports on the loggers that are currently created.

getLoggingType

public static String getLoggingType()

Returns a string identifier of the underlying logging mechanism, e.g. the string "default" for default logging. Returns the string "undefined" if the logging system is not initialized.

main

public static void main(String[] args)

For tests. This function can be used to check the logging system in your current environment. If, for example, you are using a complex logging system with a central log server, then you can run it to verify that the messages arrive to the destination.

   public static void main(String[] args)
   {
      try
      {
         Config.load();
         Logger.init();
      }
      catch(Exception ex)
      {
         System.out.println(ex);
         System.exit(0);
      }

      System.out.println("Using '"+Logger.getLoggingType()+"' logging");
      Logger test = Logger.getLogger("test");

      LogLevel[] levels =
      {
         LogLevel.ALL,
         LogLevel.DEBUG,
         LogLevel.TRACE,
         LogLevel.INFO,
         LogLevel.WARNING,
         LogLevel.ERROR,
         LogLevel.OFF
      };

      for (int i=0; i

The output with the default Logger is:

Using 'default' logging

Testing for ALL
ERROR    - CMW Logger test, log level: ALL
WARNING  - CMW Logger test, log level: ALL
INFO     - CMW Logger test, log level: ALL
TRACE    - CMW Logger test, log level: ALL
DEBUG    - CMW Logger test, log level: ALL

Testing for DEBUG
ERROR    - CMW Logger test, log level: DEBUG
WARNING  - CMW Logger test, log level: DEBUG
INFO     - CMW Logger test, log level: DEBUG
TRACE    - CMW Logger test, log level: DEBUG
DEBUG    - CMW Logger test, log level: DEBUG

Testing for TRACE
ERROR    - CMW Logger test, log level: TRACE
WARNING  - CMW Logger test, log level: TRACE
INFO     - CMW Logger test, log level: TRACE
TRACE    - CMW Logger test, log level: TRACE

Testing for INFO
ERROR    - CMW Logger test, log level: INFO
WARNING  - CMW Logger test, log level: INFO
INFO     - CMW Logger test, log level: INFO

Testing for WARNING
ERROR    - CMW Logger test, log level: WARNING
WARNING  - CMW Logger test, log level: WARNING

Testing for ERROR
ERROR    - CMW Logger test, log level: ERROR

Testing for OFF

See Also:

"log4j"