Libra in Indigo

Eclipse Libra: WTP and PDE Working Together


Kaloyan Raev looks at integrating two separate toolsets.

Enterprise Java vendors have relied on the Java EE technology for many years. The Java EE specification provides a rich set of techniques for building large modular applications. Dozens of middleware vendors implement the specification in their application servers. This gives application providers the freedom to run their enterprise Java applications on the platform of their choice. The ability to build portable applications laid the foundation of the huge Java community that we know today.

Over the years, the requirements of the modularity aspect of enterprise applications has increased significantly. Application vendors wanted better control over modules’ lifecycle and dependencies. The Java EE specification binds dependency resolution to deploy time and does not define how modular applications can change during runtime. Several vendors tried responding to the new requirements with their own proprietary solutions, but the price for using them was the loss of portability. There was a clear demand for a standardized approach.

The solution has been found in OSGi – a specification as old as Java EE. The OSGi technology has been used for years for building modular embedded Java applications. OSGi was the solution that Java EE vendors were looking for. The challenge was how to bring Java EE and OSGi together. As a first step, Java middleware vendors tried using OSGi in application servers. Today, most Java applications servers use OSGi. It was only natural to try bringing the same experience to the application programming model. The OSGi Expert Group released the OSGi Enterprise 4.2 specification in March 2010, which defines how enterprise Java applications can be developed, deployed and run in an OSGi framework.

The Eclipse Libra project

The change in the application programming model also requires the development tools to meet the new requirements.

The Eclipse technology is perhaps the most famous platform for building an IDE. It provides the best tooling for Java application development and has tools for many other programming languages and frameworks. Two of the most successful projects in Eclipse are the Web Tools Platform (WTP) – for developing Web and Java EE applications, and the Plug-in Development Environment (PDE) – for developing OSGi bundles and Eclipse Plug-ins (a special type of OSGi bundles for the Eclipse platform).

Can we use these two Eclipse projects: WTP and PDE, for developing OSGi Enterprise applications? These are two different tool sets built independently for two different purposes. Can we integrate them, so that they can work together? These questions excited several vendors like SAP, EclipseSource, Eteration, IBM, VMWare and RedHat, who at the end of 2010 came together with a new proposal – the Eclipse Libra project.

On June 22, 2011 Eclipse Libra released version 0.1 together with the Indigo Simultaneous Release. Being part of the Eclipse release train guarantees that Libra works successfully with the rest of the Eclipse tooling. This first incubating version of Libra introduces the first basic features: OSGi Bundle Facet and WAR Products.

The OSGi Bundle facet is the glue between WTP and PDE. It’s based on the Faceted Project Framework that facilitates treating projects as though they’re composed of units of capabilities (called facets) that can be easily added or removed. Facets are widely used for WTP projects. For example, a Dynamic Web project is typically composed of two facets: a Java facet that gives the Java nature to the project and the Java classpath, and the Web facet that adds the web.xml descriptor and customizes the project’s structure to represent a WAR file. Adding more facet to the Dynamic Web project can bring additional capabilities, like the JSF facet that adds the JSF libraries to the classpath and generates the faces-config.xml descriptor. In a similar fashion, the OSGi Bundle facet adds the Plug-in nature to a project, so PDE recognizes it as an OSGi bundle. This way, adding the OSGi Bundle facet to a Dynamic Web project makes it effectively a Web Application Bundle – it is still a Web project from the WTP point of view, but it is also an OSGi bundle from the PDE point of view. Both WTP and PDE tools can be used when working with Web Application Bundle projects. Using the same approach, adding the OSGi Bundle facet to a JPA project turns it to a Persistent Bundle.

The other feature of version 0.1, WAR Products, addresses a different need – it enables Server-Side Equinox applications to be easily exported in a WAR file. Server-Side Equinox is a technology for building Web applications for the Equinox OSGi framework. It is not the standard way of building OSGi Enterprise applications, but it has its field of use – like for building RAP applications. The WAR Products are a light-weight and customized variant of the Eclipse Products used in PDE. It enables developers to configure how to export their applications to WAR files and execute the actual export process as well.




If you want to give Libra a try then the first step is to install it in your Eclipse IDE. As part of the Eclipse Simultaneous Release, the Libra plug-ins are available on the Indigo Discovery Site, which makes the installation process quite easy. If you don’t have an Eclipse IDE installed yet, then it is recommended using the Eclipse IDE for Java EE Developers package that is available for free download on the Eclipse Foundation website.

With your Eclipse IDE started, go to the main menu and choose Help > Install New Software… This will call the install manager. Then select the Indigo repository and, after it is resolved, browse the Web, XML, Java EE and OSGi Enterprise Development category. Select the OSGi Bundle Facet and the WAR Products features and click the Next button. Then follow the instructions of the install manager to complete the installation.

Web Application Bundles

A simple task for getting started with the Libra tools is creating and running a Web Application Bundle. To create a new Web Application Bundle project, switch to the Java EE perspective and call the New > Dynamic Web Project wizard. If you are familiar with WTP this will bring up the wizard for creating new Web projects. Now, you should create your Web project like before with one exception – adding the OSGi Bundle facet. You can do this by clicking the Modify… button in the Configuration group, or by simply selecting OSGi Web Application Bundle from the drop-down list.

