3.2. Export Versioning

Overview

OSGi allows you to associate a single version with an exported package. The version that you choose for your package (or packages) should conform to the conventions of semantic versioning, as defined in the section called “Semantic versioning rules”.

Export version at bundle granularity

The simplest approach to export versioning is where you use the bundle version as the export version and you assign the same export version to all exported packages in the bundle.
Using the Maven bundle plug-in, you can implement this versioning policy using instructions like the following: 
<instructions>
  <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
  <Import-Package>*</Import-Package>
  <Export-Package>
    !${project.groupId}*.impl.*,
    !${project.groupId}*.internal.*,
 ${project.groupId}.my.export.pkg*;version=${project.version}
  </Export-Package>
</instructions>
Where the ${project.version} macro returns the the contents of the project/version element in the POM file (the version of the current Maven artifact).

Export versions at package granularity

Strictly speaking, importing and exporting works at the granularity level of packages, not of bundles. In principle, therefore, it is possible to assign versions at the level of individual packages, so that one bundle contains multiple packages with different versions. There are some scenarios where it can be useful to assign versions at package granularity.
For example, consider a bundle that contains both an API package and a package that implements the API (see Section 2.7, “API/Provider Build-Time Combination”). In this case, it makes more sense to use separate versions for the API package and the implementation package.
Using the Maven bundle plug-in, you can specify the version of an individual Java package by creating or modifying the standard Java packageinfo file in the corresponding package directory. For example, if you want to assign version 1.2.1 to the org.fusesource.example.time package, create a file called packageinfo (no suffix) in the src/main/java/org/fusesource/example/time directory and add the following line: 
version 1.2.1
Alternatively, since Java 5 it is also possible to specify version information using annotations in a package-info.java file, for example: 
@Version("1.2.1")
package org.fusesource.example.time;