Moving toward bundles - OSGi in Action - page 200

excessive, it affects all users of the bundle. Unfortunately, standard Java tools don't
provide an easy way to determine which packages a JAR file may use at execution
time. Manually skimming the source for package names is time consuming and unre-
liable. Byte-code analysis is more reliable and repeatable, which is especially impor-
tant for distributed teams, but it can miss classes that are dynamically loaded by
name. For instance, this could load a class from any package:
String name = someDynamicNameConstruction(someSortOfContext);
Class<?> clazz = someClassLoader.loadClass(name);
The ideal solution is to use a byte-code analysis tool like bnd ( http://aqute.biz/
Code/Bnd ) followed by a manual review of the generated metadata by project devel-
opers. You can then decide whether to keep generating the list of imported packages
for every build or generate the list once and save it to a version-controlled file some-
where so it can be pulled into later builds. Most tools for generating OSG i manifests
also let you supplement or override the generated list, in case the manual review finds
missing or incorrect packages.
After you're happy with the metadata, you should run integration tests on an OSG i
framework to verify that the bundle has the necessary imported packages. You don't
want to get a ClassNotFoundException in production when an obscure but impor-
tant piece of code runs for the first time and attempts to access a package that hasn't
been imported!
USING TOOLS TO GENERATE IMPORTS
Let's continue with the BeanUtils example and use bnd to discover what imports you
need. The bnd tool was developed by the OSG i director of technology, Peter Kriens,
and provides a number of Ant tasks and command-line commands specifically
designed for OSG i. Bnd uses a pull approach to divide a single class path into separate
bundles based on a set of instructions. This means you have to tell bnd what packages
you want to pull in and export, as well as those you want to pull in and keep private.
Bnd instructions use the same format as OSG i directives, which means you can mix
normal manifest entries along with bnd instructions. In addition to accepting OSG i
manifest headers as instructions, bnd adds some of its own, such as Include-Resource
and Private-Package , to give you more control over exactly what goes into the bun-
dle. These instructions aren't used by the OSG i framework at execution time.
The following instructions select the exported and non-exported (or so-called pri-
vate ) packages that should be contained in your final BeanUtils bundle. You start by
exporting all of the BeanUtils API , as discussed in section 6.1.2. Remember that you
also want to remove the partial Collections package from the internals and import it
instead. Finally, you let bnd decide what this bundle needs to import. Let's put these
instructions in a file named beanutils.bnd, which you can find under chapter06/
BeanUtils-example/ in this topic's examples:
Export-Package: org.apache.commons.beanutils.*
Private-Package: !org.apache.commons.collections.*, *
Import-Package: *