Moving toward bundles - OSGi in Action - page 192

6.1 Turning JARs into bundles

As you saw in chapter 2, a bundle is a JAR file with additional metadata. So to turn a JAR
file into a bundle, you need to add metadata giving it a unique identity and describing
what it imports and exports. Simple, right? For most business-domain JAR files, it is;
but for others (such as third-party GUI or database libraries), you'll need to think care-
fully about their design. Where is the line between what's public and what's private,
which imports are required and which are optional, and which versions are compati-
ble with one another?
In this section, we'll help you come up with this metadata by taking a series of com-
mon library JAR files and turning them into working bundles. We'll also consider
some advanced bundling techniques, such as embedding dependencies inside the
bundle, as well as how to manage external resources and background threads.
Before you can even load a bun-
dle into an OSG i framework, it must
have an identity. This identity
should be unique, at least among
the set of bundles loaded into the
framework. But how should you
choose such an identity? If you pick
names at random, you may clash
with other projects or other devel-
opers, as shown in figure 6.1.

org.bar 1.0

foo 1.0

foo.bar 1.0

foo.bar 2.0

foo 2.0

org.foo 1.0 foo.bar 1.0

Figure 6.1 A bundle must have a unique identity.

6.1.1 Choosing an identity

Each bundle installed into an OSG i framework must have a unique identity, made up
of the Bundle-SymbolicName and Bundle-Version . We'll look into approaches for
defining both of these now.

CHOOSING A SYMBOLIC NAME
One of the first steps in turning a JAR file into a bundle is to decide what symbolic
name to give it. The OSG i specification doesn't mandate a naming policy but recom-
mends a reverse-domain naming convention. This is the same as Java package nam-
ing: if the bundle is the primary source of a particular package, it makes sense to use it
as the Bundle-SymbolicName .
Let's look at a real-world example, the k XML parser ( http://kxml.source-
forge.net/ ) . This small JAR file provides two distinct top-level packages: the XmlPull
API org.xmlpull.v1 and the k XML implementation org.kxml2. If this JAR was the only
one expected to provide the org.xmlpull.v1 API , or if it only contained this package, it
would be reasonable to use this as the symbolic name. But this JAR file also provides a
particular implementation of the XmlPull API , so it makes more sense to use the name
of the implementation as the symbolic name because it captures the essence of what
the bundle provides:

Bundle-SymbolicName: org.kxml2