Guidelines on importing internal packages

Kura semantic versioning

Kura versions its packages according to the semantic versioning rules for both internal and org.eclipse.kura.api bundle packages. Development of an application external to Kura is safe to import packages from the org.eclipse.kura.api bundle (the ones that are also referenced in Kura Javadocs). We do our best to not introduce backwards incompatible changes in org.eclipse.kura.api bundle in minor and patch Kura releases, while we can make breaking changes to other packages at any time.

When developing an external application, sometimes it is highly tempting to reuse code that resides in some of the utility packages in Kura. Those utility packages are usually marked as x-internal or declare allowed packages as x-friends in the MANIFEST. However, all packages that are not exported in org.eclipse.kura.api are to be considered internal at the moment, even if they don't have the x-internal directive, we will progressively annotate them with x-internal.

This means that internal packages are not guaranteed to maintain retro-compatibility with older versions. Even a minor version update might break the consumers since none of the implemented methods in an internal package is an API.

Kura internal code might implement some of the following directives, whereas for code that is not part of Kura these considerations become relevant and some guidelines are presented and discussed in section Use Kura's internal packages outside of Kura.

The x-internal directive

The x-internal directive is used to specify whether the package is an internal package. The Plug-in Development Environment will discourage other bundles from using an internal package. The default value if not specified is false. The directive has the following syntax:

x-internal ::= ( 'true' | 'false' )

Example:

Export-Package: org.eclipse.kura.foo.internal; x-internal:=true

The x-friends directive

The x-friends directive can be used to specify a list of bundles which are allowed access to the package. The Plug-in Development Environment will discourage other bundles from using the package. The directive has the following syntax:

x-friends ::= '"' ( target-bundle ) ( ',' target-bundle ) * '"'
target-bundle ::= a bundle symbolic name

Example:

Export-Package: org.eclipse.kura.foo.formyfriends; x-friends:="org.eclipse.kura.foo.friend1, org.eclipse.kura.foo.friend2"

The example specifies that only the bundles org.eclipse.kura.foo.friend1 and org.eclipse.kura.foo.friend2 should use the org.eclipse.kura.foo.formyfriends package.

The x-internal directive has priority over the x-friends one, meaning that if x-internal=true then The Plug-in Development Environment will discourage all bundles from using the package even if they are specified as a friend.

Use Kura's internal packages outside of Kura

To bind external code to a specific version of an internal Kura packages is best to download the specific jar and include it into the project. This approach has several benefits:

• The external code is independent on the Kura version: a Kura update might have a new version of the imported internal package that is no longer compatible with the code using it. Having the specific internal package version downloaded in the project resolves this issue allowing it to be used in the updated Kura.
• Reduced code duplication: a lot of external code will be a duplicate of some internal package, reusing the latter can reduce the complexity of the new code.

The disadvantages of this approach are:

• Difficult to implement extensions.
• Bugs due to the imported internal packages must be solved by the consumer.

The recommended way to include an utility jar is getting a released version from the Eclipse repo; for example using the maven dependency plugin.

References

• OSGi Bundle Manifest Headers
• Kura 5.2.1 Javadocs