I didn’t mean it like this – Defining provisional API in Equinox

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.

About Lars Vogel

Lars Vogel is the founder and CEO of the vogella GmbH and works as Eclipse and Android consultant, trainer and book author. He is a regular speaker at international conferences, With more than one million visitors per month his website vogella.com is one of the central sources for Eclipse and Android programming information.
This entry was posted in Eclipse, OSGi and tagged , . Bookmark the permalink.

5 Responses to I didn’t mean it like this – Defining provisional API in Equinox

  1. Eike Stepper says:

    Hi Lars,

    I strongly recommend against accepting the warnings that result from using code that is declared as x-internal! It’s not “just” a development-time warning but can also be enforced at run-time. Compare OSGi (Equinox) and Strict Mode.

    Cheers
    /Eike

  2. Lars Vogel says:

    Hi Eike,

    I think p2 was a nice example, until recently they had no official API but exported their classes to get feedback on the usage and to fix the API. Of course the developer should in this case be aware that he will have some work to do once the API is released.

    But in general I agree, using internal API is evil. ;-)

    Cheers, Lars

  3. David Carver says:

    Personally, I dislike the x-internal extension point. The main reason is that it promotes the use of internal classes that never get promoted to being true API. It also promotes plugins diving into each others internals. If your plugin needs to access internals of another plugin to get something done, this is a true sign that you haven’t made something API that should be. Internals should be internal to the plugin they belong.

    I understand the need to make experimental API, but I prefer doing this through annotations or some other way in documentation than through the use of x-internal.

  4. Richard S. Hall says:

    API is API, get over it.

    If you want to provide some warning your APIs are volatile, just do:

    Export-Package: org.foo.prototype;
    thismaychange=”I accept responsibility”;
    mandatory:=”thismaychange”

    Done deal.

  5. Pingback: Friends of yours? Using x-friends in Equinox to loosen the API restrictions for some plugins » Eclipse Papercuts

Comments are closed.