SK.gnome.dwarf.log
Class GenericLogger

java.lang.Object
  extended bySK.gnome.dwarf.GenericService
      extended bySK.gnome.dwarf.thread.ThreadService
          extended bySK.gnome.dwarf.log.GenericLogger
All Implemented Interfaces:
Logger, java.lang.Runnable, Service
Direct Known Subclasses:
JDBCLogger, NullLogger, StreamLogger, SyslogLogger

public abstract class GenericLogger
extends ThreadService
implements Logger

The abstract logging service.

This is a service which implements the Logger interface, therefore it is intended to perform the real logging, i.e. writting the log events to a physical store.

Implementations must override the abstract write(long, String, LogLevel, String, Throwable) method. Access to this method is synchronized internally.

In addition to a common logging operation this abstract class provides two more special features:

The first one is called marking and means that if the logger is not used for a specified period of time, it will write a special mark to the log to indicate that the logger (and thus probably the whole application) is still alive. The interval of the inactivity time can be specified via the setMarkInterval(int) method.

The second feature prevents the logs to be clogged by the repeated identical messages. When such a message occurs more than once in a specified period of time, the logger will not write all the message occurencies, but it will write just a single message together with the number of its subsequent occurencies. The interval of the repeated message flushing can be specified by the setRepeatedInterval(int) method.


Field Summary
protected  java.util.Set facilities
          Set of accepted logging facilities.
protected  java.util.Set levels
          Set of accepted logging levels.
protected  java.lang.Object lock
          The locking object.
static java.lang.String LOG_FACILITY_ALL
          This string constant identifies loggers which should log all events regardless of the logging facility identifiers associated with them.
 
Fields inherited from class SK.gnome.dwarf.thread.ThreadService
daemon, thread
 
Fields inherited from class SK.gnome.dwarf.GenericService
initParameters, parent
 
Fields inherited from interface SK.gnome.dwarf.Service
INITIALIZED, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_TRACE, LOG_WARN, LOG_XFER, SHUTDOWN, STARTED, STOPPED
 
Constructor Summary
GenericLogger(java.lang.String name)
          Creates a new GenericLogger.
 
Method Summary
protected  boolean enableThread()
          Enables the creation of a new service thread.
protected  long getLastAccessed()
          Returns the time of the last write operation.
 void log(java.lang.String facility, LogLevel level, java.lang.String message)
          Logs the message with the given logging facility and level.
 void log(java.lang.String facility, LogLevel level, java.lang.String message, java.lang.Throwable error)
          Logs the message and the error with the given logging facility and level.
protected  void loop()
          Runs the service.
 void setFacilities(java.lang.String facilities)
          Sets the logging facility.
 void setLevels(java.lang.String levels)
          Sets the logging levels.
 void setMarkInterval(int interval)
          Sets the marking interval.
 void setRepeatedInterval(int interval)
          Sets the interval of flushing the repeated messages.
 void shutdown()
          Shuts down the service.
 void start()
          Starts the service.
protected  boolean wouldLog(java.lang.String facility, LogLevel level)
          Decides whether the logger would log a message with the given loggging level and facility.
protected abstract  void write(long time, java.lang.String facility, LogLevel level, java.lang.String message, java.lang.Throwable error)
          The abstract method for writing the log message to a physical store.
 
Methods inherited from class SK.gnome.dwarf.thread.ThreadService
finish, run, setDaemon, stop
 
Methods inherited from class SK.gnome.dwarf.GenericService
getAuthenticator, getAuthFacility, getFullName, getInitParameter, getInitParameterNames, getLogFacility, getLogger, getName, getParameters, getPrincipal, getShutdownTimeout, getState, init, log, log, login, logout, setAuthFacility, setInitParameters, setLogFacility, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LOG_FACILITY_ALL

public static final java.lang.String LOG_FACILITY_ALL
This string constant identifies loggers which should log all events regardless of the logging facility identifiers associated with them. It contains the string "all", which can be passed in to the setFacilities(String) method.

See Also:
Constant Field Values

levels

protected java.util.Set levels
Set of accepted logging levels.

A set of logging levels can be assigned to each logger so it can decide whether or not to log a message with the particular logging level. Set elements are of type LogLevel.

Default value: Service.LOG_INFO and higher

See Also:
setLevels(String)

facilities

protected java.util.Set facilities
Set of accepted logging facilities.

A set of logging facilities can be assigned to each logger so it can decide whether or not to log a message with the particular logging facility. Elements are of type java.lang.String.

Default value: LOG_FACILITY_ALL

See Also:
setFacilities(String)

lock

protected final java.lang.Object lock
The locking object.

An outside class to the write(long, String, LogLevel, String, Throwable) method should be synchronized on this object.

Constructor Detail

GenericLogger

public GenericLogger(java.lang.String name)
Creates a new GenericLogger.

The initial logging levels are set to Service.LOG_INFO and higher, and the logging facilities are set to LOG_FACILITY_ALL. The interval of repeated message flushing is set to LogConstants.LOG_MESSAGE_REPEATING_INTERVAL.

Method Detail

setMarkInterval

public void setMarkInterval(int interval)
Sets the marking interval.

