Migration and integration - Enterprise OSGi in Action - page 277

in WEB-INF and to be called web.xml, and expect to find servlet classes on the inter-
nal classpath of the web application. As a result, you don't need to change your WAR 's
internal structure at all!
The only important detail that separates a WAB from a WAR is that it has OSG i meta-
data in its manifest that makes it an OSG i bundle. By including this metadata, most stand-
alone WAR s can be converted into working WAB s with no other changes at all!

CREATING OSGI METADATA FOR A WAR
All Java manifest files must declare the version of the manifest syntax that they use. To
make a valid OSG i bundle, there are two more required headers, a Bundle-Manifest-
Version with a value of 2 , and a Bundle-SymbolicName that defines the bundle's
name. Because a WAB is a bundle, it also needs these two headers, but it must also add
a third that identifies it as a WAB . This is the Web-ContextPath header, which not only
identifies the bundle as a WAB , but also defines a default context root (base URL )
from which the web application should be served. Although versioning your bundle
isn't strictly required, we would never build a bundle without versioning it properly,
and would urge you not to either (for more information about why, see section 5.1.1).
The result of this is that the smallest possible WAB manifest looks something like
the following listing.

Listing 11.1 A minimal WAB manifest

Manifest-Version: 1
Bundle-ManifestVersion: 2
Bundle-SymbolicName: my.simple.wab
Bundle-Version: 1.0.0
Web-ContextPath: /contextRoot
COPING WITH THE WAR CLASSPATH
It's clearly easy to provide enough metadata to get OSG i to recognize a WAR file as an
OSG i WAB , but this isn't enough to make the WAR file work as a WAB . One of the most
critical differences is surprisingly easy to overlook: the internal structure of the WAR
file itself!
Changing the extension of a Java EE module from .jar to .war has a much more
extensive effect on the module than changing its name. WAR files have an internal
classpath that's different from normal JAR files. In a WAR , the servlet classes are sup-
posed to live in WEB-INF /classes, not the root of the WAR (which is used for noncode
resources). Furthermore, library JAR s can be included inside a WAR file; any file with a
.jar extension in the WEB-INF /lib folder of your WAR is implicitly added to the internal
classpath (see figure 11.5).
One of the best things you can do to help turn your WAR into a WAB is to remem-
ber that the internal classpath of an OSG i bundle is (by default) like a normal JAR .
This means that you have some work to do to allow OSG i to find your classes! You have
two options: you can either adjust the structure of your WAR to match a standard JAR
layout, or you can adjust the classpath of your OSG i bundle to match the layout of your
WAR . The latter approach has several advantages: it's less invasive, less error-prone,