A Quick Start with OSGi Logging: the Pax library

NOTE: This article is a replica of the work by Pierre Parrend and published on his website. This replica is made by his expressed consent and with the purpose of a backup in case the original is ever decommissioned.

The previous technical note on java loggingpresents the principles of code logging, as well as some of the most widespread logging libraries for java: Sun J2SE Logging API, Apache Log4J framework, Simple Log library, Jakarta Common Logging API, Simple Logging Facade for Java, X4juli. The configuration of the logging is done through a unique config file for instance log4j/log4j.properties.

In the context of an OSGi platform, each bundle (i.e. OSGi archives) have its own view on the file system, so using a centralized config file can not conduct to anything but dirty hacks. The solution is provided by the Pax logging facility, which bundelizes both the library code and the configuration file.

This technical note presents a Quick Start view on using the Pax logging library: what steps are required to let a proper logging be available on your OSGi platform ?

Following aspects will be shown:

• #Technical environment,
• ops4j:How to install required code,
• ops4j:How to set your own logging configuration for Log4j,
• Launch the logging example provided with the Pax library: Jcl, Avalon, Sl4j, Jdk logger,
• ops4j:How to use Pax with existing code under Maven
• ops4j:Links

Technical Environment

This Quick Start assumes that you are ready to install suitable code for installing OSGi and the Pax library.

We use the Felix OSGi implementation.

The Maven development environment is used for compiling both Felix and Pax.

All necessary logging libraries are provided in Pax. We provide some convenient extension.

Restriction: no other logging API should be available in the platform.

Installation

Installation

This section introduces how to install, configure and launch a OSGi platform with the Pax logging facility.
Of coure, you can just skip the items that are already available on your system.

• Install maven 2

  svn co https://svn.apache.org/repos/asf/incubator/felix/trunk/tools/maven2 cd ./maven mvn install

  If you want to learn Maven, you can do it is 5 minutes, or in 10 minutes
• Install felix

  svn co http://svn.apache.org/repos/asf/incubator/felix felix cd ./felix/trunk mvn install (include the script for launching felix in your path)

  If you want to start with felix, you can have a look here.
• Checkout the code for Pax

  mkdir ops4j cd ./ops4j svn co https://scm.ops4j.org/repos/ops4j/projects/base base svn co https://scm.ops4j.org/repos/ops4j/projects/pax pax

  If you are new to Pax, you will find an introduction here\
• Install Pax

  cd ./base mvn install cd ../pax mvn install

Configuration

• Configure the logging properties in Pax. In logging/service/src/main/resources/log4j.properties

  cd ./logging/ mvn clean install

Launch

• Launch the osgi platform, and suitable bundles. For felix;
  (assuming that felix is available in your path)

  start [file:///XX/felix/trunk/org.osgi.compendium/target/org.osgi.compendium-0.8.0-SNAPSHOT.jar] start [file:///XX/pax/logging/api/target/api-0.9.5-SNAPSHOT.jar] start [file:///XX/pax/logging/service/target/service-0.9.5-SNAPSHOT.jar] start [file:///XX/pax/logging/log4j/target/log4j-0.9.5-SNAPSHOT.jar]

  (with XX denoting the suitable path in your system)

You have just installed maven, felix, pax, and started the pax bundles that are required for performing logging with log4j in a OSGi platform.

Set your own logging configuration for Log4j

This section introduces how to configure, install and test the log4j facility. An example highlight the behavior of log4j with Pax.

Configure

• Have a look at the content of the logging/service/src/main/resources/log4j.properties configuration file.
• Two profiles are defined: demoLogger (logging level set to ERRORS and worse probblems), and develLogger (logging level set to DEBUG).
• You can change this configuration.
• Do not forget to reinstall (in Maven) and reload (in the OSGi platform) the serevice.jar bundle to taken your changes into account

Install

1. if your OSGi platform with logging bundles is available (section Installation)
   1. update the bundles you just compiled in your OSGi plaform
   2. update N
   3. with N the ID of the service.jar bundle
2. else
   1. follow the instruction of part 'Installation'.

Test

• Start the log4j client in your OSGi platform

  start file:///XX/logging/log4jclient/target/log4jclient-0.1.jar

• Observe what happens

2 loggers (demoLogger, and develLogger) are created, which each issue an error and a warning,
the configuration is set so that the demoLogger print logs that are at least as serious logging/log4jclient/target/log4jclient-0.1.jaras ERROR, and the develLogger prints logs that are at least as serious as DEBUG.

Example of Jcl, Avalon, Sl4j, Jdk logger

This section introduces how to launch the standard example provided with Pax, that uses simultaneously Jcl, Avalon, Sl4j and Jdk logger with a log4j backup.

Installation of the bundles

• install following bundles

OSGi Service, OSGi Util, Servlet
from OBR,
or manually from following URL: http://oscar-osgi.sourceforge.net/
or in the log4jlogging.doc/repository/ directory.

• install the logger you want to test (in the example, all are taken into account)

  start file:///XX/logging/avalon/target/avalon-0.9.5-SNAPSHOT.jar start file:///XX/logging/slf4j/target/slf4j-0.9.5-SNAPSHOT.jar start file:///XX/logging/jcl/target/jcl-0.9.5-SNAPSHOT.jar

• go the logging/example directory

  cd logging/example

• Specify the activator in the pom.xml file

  <osgi-BundleActivator>org.ops4j.pax.logging.example.Activator</osgi-BundleActivator>

• package the source

  mvn clean install

Test

• start the example bundle in your osgi platform

  start file://XX/logging/example/target/example-0.9.5-SNAPSHOT.jar

• Observes what is logged

To use PAX with existing code under Maven

This section introduces how to use the Pax facility in an existing Maven project.

Configuration

• Add following dependencies to the pom.xml file of your project

  <dependency> <groupId>org.ops4j.pax.logging</groupId> <artifactId>log4j </artifactId> <version>0.9.5-SNAPSHOT</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.ops4j.pax.logging</groupId> <artifactId>api</artifactId> <version>0.9.5-SNAPSHOT</version> <scope>provided</scope> </dependency>

Use

• you can retrieve the singleton Logger by calling

  Logger.getLogger("name");

  from all over the OSGi platform.
  Beware: no other version of the log4j library must be available on your platform.
  Otherwise, You should consider using a Logger service.

Links

Related tutorials

• Java logging

External resources

• OSGi Alliance
• Felix OSGi implementation
• Introduction to Felix
• A Useful OSGi Bundle repository
• Pax logging for the OSGi Platform\
• Maven Development Environment
• Introduction to Maven in 5 minutes
• Getting started with Maven