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.mffile. [IMPEXP]- Lists any Java packages that are imported or exported through the
Import-PackageorExport-PackageManifest 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.log4jDefault 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
