Mastering modularity - OSGi in Action - page 36

from where it comes. The OSG i specification defines several pieces of metadata for
this purpose, but none of it is required, nor does it have any impact on modularity.
The OSG i framework completely ignores it.
The following code snippet shows human-readable bundle metadata for the paint
program's org.foo.shape bundle (the other program bundles are described similarly):

Bundle-Name: Simple Paint API
Bundle-Description: Public API for a simple paint program.
Bundle-DocURL: http://www.manning.com/osgi-in-action/
Bundle-Category: example, library
Bundle-Vendor: OSGi in Action
Bundle-ContactAddress: 1234 Main Street, USA
Bundle-Copyright: OSGi in Action
The Bundle-Name attribute is intended to be a short name for the bundle. You're free
to name your bundle anything you want. Even though it's supposed to be a short
name, there's no enforcement of this; just use your best judgment. The Bundle-
Description attribute lets you be a little more long-winded in describing the purpose
of your bundle. To provide even more documentation about your bundle, Bundle-
DocURL allows you to specify a URL to refer to documentation. Bundle-Category
defines a comma-separated list of category names. OSG i doesn't define any standard
category names, so you're free to choose your own. The remaining attributes, Bundle-
Vendor , Bundle-ContactAddress , and Bundle-Copyright , provide information about
the bundle vendor.
Human-readable metadata is reasonably straightforward. The fact that the OSG i
framework ignores it means you can pretty much do what you want to with it. But
don't fall into a laissez-faire approach just yet—the remaining metadata requires more
precision. Next, we'll look at how you use metadata to uniquely identify bundles.

2.5.2 Bundle identification

The human-readable metadata from the previous subsection helps you understand
what a bundle does and where it comes from. Some of this human-readable metadata
also appears to play a role in identifying a bundle. For example, Bundle-Name seems
like it could be a form of bundle identification. It isn't. The reason is somewhat histor-
ical. Earlier versions of the OSG i specification didn't provide any means to uniquely
identify a given bundle. Bundle-Name was purely informational, and therefore no con-
straints were placed on its value. As part of the OSG i R4 specification process, the idea
of a unique bundle identifier was proposed. For backward-compatibility reasons, Bun-
dle-Name couldn't be commandeered for this purpose because it wouldn't be possible
to place new constraints on it and maintain backward compatibility. Instead, a new
manifest entry was introduced: Bundle-SymbolicName .
In contrast to Bundle-Name , which is only intended for users, Bundle-SymbolicName
is only intended for the OSG i framework to help uniquely identify a bundle. The value
of the symbolic name follows rules similar to Java package naming: it's a series of dot-
separated strings, where reverse domain naming is recommended to avoid name