Chapter 12. Deploying a WAR

To convert a WAR file into a bundle suitable for deployment in the OSGi container, add the war: prefix to the WAR URL. The PAX War URL handler acts as a wrapper, which adds the requisite manifest headers to the WAR file.

The war scheme has the following basic syntax:

war:LocationURL[?Options]

The location URL, LocationURL, can be any of the location URLs described in Appendix A, URL Handlers (for example, an mvn: or a file: URL). Options can be appended to the URL in the following format:

?Option=Value&Option=Value&...

Or if the war URL appears in an XML file:

?Option=Value&Option=Value&...

The Apache Karaf war feature is required to convert and deploy WARs using the war: scheme. It can be installed from the container's command console using features:install war.

If the WAR file is stored in a Maven repository, you can deploy it into the OSGi container using the osgi:install command, taking a war:mvn: URL as its argument. For example, to deploy the wicket-example WAR file from a Maven repository, where the application should be accessible from the wicket Web application context, enter the following console command:

JBossFuse:karaf@root> install war:mvn:org.apache.wicket/wicket-examples/1.4.7/war?Web-ContextPath=wicket

Alternatively, if the WAR file is stored on the filesystem, you can deploy it into the OSGi container by specifying a war:file: URL. For example, to deploy the WAR file, wicket-example-1.4.6.war, enter the following console command:

JBossFuse:karaf@root> install war:file://wicket-examples-1.4.7.war?Web-ContextPath=wicket

The WAR file is automatically installed into a Web container, which listens on the TCP port 8181 by default, and the Web container uses the Web application context specified by the Web-ContextPath option. For example, the wicket-example WAR deployed in the preceding examples, would be accessible from the following URL:

http://localhost:8181/wicket

The PAX War URL handler converts a WAR file to a special kind of OSGi bundle, which includes additional Manifest headers to support WAR deployment (for example, the Web-ContextPath Manifest header). By default, the deployed WAR is configured as an isolated bundle (neither importing nor exporting any packages). This mimics the deployment model of a WAR inside a J2EE container, where the WAR is completely self-contained, including all of the JAR files it needs.

For details of the default conversion parameters, see Table A.2, “Default Instructions for Wrapping a WAR File”.

The PAX War URL handler is layered over Bnd. If you want to customize the bundle headers in the Manifest file, you can either add a Bnd instruction as a URL option or you can specify a Bnd instructions file for the War URL handler to use—for details, see Section A.5, “War URL Handler”.

In particular, you might sometimes find it necessary to customize the entry for the Bundle-ClassPath, because the default value of Bundle-ClassPath does not include all of the resources in the WAR file (see Table A.2, “Default Instructions for Wrapping a WAR File”).

Support for running WARs in the OSGi container is provided by the PAX WAR Extender, which monitors each bundle as it starts and, if the bundle contains a web.xml file, automatically deploys the WAR in a Web container. The War Protocol page has the original reference documentation for the War URL handler.