Home

SLF4J Plus Documentation

Using the Logger

The Advanced Logger (ALogger) is an extension of the normal SLF4J logger interface and thus can be used similar to a SLF4J logger. Prerequisite is that you use SLF4J with Logback as logging backend.

Create an ALogger instance through the ALoggerFactory:

import de.fhg.igd.slf4jplus.ALogger;
import de.fhg.igd.slf4jplus.ALoggerFactory;

class Example {

  private static final ALogger _log = ALoggerFactory.getLogger(Example.class);

...

User messages

On an ALogger you can emit special log messages requesting the user's attention. For instances you can include the de.fhg.igd.slf4jplus.ui.userstatus bundle in an Eclipse RCP application for the user to be informed through a dialog that pops up or a notification in the application's status bar. As such you should think very well about where you use such messages.

_log.userInfo("Info message the user might be interested in");
_log.userWarn("Warning that's important for the user", exception);

Log transactions

To keep track of a big amount of log messages, it is possible to combine them to groups. A log transaction combines log messages that occur between the beginning and end of the transaction in the relevant thread or a child thread. But make sure to end a log transaction that you started.

ATransaction logTrans = _log.begin("Transaction name");
try {
  ... // do something where log messages might occur
} finally {
  logTrans.end();
}

You can also use log transactions inside another log transaction - this will result in nested groups of log messages.

Within log transactions, there is also the possibility to explicitly combine certain messages to a group. For this a log group is used. All log messages in the same transaction that are passed with a group with the same name to a logger are combined to a group of messages in the transaction. This can for instance be used to combine messages that occur very often and clutter up the log.

private static final AGroup LOG_EXAMPLE = AGroupFactory.getGroup("Example log messages");

...
for (int i = 0; i < 100; i++) {
  _log.warn(LOG_EXAMPLE, "Example message " + i); // log message that will be grouped (if executed inside a transaction)
}
_log.info("Finished"); // log message that will not be grouped

Eclipse RCP integration

To make use of the features ALogger offers in an Eclipse RCP application it can be integrated with the Eclipse Error Log view and the status bar.

Error Log view

To enable the logging to the Eclipse Error log view, you need to include the following bundles in the configuration of your application:

• de.fhg.igd.slf4jplus (the SLF4J Plus logging API)
• de.fhg.igd.slf4jplus.logback (publishes a logging service as OSGi service)
• de.fhg.igd.slf4jplus.logback.appender (implements a Logback appender to publish messages to the services, this is a fragment to Logback)
• de.fhg.igd.slf4jplus.logback.observer (Base classes for log message observers to be registered on the logging service)
• de.fhg.igd.slf4jplus.ui.errorlog with autoStart = true (Log observer that forwards log groups and messages to the Error Log view)
• org.eclipse.ui.views.log (the Eclipse Error Log View)

In addition, you need a Logback configuration that uses the de.fhg.igd.slf4jplus.logback.appender.ServiceAppender, which publishes log events to the OSGi service. For the actual configuration of Logback you will need a fragment to the Logback Classic bundle that includes a logback.xml file or something similar.

<configuration>
  <appender name="SERVICE" class="de.fhg.igd.slf4jplus.logback.appender.ServiceAppender">
  </appender>
  ...
</configuration>

User status

To display the user messages, there is an element in the status bar. When you click on it, the last user messages are displayed. The icon blinks when there are new warnings or errors - or a dialog appears, depending on the configuration. Messages with the same text or belonging to a log group are grouped together.

To include this in you application, in addition, the bundle de.cs3d.ui.util.logging.userstatus is needed.

Other appenders

When using ALogger with other Logback appenders than the service appender, that don't support the transaction messages, e.g. the Console appender, you might want to hide those messages. For this, you can use the FlattenFilter:

<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <filter class="de.fhg.igd.slf4jplus.logback.appender.FlattenFilter" />
    ...
  </appender>
  ...
</configuration>

Extend or proxy the logger

When extending ALogger or using the logger in a utility class you will want to hide the call from your subclass or utility class from the stacktrace. For this purpose there is a constructor that takes a fully qualified class name (FQCN) and a factory method the takes a class - there you should supply your class.

private static final ALogger log = ALoggerFactory.getMaskingLogger(MyLogger.class, null);

Building from source

The easiest way to build is using Maven 3 - just type mvn install in the repository root to build all bundles, source bundles, features and the update site.

Alternatively you can also directly import the projects in Eclipse using the Import Existing projects into workspace option. You can use them either with your custom target platform, or set the one provided in the platform.target file in the platform proiject.