OSGi bundles are simply sets of Java classes packaged into a JAR file, with a manifest file which describes the bundle to the OSGi framework. Any JAR archive containing a MANIFEST.MF file with required OSGi headers can be installed using the framework commands.This means it's very easy to create your own bundles.

Problems come when you need to use a third-party provided JAR file, let's say a library, as a bundle :

If the JAR developers is aware about OSGi, he added the necessary headers to the MANIFEST.MF file. Then you can go ahead and install this JAR into your OSGi framework.
If not, you will have to repackage the JAR file and provide new metadata in MANIFEST.MF file. This pages shows how to do this on the javax.transaction:jta:1.1 JAR library.

In fact, any JAR archive can be transformed into a valid OSGi bundle by using the original Bnd tool or the maven plugin based on this tool. So to create the bundled version of javax.transaction:jta:1.1 we simply create a new maven project with the following pom.xml file:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 
 <modelVersion>4.0.0</modelVersion> 
 <parent> 
 <artifactId>neo4j-osgi-howto</artifactId> 
 <groupId>org.escapek</groupId> 
 <version>0.0.1-SNAPSHOT</version> 
 </parent> 
 <groupId>org.escapek.neo4j-osgi-howto</groupId> 
 <artifactId>javax-transaction-api</artifactId> 
 <version>1.1</version> 
 <name>EscapeK - Bundles - Java transaction API</name> 
 <description>Bundled version of Java Transaction API</description> 
 <packaging>bundle</packaging> 
 
 <dependencies> 
 <dependency> 
 <groupId>javax.transaction</groupId> 
 <artifactId>jta</artifactId> 
 <version>${project.version}</version> 
 </dependency> 
 </dependencies> 
</project>

This project has no content. Is only declares a dependency to the original javax.transaction:jta:1.1 artifact.

The maven-bundle-plugin execution is setup in the parent pom as follow :

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 
 <modelVersion>4.0.0</modelVersion> 
 <groupId>org.escapek</groupId> 
 <artifactId>neo4j-osgi-howto</artifactId> 
 <version>0.0.1-SNAPSHOT</version> 
 <packaging>pom</packaging> 
 <name>Neo4j OSGi how-to</name> 
 <description>Resources needed to install Neo4j on OSGi</description> 
 <url>http://wiki.escapek.org/display/DEV/Neo4J+step-by-step+installation+%28with+HA+support%29+on+OSGi</url> 
 <modules> 
 <module>javax-transaction-api</module> 
 </modules> 
 
 <properties> 
 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> 
 </properties> 
 
 <build> 
 <finalName>${project.groupId}.${project.artifactId}_${project.version}</finalName> 
 <pluginManagement> 
 <plugins> 
 <plugin> 
 <groupId>org.apache.felix</groupId> 
 <artifactId>maven-bundle-plugin</artifactId> 
 <version>2.3.4</version> 
 </plugin> 
 <plugin> 
 <groupId>org.apache.maven.plugins</groupId> 
 <artifactId>maven-source-plugin</artifactId> 
 <version>2.1.2</version> 
 </plugin> 
 </plugins> 
 </pluginManagement> 
 <plugins> 
 <plugin> 
 <groupId>org.apache.felix</groupId> 
 <artifactId>maven-bundle-plugin</artifactId> 
 <extensions>true</extensions> 
 <configuration> 
 <instructions> 
 <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName> 
 <Bundle-Version>${project.version}</Bundle-Version> 
 <!-- Allow each bundle to override these settings by creating a file --> 
 <_include>src/main/resources/META-INF/MANIFEST.MF</_include> 
 </instructions> 
 </configuration> 
 </plugin> 
 </plugins> 
 </build> 
</project>

Important things to notice in this parent pom.xml are :

line 20 : artifact final name is overriden in order to meet OSGi bundle naming convention.
line 36 : maven-bundle-plugin execution is setup with defaults instructions for filling the MANIEST.MF file :

Bundle-Symbolic metadata will be initialized with ${project.groupId}.${project.artifactId} : org.escapek.neo4j-osgi-howto.javax-transaction-api here;
Bundle-version metadata is set to the project version : 1.1;

line 45 : the _include directive tells maven-bundle-plugin to add all the metadata from project file src/main/resources/META-INF/MANIFEST.MF.

Using this configuration, the parent POM declares common settings for maven-bundle-plugin. Every module can override these settings or simply provide some configuration in its src/main/resources/META-INF/MANIFEST.MF. For project javax-transaction-api we have in the MANIFEST.MF file :

Export-Package: javax.*;version=${project.version} 
Import-Package: *;resolution:=optional

In this file, the directives act as filters :

line 1: adds Export-Package metadata which tells the OSGi framework which packages the bundle exports. Here the bundle will export all packages from artifact javax.transaction:jta:1.1;
line 2 : adds Import-Package metadata which tells the OSGi framework which packages are imported by this bundle. Here we define that any needed import is optional : the OSGi framework will start the bundle even if all imports are not satisfied.