If the logger is not used for a specified period of time, it will write a special mark to the log to indicate that the service (and thus probably the whole application) is still alive.

The marking feature will be disabled if the interval is set to zero.

Default value: 0

Parameters:
interval - the marking interval in minutes
See Also:
loop()

setRepeatedInterval

public void setRepeatedInterval(int interval)
Sets the interval of flushing the repeated messages.

If set to zero, all identical message occurrencies will be written to the log.

Parameters:
interval - the interval in seconds

setLevels

public void setLevels(java.lang.String levels)
Sets the logging levels.

Sets the logging levels which will be accepted by the logger. Use a comma-separated list of their string representations as the method argument. It is also possible to use an optional wildcard character, as explained below.

For example, if a string "info, warn" is provided as an argument, the logger will log the messages with the Service.LOG_INFO and Service.LOG_WARN levels only. A wildcard character may be used to setup the logger to accept a particular log level as well as any higher levels than it. For example, a "debug*" string would cause the logger to accept messages with the Service.LOG_DEBUG level and higher.
Either a list of the levels or a single level with the wildcard character appended may be used, not a mix of them.

The argument components correspond to the level description strings as defined by the LogLevel interface, e.g. the "error" string represents the Service.LOG_ERROR level, and so on. The strings are case insensitive.

Accepting of messages according to their logging levels and facilities can be customized by overloading the wouldLog(String, LogLevel) method.

Parameters:
levels - the comma-separated list of log levels

setFacilities

public void setFacilities(java.lang.String facilities)
Sets the logging facility.

Sets the logging facilities which will be accepted by the logger. Use a comma-separated list of logging facilities as the method argument.

For example, if the string "http, smtp" is used as an argument, the logger will accept a message with either the "http" or the "smtp" logging facility associated with it.

The LOG_FACILITY_ALL constant may be used to set up the logger to accept a message with an arbitrary logging facility associated with it.

Accepting of messages according to their logging levels and facilities can be customized by overloading the wouldLog(String, LogLevel) method.

Parameters:
facilities - the comma-separated list of facilities

getLastAccessed

protected long getLastAccessed()
Returns the time of the last write operation.

Returns:
the time of the last write operation

wouldLog

protected boolean wouldLog(java.lang.String facility,
                           LogLevel level)
Decides whether the logger would log a message with the given loggging level and facility.

A logger would log the message if at least one of the following facility-based rules is true, and the level-based rule is true as well:

This method can be overriden in order to implement a different behavior. It should be thread-safe to allow multiple logging requests at a time.

Parameters:
facility - the logging facility
level - the logging level
Returns:
true if the logger would log the message, false otherwise

write

protected abstract void write(long time,
                              java.lang.String facility,
                              LogLevel level,
                              java.lang.String message,
                              java.lang.Throwable error)
The abstract method for writing the log message to a physical store.

The actual logging is performed via this method. It must be overriden in order to implement a real logger. Access to this method must be always synchronized on the internal lock object.

Parameters:
time - the current time of the logged event
facility - the log facility
level - the log level
message - the message
error - the error (optional)
See Also:
log(String, LogLevel, String), log(String, LogLevel, String, Throwable)

enableThread

protected boolean enableThread()
Enables the creation of a new service thread.

It returns true if the marking feature is enabled.

Overrides:
enableThread in class ThreadService
Returns:
true if the thread is enabled

start

public void start()
           throws ServiceException
Description copied from class: ThreadService
Starts the service.

If the ThreadService.enableThread() method returns true, it creates and starts a new thread. The thread's name corresponds to the service name and the thread's Runnable target is the service itself since it implements the Runnable interface. The reference to the thread object is stored in the ThreadService.thread field.

It throws a IllegalStateException if the ThreadService.thread field is not null and its isAlive() method returns true.

Specified by:
start in interface Service
Overrides:
start in class ThreadService
Throws:
ServiceException

shutdown

public void shutdown()
Description copied from class: ThreadService
Shuts down the service.

It interrupts the ThreadService.thread via its interrupt() method and waits for it to finish by calling the ThreadService.finish() method.

Specified by:
shutdown in interface Service
Overrides:
shutdown in class ThreadService

log

public final void log(java.lang.String facility,
                      LogLevel level,
                      java.lang.String message)
Logs the message with the given logging facility and level.

First calls the wouldLog(String, LogLevel) method with the facility and the level argument and if the result is true, calls the write(long, String, LogLevel, String, Throwable) method to perform the actual logging.

Specified by:
log in interface Logger
Parameters:
facility - the logging facility
level - the logging level
message - the message

log

public final void log(java.lang.String facility,
                      LogLevel level,
                      java.lang.String message,
                      java.lang.Throwable error)
Logs the message and the error with the given logging facility and level.

First calls the wouldLog(String, LogLevel) method with the facility and the level argument and if the result is true, calls the write(long, String, LogLevel, String, Throwable) method to perform the actual logging.

Specified by:
log in interface Logger
Parameters:
facility - the logging facility
level - the logging level
message - the message
error - the error

loop

protected void loop()
Runs the service.

This method provides the marking feature.

Overrides:
loop in class ThreadService
See Also:
setMarkInterval(int)


Copyright (c) 1999-2005, Gnome Ltd. All rights reserved.