Chapter 12. Deploying a WAR

Abstract

This chapter explains how to deploy a Web archive (WAR) file as a bundle in the OSGi container. Conversion to a bundle is performed automatically by the PAX War URL, which is based on the open source Bnd tool. The presence of a web.xml file in the bundle signals to the container that the bundle should be deployed as a Web application.
Important
The information in this chapter pertains to deploying standard JEE WAR files into an OSGi container. For complex War files, those which combine components, such as Apache Camel and Spring, the easiest and most efficient way to deploy them into a JBoss Fuse container is to use JBoss Fuse on EAP. For details, see the JBoss Fuse on EAP documention listed under Getting Started and Adminisration on JBoss EAP on the Red Hat Customer Portal.

12.1. Converting the WAR Using the war Scheme

Overview

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.

Syntax

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&...

Prerequisite

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.

Deploying a WAR file

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

Accessing the Web application

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

Default conversion parameters

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”.

Customizing the conversion parameters

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”).

References

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.