See the maven-bundle-plugin documentation for a complete list of usable metadata and their syntax.

Now run mvn package from the javax-transaction-api project directory to create the bundle. As expected, you will get a new file called org.escapek.neo4j-osgi-howto.javax-transaction-api_1.1.jar in target/. Look at the file content :

$ jar tvf org.escapek.neo4j-osgi-howto.javax-transaction-api_1.1.jar 
 552 Thu Apr 14 12:39:10 CEST 2011 META-INF/MANIFEST.MF 
 0 Thu Apr 14 12:39:10 CEST 2011 META-INF/ 
 0 Thu Apr 14 12:39:10 CEST 2011 META-INF/maven/ 
 0 Thu Apr 14 12:39:10 CEST 2011 META-INF/maven/org.escapek.neo4j-osgi-howto/ 
 0 Thu Apr 14 12:39:10 CEST 2011 META-INF/maven/org.escapek.neo4j-osgi-howto/javax-transaction-api/ 
 162 Thu Apr 14 12:39:10 CEST 2011 META-INF/maven/org.escapek.neo4j-osgi-howto/javax-transaction-api/pom.properties 
 861 Thu Apr 14 11:59:02 CEST 2011 META-INF/maven/org.escapek.neo4j-osgi-howto/javax-transaction-api/pom.xml 
 0 Thu Apr 14 12:39:10 CEST 2011 javax/ 
 0 Thu Apr 14 12:39:10 CEST 2011 javax/transaction/ 
 477 Fri Jan 05 11:38:46 CET 2007 javax/transaction/HeuristicCommitException.class 
 474 Fri Jan 05 11:38:46 CET 2007 javax/transaction/HeuristicMixedException.class 
 483 Fri Jan 05 11:38:46 CET 2007 javax/transaction/HeuristicRollbackException.class 
 491 Fri Jan 05 11:38:46 CET 2007 javax/transaction/InvalidTransactionException.class 
 468 Fri Jan 05 11:38:46 CET 2007 javax/transaction/NotSupportedException.class 
 456 Fri Jan 05 11:38:46 CET 2007 javax/transaction/RollbackException.class 
 541 Fri Jan 05 11:38:46 CET 2007 javax/transaction/Status.class 
 195 Fri Jan 05 11:38:46 CET 2007 javax/transaction/Synchronization.class 
 583 Fri Jan 05 11:38:46 CET 2007 javax/transaction/SystemException.class 
 773 Fri Jan 05 11:38:46 CET 2007 javax/transaction/Transaction.class 
 885 Fri Jan 05 11:38:46 CET 2007 javax/transaction/TransactionManager.class 
 494 Fri Jan 05 11:38:46 CET 2007 javax/transaction/TransactionRequiredException.class 
 500 Fri Jan 05 11:38:46 CET 2007 javax/transaction/TransactionRolledbackException.class 
 531 Fri Jan 05 11:38:46 CET 2007 javax/transaction/TransactionSynchronizationRegistry.class 
 661 Fri Jan 05 11:38:46 CET 2007 javax/transaction/UserTransaction.class 
 0 Thu Apr 14 12:39:10 CEST 2011 javax/transaction/xa/ 
 1449 Fri Jan 05 11:38:46 CET 2007 javax/transaction/xa/XAException.class 
 1062 Fri Jan 05 11:38:46 CET 2007 javax/transaction/xa/XAResource.class 
 292 Fri Jan 05 11:38:46 CET 2007 javax/transaction/xa/Xid.class

You can already see the first thing the maven-bundle-plugin has done, which is exploding the content of javax.transaction:jta:1.1 directly into the new JAR file.

Now you can also have a look at the MANIFEST.MF file :

Manifest-Version: 1.0 
Export-Package: javax.transaction;uses:="javax.transaction.xa";version="1.1",javax.transaction.xa;version="1.1" 
Tool: Bnd-1.15.0 
Bundle-Name: EscapeK - Bundles - Java transaction API 
Created-By: Apache Maven Bundle Plugin 
Build-Jdk: 1.6.0_24 
Bundle-Version: 1.1 
Bnd-LastModified: 1302777551765 
Bundle-ManifestVersion: 2 
Bundle-Description: Bundled version of Java Transaction API 
Bundle-SymbolicName: org.escapek.neo4j-osgi-howto.javax-transaction-api 
Import-Package: *;resolution:=optional

The maven-bundle-plugin has added and computed the necessary metadata to make our JAR file a valid OSGi bundle :

line 2 : The exact list of exported packages has been computed from the liste of packages present in the dependency and according to the filters put in src/main/resources/META-INF/MANIFEST.MF.

Conclusion : org.escapek.neo4j-osgi-howto.javax-transaction-api_1.1.jar is now a valid OSGi bundle which can be directly installed on any OSGi framework.