Eclipse Papercuts

As you know the OSGi Framework enforces strong modularity. This also applies to native library code, e.g. a Windows DLL.

To make your DLL available in the context of OSGi you have to use the Bundle-NativeCode section in MANIFEST.MF.

For example if your DLL is called “sapjco3.dll” and is in the main path of you bundle you can use.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Jco
Bundle-SymbolicName: com.sap.conn.jco
Bundle-Version: 1.0.0
Bundle-ClassPath: sapjco3.jar
Bundle-NativeCode: /sapjco3.dll; osname=win32; processor=x86
Export-Package: com.sap.conn.jco,

Many thanks to Matthias Heinrich for the tip.

In Defining provisional API in Equinox I discussed how to mark your API as internal / provisional. But what if your plugin has a close friend which should be allowed to use this API without restrictions? Even in the plugin world some plugins are sometimes closer to each other.

This can be achived by the x-friends directive. Which can be added via the some editor which added the x-internal flag.

This should result in the following MANIFEST.MF.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Provider
Bundle-SymbolicName: de.vogella.osgi.xinternal.provider
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Export-Package: de.vogella.osgi.xinternal.provider;x-friends:="de.vogella.osgi.xinternal.consumer"

By this setting the package de.vogella.osgi.xinternal.provider can be used by the plugin “de.vogella.osgi.xinternal.consumer” without restrictions but is mark as “x-internal” for all other plugins.

Choose your friends wisely.

OSGi is very strong in defining API contracts. In each bundle you can decide this which packages are exported and which can be used by other plugins.

But what if you want to make your classes usable to other but don’t want to to make it final API, so that you can change it later after the first consumer have tried using it. You want to export it, but you want to put a warning sign out there to tell everybody that this is not fixed API.

Meet the x-internal extension of OSGi in Equinox. This extension allows you to export you API but mark it as internal so that the consumer knows that he is using an API which may be changed later. To test this out create a new plugin project “de.vogella.osgi.xinternal.provider” using no template. Implement the following class.

package de.vogella.osgi.xinternal.provider;

public class Hello {
	public String getHello(){
		return "Hello";
	}
}

Switch to the MANIFEST.MF, select the tab Runtime. Export you package, select it and select under “Package Visibility” the flag “hidden from all plug-ins except”.

This should result in a MANIFEST.MF like this.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Provider
Bundle-SymbolicName: de.vogella.osgi.xinternal.provider
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Export-Package: de.vogella.osgi.xinternal.provider;x-internal:=true

To test you export create a new plugin project “de.vogella.osgi.xinternal.consumer”. Define in MANIFEST.MF a dependency to “de.vogella.osgi.xinternal.provider”. Define a class which uses the class “Hello.java”, e.g.

package de.vogella.osgi.xinternal.consumer;

import de.vogella.osgi.xinternal.provider.Hello;

public class Test {
	public static void main(String[] args) {
		Hello hello = new Hello();
		System.out.println(hello.getHello());
	}
}

Depending on your preference settings you receive either an info, or a warning or an error.b

The Eclipse platform uses this directive quite ofter for API which should not be considered as public API. You can also make your API consumer aware if the API is rock solid or if the consumer should be careful in using it.

The Eclipse plugin creation wizard allows to create OSGi bundles or Eclipse plugins.

The most notable difference is that the PDE plugin editor does not show the extension tab.

I recently wanted to use an plugin extension in a project which I initially created based on OSGi; therefore I wanted to enable the “Extension” and the “Extension Point” tab in the PDE editor.

To do this remove the line “pluginProject.extensions.false” from the file .settings/org.eclipse.pde.core.prefs. Re-open the “MANIFEST.MF” and the Extensions tab will show.

Many thanks to Neil Bartlett for sharing this tip via twitter.

In this episode of Eclipse Papercuts I explain how you get bundles for popolar Java libraries for your Eclipse plugin development.

I believe it has advantages to work with plugin projects instead of pure Java projects even if the plan is not to create Eclipse plugins / RCP applications.

The core strength of OSGi for this scenario is in my opinion the encapsalation and protection of your inner classes. With OSGi bundles you decide which packages of your project are exported and therefore visible to other projects (via the tab Runtime in the editor for the file plugin.xml).

This leaves only one problem: If you are using externally libraries you have to convert them into bundles / plugins.

I would be nicer to consume pre-packages bundles. As I created a bug iText should be OSGi and tweeted about it Chris Aniszczyk pointed me to Eclipse Orbit.

Eclipse Orbit provides lots of standard libraries already pre-packaged as bundles / plugins.

Lets see how you could get the iText version from Orbit. Check the Orbit FAQ to find out more.

You need to connect via cvs to the Eclipse cvs repository. CVS URL is :pserver:anonymous@dev.eclipse.org/cvsroot/tools

Navigate to “org.eclipse.orbit”. Select “com.lowagie.text” and check it out.

Orbit keeps the different version of the library as cvs branches. Select your project and select Replace With -> Another Branch or Version…

After selecting the branch and pressing ok the system will download the library and you can start using the library.

In addition to Orbit you can also use the Springsource bundle repository. On this website you can search for bundles and download then directly. You can then import them as plugin projects into your workspace.