Deploying Spring MVC Based Web Applications to OSGi Using Apache ServiceMix

The OSGi specification defines appropriate bundle manifest headers and mechanisms for the deployment of servlet-based WAR packaged applications into an OSGi container. As with most APIs, programming a modern application using the Servlet specification requires copious amounts of boilerplate code that any number of Web application frameworks can reduce. The Spring MVC framework is among these Web application frameworks. As with many of the capabilities of an OSGi container, the hooks for integrating the WAR with the capabilities of the container, such as OSGi services; modularity; configuration; and class loading, requires programming copious amounts of boilerplate code to OSGi APIs. Unlike the world of Web applications, there are far fewer frameworks for simplifying deployment in an OSGi container. The Spring DM framework is among this small group. This article discusses how to leverage the Spring MVC framework together with the capabilities of Spring DM in order to take full advantage of the value added features of both frameworks. This article uses Apache ServiceMix as the target platform.

Update September 4, 2013: The source code tagged 1.0 works with ServiceMix 4.3.  The source code tagged 1.1 works with ServiceMix 4.5.2.  The source code is largely the same except for differences in the Karaf feature descriptor needed to install the correct version of Spring MVC and Spring DM for the targeted ServiceMix container.  The article provides instructions for obtaining the correct source code for the targeted ServiceMix container as needed.

The Project and Build Structure

