Felix integration inside Eclipse

This tutorial describes how running Felix inside the Eclipse IDE. This tutorial is organized as follow :

1. Requirements
2. Downloading Felix
3. Felix Compilation
4. Eclipse Projects creation
5. Eclipse configuration
6. Project imports in Eclipse
7. Launching Felix
8. Other information

Feel free to send me an e-mail if you have some feedbacks on this tutorial to clement.escoffier@gmail.com.

Requirements

To integrate Felix inside Eclipse you need to install first :

• Eclipse
• Maven
• Subversion

This page explains briefly how to install these softwares.

Eclipse Installation

To install Eclipse, follow instructions given here. The tutorial works with Eclipse 3.1 and 3.2.

Maven Installation

Mavenis a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. To install Maven, follow instructions given here.

Download a version superior or equal than 2.0.4. Felix compilation fails with anterior version.  You can download Maven here.

TIPS :   Maven use a local repository to store Jar files. This repository could grow up quickly. By default, this repository is in the ~/.m2/repository directory. You can create a new configuration in <USER_HOME>/.m2/settings.xml containing :

TIPS :   if you run this behind the proxy, update/create ~/.m2/settings.xml , see detail.
TIPS :   if you run under windows, config the PATH variable to be able to run "mvn".

Subversion Installation

The goal of the Subversion project is to build a version control system that is a compelling replacement for CVS in the open source community. The software is released under an Apache/BSD-styleopen source license. Felix sources are stores on an Subversion server. To get Felix, you need to download Felix sources on this server. Subversion is available here.

Important : Subversion binary files need to be in the PATH variable of your system.

Downloading Felix

 Felix sources are available  on : https://svn.apache.org/repos/asf/incubator/felix.

To download sources, follow the instructions :

•  Create a directory for Felix

•  In this directory launch the command : 

• When the checkout is finished, you should see :  [The revision number should be different]

 The Felix sources are in the trunk directory.

Felix Compilation 

 This section describe the Felix compilation. The Felix compilation process is based on Maven. Maven has an issue with a multi-module project (as Felix). Consequently, Felix trunk has 2 pom files.

• Go in the trunk directory
• Launch the commands :

  mvn -f pom-new-plugin-xml clean install
  mvn -f pom-old-plugin-xml clean install

  TIPS : Maven will download a lot of jar files. The network transfert can fail. So, if a Build error appears, re-try the command.

