HowTo: Logging in Eclipse 4 (e4) Applications

Introduction

In the following we are going to modify the Eclipse 4 sample application by adding logging. As logging backend we will use Pax Logging. We will take care of the configuration with a combination of Apache Felix File Install and Apache Felix Config Admin. In the end our sample application will support multiple logging APIs like Log4J, JCL or SLF4j (check Pax Logging for a full feature list) and can be simply configured via a log4j.properties file which can be modified during runtime and placed outside the bundle anywhere on the machine.

Prerequisites

• Eclipse 4.x with installed e4 Tools 

Note: If you need any help installing Eclipse or e4 Tools, I strongly recommend reading Lars Vogel's great Eclipse RCP tutorial.

Steps

Create RCP sample application

1. Create a new Eclipse 4 Application Project (File -> New -> Other).
   
2. Name the project.
   
3. Configure project properties (you can use the defaults here).
   
4. Choose the ‘Template option’ and finish.
   
5. Launch the application to check everything is fine.
   

Set up Target Definition

1. Create a new Target Definition file (File -> New -> Other).
   
• Add the running platform as default target.
  
2. Download additional libraries.
• Apache Felix Config Admin is an implementation of the Configuration Admin Service which is specified by the OSGi Compendium. In a nutshell the Configuration Admin Service allows retrieving and changing configurations. In this example Apache Felix Config Admin will read the LOG4J configuration for Pax Logging Service. Official documentation can be found here. 
• Apache Felix File Install watches a directory in the file system for files to be installed in the OSGi runtime. If any bundle is placed into this watched directory File Install installs and starts the bundle. If you update the bundle it will be updated, if you delete the bundle it will be stopped and uninstalled. It does the same for configuration files whose content will be pushed to Configuration Admin Service. In this example Apache Felix File Install will install and likewise update the LOG4J configuration file in our OSGi runtime (Equinox container). Official documentation can be found here. 
• Pax Logging API bundles all featured logging APIs. 
• Pax Logging Service implements the OSGi Log Service using Log4J as backend implementation.
3. Create a folder 'add_libs' in the project directory, copy the downloaded libraries into it and add the folder to the Target Definition.
   
• Choose directory as the source.
  
• Add the add_libs folder as location.
  
• Set the Target Definition as Target Platform.
  

Configure a Logger in the sample application

1. Add org.slf4j to the imported packages in MANIFEST.MF.
   
2. Initialize a Logger and define a log statement.
   

Configure Log4J

1. Create a folder 'etc' in the project directory with a file org.ops4j.pax.logging.cfg placed in it.
   
2. Configure log4j by adding content to the configuration file.

Run the application

1. Set up the Run Configuration.
   
2. Add Felix File Install properties as VM arguments.
   
3. Add Felix Config Admin and File Install to the run configuration and force their start.
   
4. Add Pax Logging API and Service to the run configuration and force their start.
   
5. Finally run the application expecting log output on the console.