One of the easiest ways to assemble an OSGi ready WAR is to use Maven in conjunction with the WAR and Felix Bundle Plug-ins. The WAR Plug-in allows the build to produce a WAR artifact while the Bundle Plug-in simplifies the creation of the OSGi manifest. The following Maven POM snippet illustrates the key points of the Maven build. The complete POM can be found in the source code repository.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
  ...
  <packaging>war</packaging>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- Make a skinny WAR -->
          <packagingExcludes>WEB-INF/lib/*.jar</packagingExcludes>
          <archive>
            <manifestFile>${basedir}/target/bnd/MANIFEST.MF</manifestFile>
          </archive>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>2.3.5</version>
        <executions>
          <execution>
            <id>bundle-manifest</id>
            <phase>process-classes</phase>
            <goals>
              <goal>manifest</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <supportedProjectTypes>
            <supportedProjectType>war</supportedProjectType>
          </supportedProjectTypes>
          <manifestLocation>target/bnd</manifestLocation>
          <instructions>
            <Webapp-Context>spring-mvc-smx</Webapp-Context>
            <Web-ContextPath>spring-mvc-smx</Web-ContextPath>
            <Export-Package>!*</Export-Package>
            <Import-Package>
              javax.servlet; version="[2.4.0, 4.0.0)",
              javax.servlet.http; version="[2.4.0, 4.0.0)",
              javax.servlet.jsp.jstl.core; version="[1.2,2.0)",
              javax.servlet.resources; version="[2.4.0, 4.0.0)",
              <!-- Just import EVERYTHING from Apache standard JSTL impl. -->
              org.apache.taglibs.standard; version="[1.2.0,2)",
              org.apache.taglibs.standard.extra.spath; version="[1.2.0,2)",
              org.apache.taglibs.standard.functions; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl.parser; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl.test; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl.test.beans; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.support; version="[1.2.0,2)",
              org.apache.taglibs.standard.resources; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.core; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.fmt; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.sql; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.xml; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.core; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.fmt; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.sql; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.xml; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.core; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.fmt; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.sql; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.xml; version="[1.2.0,2)",
              org.apache.taglibs.standard.tei; version="[1.2.0,2)",
              org.apache.taglibs.standard.tlv; version="[1.2.0,2)",
              org.springframework.beans.factory.config,
              org.springframework.osgi.web.context.support; version="[1.2,2.0)",
              org.springframework.stereotype,
              org.springframework.web.bind.annotation,
              org.springframework.web.servlet,
              org.springframework.web.servlet.view,
              *
            </Import-Package>
            <Bundle-ClassPath>
              WEB-INF/classes,
              <!-- Have to use this for PAX Web 0.7.4 to find JSPs since it uses classpath. -->
              .
            </Bundle-ClassPath>
          </instructions>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
</project>

• Line 4 – This line is the standard way in which you instruct Maven to construct a WAR artifact instead of the default JAR packaging.
• Line 13 – This line instructs the WAR Plug-in to exclude all dependencies from the WAR. The resulting WAR imports all of its dependencies from the OSGi class loader and is therefore significantly smaller than a traditional WAR.
• Line 15 – This line instructs the WAR Plug-in to use an externally generated manifest file instead of the one that is automatically generated by default.
• Line 28 – This line instructs the Felix Bundle Plug-in to generate a manifest file on the file system when the plug-in is executed. Normally, the plug-in injects the manifest directly into the artifact; however, this behavior conflicts with that of the WAR plug-in so we configure this plug-in to write the file to disk and we configure the WAR Plug-in to use the manifest file from the file system.
• Line 34 – This line instructs the Felix Bundle Plug-in to execute for projects with the WAR packaging type. The plug-in will not execute for this type of packaging by default.
• Line 36 – This line indicates where the Felix Bundle Plug-in should write the manifest file. Note that this location aligns with the location that the WAR Plug-in reads the manifest file from.
• Lines 38-39 – These lines provide the context path for the Web application when it is deployed. The context path is the portion of the path preceding the application specific path. In this case, all application URLs will start with http://HOST:PORT/spring-mvc-smx. This property is specified twice in order to support a wider range of PAX Web Extender versions. Web-ContextPath is the official OSGi header while Webapp-Context is the PAX Web Extender specific header supported in earlier versions of PAX Web. PAX Web is the implementation of the WAR related OSGi capabilities that is used in ServiceMix. This library is responsible or connecting the WAR to the underlying OSGi framework as well as publishing the WAR to the OSGi HTTP Service.
• Lines 42-45 – These lines indicate that the OSGi container, through its class loading mechanism, should provide the standard Servlet API classes. Much like standard WAR deployments, the container frequently provides these API classes to the class path.
• Lines 46-69 – These lines indicate that the OSGi container should provide the Apache implementation of the JSTL to the WAR. In this case, we simply import all of the packages that the Apache “standard” JSTL implementation library exports. These package imports are required if your application includes JSPs that leverage the JSTL tags, but may vary if you choose to use a different implementation. Providing these packages from the container instead of WEB-INF/lib means that your WAR size can be reduced and the implementation library can be shared across multiple WARs. As these packages are not directly referenced from compiled code, they are not automatically detected by the plug-in and therefore must be manually specified.
• Line 70-75 – These lines indicate that the OSGi container should provide the necessary Spring MVC classes from the OSGi class loader and not from WEB-INF/lib. As with the Apache JSTL implementation, these packages are not directly referenced from compiled code and are therefore not detected by the Felix Bundle Plug-in. These packages must be imported from the OSGi container to ensure a consistent class space with the Spring DM OsgiBundleXmlWebApplicationContext class.
• Lines 79-81 – These lines indicate that the bundle/WAR class path should also include the contents of specific locations within the WAR. The WEB-INF/classes folder provides the implementation classes for the WAR while the “.” entry is required to enable the PAX Web Extender to locate JSPs within the WAR. Some versions of the PAX Web Extender search for the JSP path using the WAR/bundle class path in lieu of searching the actual bundle/WAR contents. As such, including the root folder of the bundle/WAR on the class path ensures that JSPs can be resolved over a broader range of PAX Web versions.

The project folder structure is as follows:

• /src/main/java – This folder contains the source code for the WAR.
• /src/main/features – This folder contains the source file for the project Karaf Feature Descriptor.
• /src/main/webapp – This folder contains the contents that are copied into the root of the WAR. This folder contains JSPs, web.xml, and the Spring MVC application context file.

Spring MVC In an OSGi World

Spring MVC typically uses an XmlWebApplicationContext instance with the DispatcherServlet. Together, these two classes provide a means to bootstrap a Servlet container aware application context and to wire the Servlet container to the Spring MVC controllers. XmlWebApplicationContext is however, unaware of the OSGi container. For this reason, Spring DM provides an OsgiBundleXmlWebApplicationContext that can be substituted for XmlWebApplicationContext when deploying the WAR in an OSGi container. OsgiBundleXmlWebApplicationContext makes the application context in the WAR aware of the OSGi container and provides access to the capabilities provided by the container as well as the BundleContext of the deployed bundle/WAR. One specifies that the DispatcherServlet should use the OSGi aware version of the application context in the web.xml file of the bundle/WAR. The following web.xml snippet illustrates the relevant configuration. After this small change, the standard features of Spring and Spring MVC, including annotation based controllers and component scanning, are available within the OSGi deployed WAR. The complete web.xml can be found in the source code repository.

…
  <servlet>
    <servlet-name>spring-mvc-smx</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextClass</param-name>
      <param-value>org.springframework.osgi.web.context.support.OsgiBundleXmlWebApplicationContext</param-value>
    </init-param>
  </servlet>
…

• Lines 5-8 – Illustrate using an init-param for the DispatcherServlet to override the implementation class for the application context used by the servlet.

Tag Libraries in an OSGi World

Normally, tag libraries can be auto-detected from the WEB-INF/lib folder or specified in the web.xml file. As this example does not specify any JAR files from WEB-INF/lib in the Bundle-Classpath manifest header, the tag library implementation must be provided by the OSGi container class loader through a package import. While this approach does not require the tag library implementation to be included in the WAR itself, it does create a small issue with auto-discovery of the .tld files for the tag library. Tag library descriptor files reside in the META-INF folder of the JAR. When this JAR is not in the WEB-INF/lib folder and its packages are instead supplied by OSGi package imports, these files are not detected. The workaround for this limitation is to include the tag library descriptor files directly in the WAR and to reference them from web.xml. The following web.xml snippet illustrates the relevant configuration settings for including the JSTL .tld files from withing the WAR itself. The complete web.xml can be found in the source code repository.

…
  <jsp-config>
    <taglib>
      <taglib-uri>http://java.sun.com/jstl/core</taglib-uri>
      <taglib-location>/WEB-INF/tld/c.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/fmt</taglib-uri>
      <taglib-location>/WEB-INF/tld/fmt.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/fmt</taglib-uri>
      <taglib-location>/WEB-INF/tld/fmt.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/functions</taglib-uri>
      <taglib-location>/WEB-INF/tld/fn.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/xml</taglib-uri>
      <taglib-location>/WEB-INF/tld/x.tld</taglib-location>
    </taglib>
  </jsp-config>
…

• Lines 2-23 – These lines provide the location for the TLD files of the JSTL. The files were copied from the implementation JAR that the bundle/WAR imports the JSTL implementation packages from. Alternatively, the JSTL implementation JAR can be included in the WAR and added to the Bundle-Classpath manifest header; however, the bundle/WAR will then need to import the package dependencies from the implementation JAR or also add those dependencies to the Bundle-Classpath manifest header.

Bridging the OSGi WAR Gap

So far this article has discussed how to get Spring MVC to act like Spring MVC in an OSGi deployed WAR. If there were nothing more, the keener reader’s out there would be asking, “why would I go through all this trouble when Servlet container XXX will do just fine?” Don’t worry if you didn’t ask this question, you are already researching this topic and reading a blog. That makes you more keen than not. Because the WAR is using OsgiBundleXmlWebApplicationContext from Spring DM, all of the OSGi goodness that Spring DM brings to Spring is also available to the Spring MVC based applications. Service implementations for Spring MVC controllers can be looked up in the OSGi service registry, configuration options can be managed and updated through the OSGi Configuration Admin service, and previously insurmountable class space collisions can be overcome. The following Spring application context snippet illustrates one of the many convenient integration points that Spring DM can provide to the Web application. More examples of the Spring DM capabilities are available in the Spring DM documentation. The complete context file can be found in the source code repository.

...
<osgi:reference id="configurationAdmin"
                  interface="org.osgi.service.cm.ConfigurationAdmin"/>
...

• Lines 2-3 – This line illustrates how to retrieve a service from the OSGi registry. In this case, the service is the Configuration Admin service. The controller in the example application uses this service to list all of the configurations available in the OSGi container.

Once available in the application context, the bean can be used just as any other locally defined bean. The following Java snippet illustrates how the bean is injected into a controller and used to render the view.  The complete controller source is available in the source repository.

...

@Controller
@RequestMapping(value = "/")
public class HomeController {

    @Autowired
    BundleContext bundleContext;

    @Autowired
    ConfigurationAdmin configurationAdmin;

    RequestMapping(method = {RequestMethod.GET})
    public ModelAndView home() throws Exception {

        ModelAndView mav = new ModelAndView("home");

        Bundle[] bundles = bundleContext.getBundles();
        mav.addObject("bundles", bundles);

        Configuration[] configurations = configurationAdmin.listConfigurations(null);
        mav.addObject("configurations", configurations);
        return mav;
    }

    public BundleContext getBundleContext() {
        return bundleContext;
    }

    public void setBundleContext(BundleContext bundleContext) {
        this.bundleContext = bundleContext;
    }

    public ConfigurationAdmin getConfigurationAdmin() {
        return configurationAdmin;
    }

    public void setConfigurationAdmin(ConfigurationAdmin configurationAdmin) {
        this.configurationAdmin = configurationAdmin;
    }
}

• Line 11 – This line declares an instance of the Configuration Admin interface as an instance variable that is set using Spring’s auto-wiring.
• Lines 14-23 – These lines query the Configuration Admin service and add the results to the model for rendering.

Deploying in Apache ServiceMix

In order to deploy a WAR using Spring MVC and the Apache JSTL implementation, several additional OSGi bundles must be provisioned in an out-of-the-box ServiceMix instance. The easiest and most repeatable way to provision these bundles is to use a Karaf feature descriptor to describe the bundles to be provisioned. The following feature descriptor snippet illustrates the additional provisioning activities that are needed. The complete feature descriptor can be found in the source code repository.

<?xml version="1.0" encoding="UTF-8"?>
<features name="spring-mvc-smx-${project.version}">
  <feature name="spring-mvc-smx" version="${project.version}">
    <feature>spring</feature>
    <feature>spring-dm</feature>
    <feature>war</feature>

    <bundle>mvn:${project.groupId}/spring-mvc-smx/${project.version}/war</bundle>

    <bundle>mvn:org.springframework.osgi/spring-osgi-web/1.2.0</bundle>
    <bundle>mvn:org.springframework/spring-web/3.0.5.RELEASE</bundle>
    <bundle>mvn:org.springframework/spring-webmvc/3.0.5.RELEASE</bundle>

    <bundle>mvn:javax.servlet/com.springsource.javax.servlet.jsp.jstl/1.2.0.v20110728</bundle>
  </feature>
</features>

• Lines 4-6 – These lines ensure that the core Spring bundles, the core Spring DM bundles, and the PAX Web bundles are provisioned in the container.
• Lines 10-12 – These lines provision the additional Spring DM and Spring MVC bundles required to deploy a WAR using Spring MVC.
• Line 14 – These lines provision the bundle related to the Apache implementation of the JSTL.

Building and Deploying the Example Code

Build Pre-requisites

• Java 1.5+
• Maven 3.0+
• Subversion

Deploy Pre-requisites

• Apache ServiceMix 4.3.0 or Apache ServiceMix 4.5.2

Building

1. For deploying in ServiceMix 4.3, checkout the source code from https://davidvaleri.googlecode.com/svn/projects/examples/spring-mvc-smx/tags/spring-mvc-smx-1.0 using your Subversion client.  For deploying to ServiceMix 4.5.2, checkout the source code from https://davidvaleri.googlecode.com/svn/projects/examples/spring-mvc-smx/tags/spring-mvc-smx-1.1 using your Subversion client.  Note that the code from each tag will likely work with other releases of ServiceMix using the same version of Spring.  See the comments for different user experiences with different releases of ServiceMix.
2. Build the source code by executing the following command from the checkout folder:

   mvn clean install

Deploying

1. Start Apache ServiceMix
2. In the ServiceMix shell, add the feature descriptor for the example application.
   1. Execute the following command on ServiceMix 4.3:

      features:addurl mvn:valeri.blog.examples/spring-mvc-smx/1.0/xml/features

   2. Execute the following command on ServiceMix 4.5.2:

      features:addurl mvn:valeri.blog.examples/spring-mvc-smx/1.1/xml/features

   NOTE: If you did not build the example locally, you will need to add the Maven repository for this blog to the ServiceMix configuration. Edit SERVICEMIX_HOME/etc/org.ops4j.pax.url.mvn.cfg and add http://davidvaleri.googlecode.com/svn/repo/ to the org.ops4j.pax.url.mvn.repositories property.

3. Provision the example WAR by executing the following command in the ServiceMix shell:
   features:install spring-mvc-smx
4. Confirm the installation by executing the following command in the ServiceMix shell:
   osgi:list
5. The output should resemble the following:

   [ 202] [Active ] [ ] [ ] [ 60] David Valeri's Blog :: Examples :: Spring MVC In ServiceMix (1.0.0)
   [ 203] [Active ] [ ] [ ] [ 60] spring-osgi-web (1.2.0)
   [ 204] [Active ] [ ] [ ] [ 60] Spring Web (3.0.5.RELEASE)
   [ 205] [Active ] [ ] [ ] [ 60] Spring Web Servlet (3.0.5.RELEASE)
   [ 206] [Active ] [ ] [ ] [ 60] JavaServer Pages (TM) TagLib API and Implementation (1.2.0.v20110728)

6. Navigate to http://localhost:8181/spring-mvc-smx/ using the browser of your choice.
7. The displayed page contains information retrieved from the OSGi bundle context as well as from an OSGi service retrieved from the OSGi service registry. If you receive an error message or no page is displayed, try refreshing the WAR bundle as it may have loaded before the other newly provisioned bundles. Execute the refresh in the ServiceMix shell using the ID of the bundle with the name “David Valeri’s Blog :: Examples :: Spring MVC In ServiceMix (1.0.0)”. If you still receive an error message, refer to the ServiceMix log files and feel free to post a comment below.