Inspecting the OSGi runtime - New ways for Eclipse projects

I often get asked how to find and solve issues in an OSGi runtime. Especially with regards to OSGi services. I then always answer that you have two options:

• Use the Gogo Shell scr:list - lists all DS components scr:info <id> - dump  detailed information for a selected DS component.
• Use the Apache Felix Webconsole

While the Gogo Shell is typically already part of an Eclipse application and can be activated by passing the -console parameter to the Program Arguments, the Webconsole is not available that simple. As Eclipse application projects are mostly still created using PDE, you have to use a target definition to configure the libraries to use for development and deployment. And in the past a target platform could only consume p2 repositories. That was especially important for the Tycho builds, as the also supported Directory locations in a target definition were not supported by Tycho builds. As the Felix Webconsole is not available via p2 update site, the only way to include it to an Eclipse application was to include the necessary jars locally somehow.

Luckily there were a lot of improvements in that area, and since Tycho 2.0 also other file-based locations are supported. And with Tycho 2.2 even Maven dependencies can be included directly. At the time writing this blog post 2.2 is not yet released. But the support for Maven dependencies in a Target Definition is available in m2e. With this enhancement the inclusion of the Felix Webconsole becomes a lot easier.

Install the m2e PDE Integration

First you need to install the m2e PDE Integration into the Eclipse IDE.

• Help - Install New Software…
• Use the m2e Update Site: https://download.eclipse.org/technology/m2e/releases/latest/
• Select m2e PDE Integration
• Finish the installation

After the installation it can be used in the PDE Target Editor.

Interlude: Target Editor

IMHO the PDE Target Editor is the second worst editor in PDE, right after the Component Definition Editor. The later luckily doesn’t need to be used anymore as PDE added support for the OSGi DS Component annotations. As a replacement for the Target Editor I used the Target Platform DSL. Unfortunately the DSL seems to be not actively implemented, and therefore the new Maven location support is missing. But I’ve found out that you can use the Generic Editor for the .target file and get similar features as with the DSL. For me the most important thing is to avoid the dialog for selecting artifacts from an update site, as this one really has its problems. So the nice thing on the DSL is the code completion for unit id and version, which is also working pretty well in the Generic Editor. Which could make the DSL obsolete.

So with the new Maven location and the Generic Editor, I now suggest to use the Target Editor for adding the Maven locations and switch to the Generic Editor for adding InstallableUnits from p2 repositories.

Add the Webconsole artifacts to the Target Platform

Open a Target Definition file with the Target Editor and add the following artifacts:

• commons-fileupload (1.4)
• commons-io (2.4)
• org.apache.felix.http.jetty (4.1.4)
• org.apache.felix.inventory (1.0.6)
• org.apache.felix.http.servlet-api (1.1.2)
• org.apache.felix.webconsole.plugins.ds (2.1.0)
• org.apache.felix.webconsole.plugins.event (1.1.8)
• org.apache.felix.webconsole (4.6.0)

Note:

• If you set the Dependencies scope to compile you get the transitive dependencies added too.
• Unfortunately the dependencies of org.apache.felix.webconsole are not configured well in the pom.xml.
  • You will transitively get commons-fileupload in version 1.3.3, which does not satisfy the Import-Package statement in org.apache.felix.webconsole.
  • You will transitively get commons.io in version 2.6, which does not satisfy the Import-Package statement in org.apache.felix.webconsole.
  • org.apache.felix.inventory is missing.
• I am using the Felix Http Jetty bundle as it is easier to configure than adding all the necessary Jetty bundles separately. But of course you can also use the Eclipse Jetty bundles directly from a p2 Update Site.
  • This unfortunately brings another dependency issue. The Felix Jetty bundle defines the Require-Capability header osgi.contract=JavaServlet. While the javax.servlet-api bundle that is transitively included by Maven would satisfy the technical requirements (Import Package), it is missing the capability header. To satisfy the capability you need to use org.apache.felix.http.servlet-api from Maven Central. Alternatively you can directly use the Eclipse Jetty bundles from an Eclipse Update Site and the provided javax.servlet bundle provided by Eclipse, as the Eclipse Jetty bundles to not specify the Require-Capability header.
• If you do not find the transitive included Maven dependencies as bundles for example when creating a product or feature definition, try to reload the target definition again.

To add the Maven locations you need to:

• Click Add… in the Target Editor
• Select Maven
• Provide the necessary information to select the artifact from Maven Central

The m2e PDE Integration has a nice feature to insert the values. If you have the Maven dependency XML structure in the clipboard, the values in the dialog are inserted automatically. To make it easier for adapters, here are the dependencies. Note that every dependency needs to be added separately.

<dependency>
    <groupId>commons-fileupload</groupId>
    <artifactId>commons-fileupload</artifactId>
    <version>1.4</version>
</dependency>

<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.4</version>
</dependency>

<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.inventory</artifactId>
    <version>1.0.6</version>
</dependency>

<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.http.jetty</artifactId>
    <version>4.1.4</version>
</dependency>

<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.http.servlet-api</artifactId>
    <version>1.1.2</version>
</dependency>

<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.webconsole.plugins.ds</artifactId>
    <version>2.1.0</version>
</dependency>

<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.webconsole.plugins.event</artifactId>
    <version>1.1.8</version>
</dependency>

<dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.webconsole</artifactId>
    <version>4.6.0</version>
    <scope>provided</scope>
</dependency>

Configure the product

If you have a feature based product you can create a new feature that includes the necessary bundles. This feature should include the following bundles:

• org.apache.felix.http.servlet-api
• org.apache.commons.commons-fileupload
• org.apache.commons.io (2.4.0)
• org.apache.felix.http.jetty
• org.apache.felix.inventory
• org.apache.felix.webconsole
• org.apache.felix.webconsole.plugins.ds
• org.apache.felix.webconsole.plugins.event

If you have a product based on bundles, ensure that these bundles are part of the Contents. Note that org.apache.commons.io needs to be included in version 2.4.0 to satisfy the dependencies of org.apache.felix.webconsole.

As Equinox has the policy to NOT activate all bundles on startup, you need to configure that the necessary bundles are started automatically:

• Open the .product file
• Switch to the Configuration tab
• In the Start Levels section click Add… and add the following bundles
  • org.apache.felix.scr
  • org.apache.felix.http.jetty
  • org.apache.felix.webconsole
  • org.apache.felix.webconsole.plugins.ds
  • org.apache.felix.webconsole.plugins.event
• Set Auto-Start for all bundles to true

Now you can launch the Eclipse application from the Overview tab via Launch an Eclipse application. The webconsole will be available via http://localhost:8080/system/console/ If you are asked for a login you can use the default admin/admin.

In the main bar of the Webconsole UI you can expand OSGi and find detailed informations on Bundles, Configuration, Events, Components, Log Service and Services. In these sub-sections you can find detailed information on the corresponding topics inside the current OSGi runtime. This way you can inspect and fix possible issues in a much more comfortable way.

Conclusion

Inspecting an OSGi runtime is much more comfortable using the Apache Felix Webconsole. With the new m2e PDE Integration finally Maven artifacts can be added as part of the target platform. Using it including the the Apache Felix Webconsole is much easier than it was before. And I am sure there are a lot more use cases that makes the live of Eclipse developers easier with that new feature. Thanks to Christoph Läubrich who added that feature lately.

Further information on the m2e PDE Integration can be found here:

• USING MAVEN ARTIFACTS IN PDE / RCP AND TYCHO BUILDS
• How to create Eclipse plug-ins from Java libraries (JAR files)