6.3. Packaging a Web Service in a Bundle
Overview
This section explains how to modify an existing Maven project for a Apache CXF application, so that the project generates an OSGi bundle suitable for deployment in the Red Hat JBoss Fuse OSGi container. To convert the Maven project, you need to modify the project's POM file and the project's Spring XML file(s) (located in
META-INF/spring).
Modifying the POM file to generate a bundle
To configure a Maven POM file to generate a bundle, there are essentially two changes you need to make: change the POM's package type to
bundle; and add the Maven bundle plug-in to your POM. For details, see Section 6.1, “Generating a Bundle Project”.
Required bundle
The Apache CXF runtime components are included in JBoss Fuse as an OSGi bundle called
org.apache.cxf.bundle. The dependency on this bundle can conveniently be expressed by adding the Require-Bundle element to the Maven bundle plug-in's instructions, as highlighted in the following sample POM:
<project ... >
...
<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
...
<Require-Bundle>org.apache.cxf.bundle</Require-Bundle>
...
</instructions>
</configuration>
</plugin>
</plugins>
</build>
...
</project>Mandatory import packages
In order for your application to use the Apache CXF components, you need to import their packages into the application's bundle. Because of the complex nature of the dependencies in Apache CXF, you cannot rely on the Maven bundle plug-in, or the bnd tool, to automatically determine the needed imports. You will need to explicitly declare them.
You need to import the following packages into your bundle:
javax.jws javax.wsdl javax.xml.bind javax.xml.bind.annotation javax.xml.namespace javax.xml.ws META-INF.cxf META-INF.cxf.osgi org.apache.cxf.bus org.apache.cxf.bus.spring org.apache.cxf.bus.resource org.apache.cxf.configuration.spring org.apache.cxf.resource org.apache.cxf.jaxws org.springframework.beans.factory.config
Sample Maven bundle plug-in instructions
Example 6.1, “Configuration of Mandatory Import Packages” shows how to configure the Maven bundle plug-in in your POM to import the mandatory packages. The mandatory import packages appear as a comma-separated list inside the
Import-Package element. Note the appearance of the wildcard, *, as the last element of the list. The wildcard ensures that the Java source files from the current bundle are scanned to discover what additional packages need to be imported.
Example 6.1. Configuration of Mandatory Import Packages
<project ... >
...
<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
...
<Import-Package>
javax.jws,
javax.wsdl,
javax.xml.bind,
javax.xml.bind.annotation,
javax.xml.namespace,
javax.xml.ws,
META-INF.cxf,
META-INF.cxf.osgi,
org.apache.cxf.bus,
org.apache.cxf.bus.spring,
org.apache.cxf.bus.resource,
org.apache.cxf.configuration.spring,
org.apache.cxf.resource,
org.apache.cxf.jaxws,
org.springframework.beans.factory.config,
*
</Import-Package>
...
</instructions>
</configuration>
</plugin>
</plugins>
</build>
...
</project>Add a code generation plug-in
A Web services project typically requires code to be generated. Apache CXF provides two Maven plug-ins for the JAX-WS front-end, which enable tyou to integrate the code generation step into your build. The choice of plug-in depends on whether you develop your service using the Java-first approach or the WSDL-first approach, as follows:
- Java-first approach—use the
cxf-java2ws-pluginplug-in. - WSDL-first approach—use the
cxf-codegen-pluginplug-in.
OSGi configuration properties
The OSGi Configuration Admin service defines a mechanism for passing configuration settings to an OSGi bundle. You do not have to use this service for configuration, but it is typically the most convenient way of configuring bundle applications. Both Spring DM and Blueprint provide support for OSGi configuration, enabling you to substitute variables in a Spring XML file or a Blueprint file using values obtained from the OSGi Configuration Admin service.
For details of how to use OSGi configuration properties, see Section 6.4, “Configuring the Bundle Plug-In” and the section called “Add OSGi configurations to the feature”.
