9.2. Converting a JAR Using Bnd

Overview

This section describes how to convert a vanilla JAR file into an OSGi bundle using the Bnd tool's wrap command. You can choose either to perform the conversion with default settings (which works in most cases) or to perform a custom conversion with the help of a Bnd properties file.

Sample JAR file

To demonstrate how to convert a plain JAR into a bundle, we will consider the example of the commons-logging-Version.jar, which is available from the Apache Commons project and can be downloaded from the following location: 
http://commons.apache.org/downloads/download_logging.cgi
Note
Actually, this is a rather artificial example, because the Apache Commons logging API is not intended to be deployed as an OSGi bundle (which is why it does not have the requisite Manifest headers in the first place). Most of the other JARs from Apache Commons are already provided as bundles.

Bnd print command

The Bnd print command is a useful diagnostic tool that displays most of the information about a JAR that is relevant to bundle creation. For example, to print the Manifest headers and package dependencies of the commons logging JAR, you can invoke the Bnd print command as follows: 
java -jar bnd.jar print commons-logging-1.1.1.jar
The preceding command produces the following output: 
[MANIFEST commons-logging-1.1.1.jar]
Archiver-Version                        Plexus Archiver
Build-Jdk                               1.4.2_16
Built-By                                dlg01
Created-By                              Apache Maven
Extension-Name                          org.apache.commons.logging
Implementation-Title                    Commons Logging
Implementation-Vendor                   Apache Software Foundation
Implementation-Vendor-Id                org.apache
Implementation-Version                  1.1.1
Manifest-Version                        1.0
Specification-Title                     Commons Logging
Specification-Vendor                    Apache Software Foundation
Specification-Version                   1.0
X-Compile-Source-JDK                    1.2
X-Compile-Target-JDK                    1.1

[IMPEXP]

[USES]
org.apache.commons.logging              org.apache.commons.logging.impl
org.apache.commons.logging.impl         javax.servlet
                                        org.apache.avalon.framework.logger
                                        org.apache.commons.logging
                                        org.apache.log
                                        org.apache.log4j
One error
1 : Unresolved references to [javax.servlet, org.apache.avalon.framework.logger,
 org.apache.log, org.apache.log4j] by class(es) on the Bundle-Classpath[Jar:comm
ons-logging-1.1.1.jar]: [org/apache/commons/logging/impl/AvalonLogger.class, org
/apache/commons/logging/impl/ServletContextCleaner.class, org/apache/commons/log
ging/impl/LogKitLogger.class, org/apache/commons/logging/impl/Log4JLogger.class]
From this output, you can see that the JAR does not define any bundle manifest headers. The output consists of the following sections:
[MANIFEST JarFileName]
Lists all of the header settings from the JAR file's META-INF/Manifest.mf file.
[IMPEXP]
Lists any Java packages that are imported or exported through the Import-Package or Export-Package Manifest headers.
[USES]
Shows the JAR's package dependencies. The left column lists all of the packages defined in the JAR, while the right column lists the dependent packages for each of the packages in the left column.
Errors
Lists any errors—for example, any unresolved dependencies.

Bnd wrap command

To convert the plain commons logging JAR into an OSGi bundle, invoke the Bnd wrap command as follows: 
java -jar bnd.jar wrap commons-logging-1.1.1.jar
The result of running this command is a bundle file, commons-logging-1.1.1.bar, which consists of the original JAR augmented by the Manifest headers required by a bundle.

Checking the new bundle headers

To display the Manifest headers and package dependencies of the newly created bundle JAR, enter the following Bnd print command: 
java -jar bnd.jar print commons-logging-1.1.1.bar
The preceding command should produce output like the following: 
[MANIFEST commons-logging-1.1.1-bnd.jar]
Archiver-Version                        Plexus Archiver
Bnd-LastModified                        1263987809524
Build-Jdk                               1.4.2_16
Built-By                                dlg01
Bundle-ManifestVersion                  2
Bundle-Name                             commons-logging-1.1.1
Bundle-SymbolicName                     commons-logging-1.1.1
Bundle-Version                          0
Created-By                              1.5.0_08 (Sun Microsystems Inc.)
Export-Package                          org.apache.commons.logging;uses:="org.ap
ache.commons.logging.impl",org.apache.commons.logging.impl;uses:="org.apache.ava
lon.framework.logger,org.apache.commons.logging,org.apache.log4j,org.apache.log,
javax.servlet"
Extension-Name                          org.apache.commons.logging
Implementation-Title                    Commons Logging
Implementation-Vendor                   Apache Software Foundation
Implementation-Vendor-Id                org.apache
Implementation-Version                  1.1.1
Import-Package                          javax.servlet;resolution:=optional,org.a
pache.avalon.framework.logger;resolution:=optional,org.apache.commons.logging;re
solution:=optional,org.apache.commons.logging.impl;resolution:=optional,org.apac
he.log;resolution:=optional,org.apache.log4j;resolution:=optional
Manifest-Version                        1.0
Originally-Created-By                   Apache Maven
Specification-Title                     Commons Logging
Specification-Vendor                    Apache Software Foundation
Specification-Version                   1.0
Tool                                    Bnd-0.0.384
X-Compile-Source-JDK                    1.2
X-Compile-Target-JDK                    1.1


[IMPEXP]
Import-Package
  javax.servlet                         {resolution:=optional}
  org.apache.avalon.framework.logger    {resolution:=optional}
  org.apache.log                        {resolution:=optional}
  org.apache.log4j                      {resolution:=optional}
Export-Package
  org.apache.commons.logging
  org.apache.commons.logging.impl

[USES]
org.apache.commons.logging              org.apache.commons.logging.impl
org.apache.commons.logging.impl         javax.servlet
                                        org.apache.avalon.framework.logger
                                        org.apache.commons.logging
                                        org.apache.log
                                        org.apache.log4j

Default property file

By default, the Bnd wrap command behaves as if it was configured to use the following Bnd property file: 
Export-Package: * 
Import-Package: AllReferencedPackages
The result of this configuration is that the new bundle imports all of the packages referenced by the JAR (which is almost always what you need) and all of the packages defined in the JAR are exported. Sometimes you might want to hide some of the packages in the JAR, however, in which case you would need to define a custom property file.

Defining a custom property file

If you want to have more control over the way the Bnd wrap command generates a bundle, you can define a Bnd properties file to control the conversion process. For a detailed description of the syntax and capabilities of the Bnd properties file, see the Bnd tool documentation.
For example, in the case of the commons logging JAR, you might decide to hide the org.apache.commons.logging.impl package, while exporting the org.apache.commons.logging package. You could do this by creating a Bnd properties file called commons-logging-1.1.1.bnd and inserting the following lines using a text editor: 
version=1.1.1
Export-Package: org.apache.commons.logging;version=${version}
Private-Package: org.apache.commons.logging.impl
Bundle-Version: ${version}
Notice how a version number is assigned to the exported package by substituting the version variable (any properties starting with a lowercase letter are interpreted as variables).

Wrapping with the custom property file

To wrap a JAR file using the custom property file, specify the Bnd properties file using the -properties option of the wrap command. For example, to wrap the vanilla commons logging JAR using the instructions contained in the commons-logging-1.1.1.bnd properties file, enter the following command: 
java -jar bnd.jar wrap -properties commons-logging-1.1.1.bnd commons-logging-1.1.1.jar