Delving deeper into modularity - OSGi in Action - page 171

We've finished covering the advanced capabilities for importing packages, but there's
still a related concept provided by OSG i for declaring dependencies. In some situa-
tions, such as legacy situations where modules are tightly coupled or contain a given
package split across modules, importing a specific package isn't sufficient. For these
situations, OSG i allows you to declare dependencies on specific bundles. We'll look at
how this works next.

5.3 Requiring bundles

In section 5.1.2, we discussed how implicit export attributes allow bundles to import
packages from a specific bundle. The OSG i specification also supports a module-level
dependency concept called a required bundle that provides a similar capability. In chap-
ter 2, we discussed a host of reasons why package-level dependencies are preferred
over module-level dependencies, such as them being more flexible and fine-grained.
We won't rehash those general issues. But there is one particular use case where
requiring bundles may be necessary in OSG i: if you must deal with split packages.

SPLIT PACKAGE A split package is a Java package whose classes aren't con-
tained in a single JAR but are split across multiple JAR files. In OSG i terms, it's
a package split across multiple bundles.

In standard Java programming, packages are generally treated as split; the Java class
path approach merges all packages from different JAR files on the class path into one
big soup. This is anathema to OSG i's modularization model, where packages are
treated as atomic (that is, they can't be split).
When migrating to OSG i from a world where split packages are common, we're
often forced to confront ugly situations. But even in the OSG i world, over time a pack-
age may grow too large and reach a point where you can logically divide it into disjoint
functionality for different clients. Unfortunately, if you break up the existing package
and assign new disjoint package names, you break all existing clients. Splitting the
package allows its disjoint functionality to be used independently; but for existing cli-
ents, you still need an aggregated view of the package.
This gives you an idea of what a split package is, but how does this relate to requir-
ing bundles? This will become clearer after we discuss what it means to require a bun-
dle and introduce a use case for doing so.

5.3.1 Declaring bundle dependencies

The big difference between importing a package and requiring a bundle is the scope
of the dependency. Whereas an imported package defines a dependency from a bun-
dle to a specific package, a required bundle defines a dependency from a bundle to
every package exported by a specific bundle. To require a bundle, you use the
Require-Bundle manifest header in the requiring bundle's manifest file.

REQUIRE-BUNDLE This header consists of a comma-separated list of target
bundle symbolic names on which a bundle depends, indicating the need to
access all packages exported by the specifically mentioned target bundles.