After each command, you should see the a table like :
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Apache Felix (parent) ................................. SUCCESS [2.884s]
[INFO] Maven OSGi Plugin ..................................... SUCCESS [2.874s]
[INFO] Servlet 2.1 API ....................................... SUCCESS [0.541s]
[INFO] OSGi R4 Core Bundle ................................... SUCCESS [0.210s]
[INFO] OSGi R4 Compendium Bundle ............................. SUCCESS [0.340s]
[INFO] Apache Felix Shell Service ............................ SUCCESS [0.161s]
[INFO] Apache Felix OSGi Framework Implementation ............ SUCCESS [0.380s]
[INFO] Apache Felix Shell Text Interface ..................... SUCCESS [0.130s]
[INFO] Apache Felix Shell GUI ................................ SUCCESS [0.121s]
[INFO] Apache Felix Bundle Repository Service ................ SUCCESS [0.240s]
[INFO] Apache Felix Shell GUI Plugin ......................... SUCCESS [0.170s]
[INFO] Apache Felix Daemon ................................... SUCCESS [0.110s]
[INFO] Apache Felix Dependency Manager ....................... SUCCESS [0.681s]
[INFO] Apache Felix Main ..................................... SUCCESS [1:38.392s]
[INFO] Apache Felix Examples: Service Event Listener ......... SUCCESS [0.721s]
[INFO] Apache Felix Examples: English Dictionary Service ..... SUCCESS [0.821s]
[INFO] Apache Felix Examples: French Dictionary Service ...... SUCCESS [2.153s]
[INFO] Apache Felix Examples: Dictionary Client .............. SUCCESS [0.601s]
[INFO] Apache Felix Examples: Dynamic Dictionary Client ...... SUCCESS [0.941s]
[INFO] Apache Felix Examples: Spell Check Service ............ SUCCESS [0.691s]
[INFO] Apache Felix Examples: Spell Check Client ............. SUCCESS [2.244s]
[INFO] Apache Felix Service Binder ........................... SUCCESS [1.402s]
[INFO] Apache Felix Examples: Spell Check w/ Service Binder .. SUCCESS [2.052s]
[INFO] Apache Felix WireAdmin ................................ SUCCESS [2.704s]
[INFO] Apache Felix UPnP Extra ............................... SUCCESS [0.922s]
[INFO] Apache Felix UPnP Base Driver ......................... SUCCESS [10.395s]
[INFO] Apache Felix UPnP Tester .............................. SUCCESS [1.682s]
[INFO] Apache Felix UPnP Sample TV ........................... SUCCESS [1.262s]
[INFO] Apache Felix UPnP Sample Clock ........................ SUCCESS [1.382s]
[INFO] Apache Felix UPnP Sample Binary-Light ................. SUCCESS [1.031s]
[INFO] Apache Felix HTTP Service ............................. SUCCESS [2:56.354s]
[INFO] Apache Felix Declarative Services ..................... SUCCESS [1.422s]
[INFO] Apache Felix EventAdmin ............................... SUCCESS [1.412s]
[INFO] Apache Felix EventAdmin Bridge UPnP ................... SUCCESS [0.761s]
[INFO] Apache Felix EventAdmin Bridge Configuration .......... SUCCESS [0.671s]
[INFO] Apache Felix EventAdmin Bridge UserAdmin .............. SUCCESS [1.172s]
[INFO] Apache Felix EventAdmin Bridge WireAdmin .............. SUCCESS [0.681s]
[INFO] Apache Felix iPOJO Metadata ........................... SUCCESS [0.641s]
[INFO] Apache Felix iPOJO .................................... SUCCESS [16.674s]
[INFO] Apache Felix iPOJO Maven Plugin ....................... SUCCESS [1:49.087s]
[INFO] Apache Felix iPOJO Arch Command ....................... SUCCESS [3.274s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7 minutes 32 seconds
[INFO] Finished at: Tue Jul 18 09:43:13 CEST 2006
[INFO] Final Memory: 13M/32M
[INFO] ------------------------------------------------------------------------

Eclipse Projects Creation

 The downloaded projects are not Eclipse projects. So you need to transform the projects in Eclipse project. In fact, Eclipse projects are configured with two files : .classpath (containing the classpath of the projects), and .project (descripbing the project). Of course, Maven can create these files from the pom.xml files.

To create Eclipse projects, launch in the trunk directory the following command : 

After each command, you should see a table like this :
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Apache Felix (parent) ................................. SUCCESS [0.871s]
[INFO] Maven OSGi Plugin ..................................... SUCCESS [3.445s]
[INFO] Servlet 2.1 API ....................................... SUCCESS [0.160s]
[INFO] OSGi R4 Core Bundle ................................... SUCCESS [0.051s]
[INFO] OSGi R4 Compendium Bundle ............................. SUCCESS [0.080s]
[INFO] Apache Felix Shell Service ............................ SUCCESS [0.050s]
[INFO] Apache Felix OSGi Framework Implementation ............ SUCCESS [0.060s]
[INFO] Apache Felix Shell Text Interface ..................... SUCCESS [0.060s]
[INFO] Apache Felix Shell GUI ................................ SUCCESS [0.050s]
[INFO] Apache Felix Bundle Repository Service ................ SUCCESS [0.070s]
[INFO] Apache Felix Shell GUI Plugin ......................... SUCCESS [0.060s]
[INFO] Apache Felix Daemon ................................... SUCCESS [0.100s]
[INFO] Apache Felix Dependency Manager ....................... SUCCESS [0.040s]
[INFO] Apache Felix Main ..................................... SUCCESS [0.281s]
[INFO] Apache Felix Examples: Service Event Listener ......... SUCCESS [0.050s]
[INFO] Apache Felix Examples: English Dictionary Service ..... SUCCESS [0.040s]
[INFO] Apache Felix Examples: French Dictionary Service ...... SUCCESS [0.050s]
[INFO] Apache Felix Examples: Dictionary Client .............. SUCCESS [0.050s]
[INFO] Apache Felix Examples: Dynamic Dictionary Client ...... SUCCESS [0.050s]
[INFO] Apache Felix Examples: Spell Check Service ............ SUCCESS [0.080s]
[INFO] Apache Felix Examples: Spell Check Client ............. SUCCESS [0.050s]
[INFO] Apache Felix Service Binder ........................... SUCCESS [0.050s]
[INFO] Apache Felix Examples: Spell Check w/ Service Binder .. SUCCESS [0.050s]
[INFO] Apache Felix WireAdmin ................................ SUCCESS [0.050s]
[INFO] Apache Felix UPnP Extra ............................... SUCCESS [0.161s]
[INFO] Apache Felix UPnP Base Driver ......................... SUCCESS [0.060s]
[INFO] Apache Felix UPnP Tester .............................. SUCCESS [0.040s]
[INFO] Apache Felix UPnP Sample TV ........................... SUCCESS [0.040s]
[INFO] Apache Felix UPnP Sample Clock ........................ SUCCESS [0.040s]
[INFO] Apache Felix UPnP Sample Binary-Light ................. SUCCESS [0.040s]
[INFO] Apache Felix HTTP Service ............................. SUCCESS [1.232s]
[INFO] Apache Felix Declarative Services ..................... SUCCESS [0.100s]
[INFO] Apache Felix EventAdmin ............................... SUCCESS [0.090s]
[INFO] Apache Felix EventAdmin Bridge UPnP ................... SUCCESS [0.090s]
[INFO] Apache Felix EventAdmin Bridge Configuration .......... SUCCESS [0.080s]
[INFO] Apache Felix EventAdmin Bridge UserAdmin .............. SUCCESS [0.040s]
[INFO] Apache Felix EventAdmin Bridge WireAdmin .............. SUCCESS [0.050s]
[INFO] Apache Felix iPOJO Metadata ........................... SUCCESS [0.041s]
[INFO] Apache Felix iPOJO .................................... SUCCESS [0.050s]
[INFO] Apache Felix iPOJO Maven Plugin ....................... SUCCESS [0.170s]
[INFO] Apache Felix iPOJO Arch Command ....................... SUCCESS [0.050s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 25 seconds
[INFO] Finished at: Tue Jul 18 09:46:57 CEST 2006
[INFO] Final Memory: 9M/16M
[INFO] ------------------------------------------------------------------------

Eclipse Configuration

Before importing Felix projects inside Eclipse, you need to configure an Eclipse variable. This variable points on the Maven repository. Indeed, the Eclipse project creation will create project dependencies and library dependencies. These librairies should be in the Maven repository. These dependencies are described in terms of the M2_REPO variable. So you need to configure this variable in Eclipse.

To achieve this, go in the : Window - Preference. Then look for the Java - Build Path - ClassPath Variables

 To create the variable, click on new. The variable name is M2_REPO. The variable point onto a folder. Select the maven repository folder (in the image : f:\maven_repo). 

Projects importation in Eclipse 

Now we can import Feluix projects in Eclipse. It is not useful to imports all Felix projects. To be able to run Felix inside Eclipse you need to import the following projects :

• org.apache.felix.main
• org.apache.felix.framework
• org.osgi.core
• org.apache.felix.shell
• org.apache.felix.shell.tui
• org.apache.felix.bundlerepository

To import project, click on File - Import - Existing Projects into Workspace :

 Then choose the projects :

• Select the trunk directory
• Select the wanted projects
  

 When you has finished to choose your projects, clic on Finish. When the workspaces has finish the import, you should see something like the next image in your project list :
  

Launching Felix

Now, we are able to configure Eclipse to launch Felix. To achive this go in the org.apache.felix.main project, and add the bin/felix.jar to the build path.
You should obtain something like the following structure:

In addition, you need to update the project build path by :

• Removing the link on the project org.apache.felix.framework
• Add a libraries point on the org.apachfe.felix.framework jar contained in the maven repository (M2_REPO/org/apache/felix/org.apache.felix.framework/0.9.0-incubator-SNAPSHOT/org.apache.felix.framework-0.9.0-incubator-SNAPSHOT.jar)

Let's go configure the "Run Configuration" :

• Go in the Run - Run ...
• Create a new Run configuration named Felix
• Configure the Run configuration as following

IMPORTANT : Choose the Main class contained in the felix.jar file.

Then, to launch Felix, just run this configuration. You should see in the console view :

Other Information

Now your can launch Felix inside Eclipse. You can debug your bundles in Eclipse (with the Eclipse debugger too), by launching your Felix in Debug Mode and by inserting breakpoint in your bundle code.

Moreover, it is possible to compile your bundle with Maven directly inside Eclipse, by configuring Maven as an External Tools. See the Maven guide for further information.

If you have any question on this tutorial, does not hesitate to send me an e-mail.