As we mentioned before, the OSGi Bundle facet adds the Plug-in nature to your Dynamic Web project. Plug-ins and OSGi bundles are interchangeable terms in the PDE tooling.



It is possible to finish the wizard directly from the first wizard page, but if you advance to the following pages, then you can customize the metadata of the generated OSGi bundle. The OSGi Bundle facet itself contributes an additional wizard page to the wizard, where you can specify some generic metadata like Bundle Id, Bundle Name, etc. But the facet also integrates with the configuration of other facets, e.g. it reads the Context Root property that can be specified on the Web facet’s wizard page and sets its value to the Web-ContextRoot header in the MANIFEST.MF of the generated Web Application Bundle project.

When finished, the wizard generates a project that looks quite similar to a regular Dynamic Web project, but it has also some additional metadata – the Plug-in nature and the META-INF/MANIFEST.MF descriptor. The bundle root is set to the WebContent folder.

You will probably notice that the Web Application Bundle project has some compilation error markers. This is because there is no appropriate target platform activated in the workspace. The PDE target platform consists of all the bundles that define the build and the runtime environment of your target OSGi framework. If you use Libra for developing on a vendor’s OSGi middleware, then you would most probably have the target platform already defined. In the contrary case, you need to define it yourself. There are comprehensive guidelines on the wiki page of the Eclipse Gemini Web project on how to setup the Gemini web container as a target platform. On the same wiki page you can also follow the instructions on how to setup the launch configuration that will execute the OSGi framework in an appropriate way.

Before launching your Web Application Bundle you will most probably want to add some web content. You can use all familiar WTP tools to do this – remember, you project is still a valid Dynamic Web project. When ready you can run the OSGi launch configuration you have defined in the previous step. Once the OSGi framework starts you can request you application in the browser using URL like


All the steps described in this section can be followed in a YouTube video accessible from the Libra project page.

Persistent Bundles

Creating OSGi Persistent Bundles is a task as simple as creating Web Application Bundles. It is a completely analogical routine where the OSGi Bundle facet plays the same role. Again, you use familiar WTP wizard – New > JPA Project, where you need to select the OSGi Bundle facet in the project’s configuration.

The result is a valid WTP JPA project, but with the Plug-in nature added. There is also a META-INF/MANIFEST.MF descriptor that contains the bundle metadata, including the Meta-Persistence header specific to Persistent Bundles.

As you may have noticed, OSGi Bundle facet is quite powerful and can be added to different types of projects, and its behavior can be adjusted to the context. You can add all three facets – Web, JPA and OSGi Bundle into a single project and the result would be as expected – a Web project that is both a Web Application Bundle and a Persistent Bundle. This is completely valid according to the OSGi Enterprise specification, but may not be supported by all OSGi platforms. You can even add the OSGi Bundle facet to a plain Java project, which will convert it to a plain core OSGi Bundle.

Launching the Persistent Bundle requires an appropriate target platform and launch configuration. This can be set up in a similar way to the ones for the Web Application Bundle. The Gemini JPA project provides an OSGi JPA container that can be configured to work together with the web container from the Gemini Web project.



What’s next?

You have seen an overview of the first basic features that Libra introduces with the Eclipse Indigo release. So, what to expect next? As being part of the Eclipse Simultaneous Release, the Libra project will have two maintenance releases with Indigo SR1 (end of September 2011) and Indigo SR2 (end of February 2012). So, if you find any bugs, please let us know and report them in Eclipse Bugzilla. More interesting features are coming with the next Eclipse Simultaneous Release – Juno, that is scheduled for the end of June 2012. We have significant contributions from Eteration and IBM:

Integrated support for different open source OSGi frameworks like Apache Felix, Eclipse Equinox and Knopflerfish. This contribution provides server adapters, and UI components such as editors for server adapters, views to manage target platforms and launch configurations.

The generic parts from the OSGi tooling for Apache Aries – a full set of wizards to support working with OSGi bundles and wizards for working with Blueprint files.



Both contributions have already passed the IP review successfully and are in the process of being integrated in the master branch. VMWare also plans to move some generic parts of the Virgo tooling that they have recently contributed to Eclipse, to the Libra project. So, watch closely for the Juno milestones – coming soon.




You have seen how the Eclipse Libra project integrates two independent toolsets – WTP and PDE, so they can be used for developing OSGi Enterprise applications. Libra assumes that users have more experience with the WTP tooling and tries to hide the complexity of PDE behind familiar WTP concepts. This makes the experience of developing OSGi Enterprise applications similar to the Java EE application development. The first basic features of the Libra project have just been delivered with the Indigo Simultaneous Release. This is just the beginning and there are much more contributions to come in the next year, with the Juno release.

Kaloyan is the project lead of the Eclipse Libra project. He is one of the pioneers at SAP that turned the company into a dedicated player in the Open Source world. His first involvement with the Eclipse community dates back to 2006. A year later he became a committer in the Eclipse WTP project

Inline Feedbacks
View all comments