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.

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.

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:

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.

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

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.

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).

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