servletbridge-felix

A ServletBridge based on Apache Felix and Apache Felix Webconsole to use an embedded OSGi container within a Web ARchive.

Motivation

When searching the web for an OSGi servletbridge implementation you will eventually get to https://felix.apache.org/documentation/subprojects/apache-felix-http-service.html#using-the-servlet-bridge. When taking a look at the Felix example project mentioned on this website you will possibly notice that the Felix version in question is quite old. I searched the web high and low to find an up2date project that is using newer versions but could not fine one. Therefore I decided to come up with my own project that will take care of this.

Build & Installation

The installation is based on Apache Maven and should work just out of the box. All dependencies are proper OSGi bundles, with the exception of org.json and the asm libraries. Two wrapper projects take care of the transformation into OSGi bundles so no manual work has to be done here. Based on your requirements you can now create either a minimal or an extended version of the servletbridge.

Simple version

The simple version only contains the mandatory bundles to run a servletbridge with webconsole support. To create such a servletbridge just clone the project and navigate to the parent folder. Next run mvn clean install from the command line. This will create and fetch all the required artifacts to get a working war file. The following screenshot shows the webconsole with all installed bundles.

Extended version

The extended version does not only provide webconsole support but also comes with additional OSGi bundles/services and webconsole plugins. To create the extended servletbridge navigate to the parent folder and run mvn clean install -Pextended in the command line. As a result you will get a war file that contains all the bundles shown in the following screenshot.

Automated deployment to Apache Tomcat 7

To ease the development and testing it is possible to automatically deploy the created servletbridge to a Apache Tomcat 7.x instance. A few changes are necessary to get this automatic deployment working.

Modify settings.xml

Add a server definition to your settings.xml and change the username and password accordingly.

<servers>
    <server>
        <id>TomcatServer</id>
        <username>tomcat</username>
        <password>tomcat</password>
    </server>
</servers>

Modify the tomcat-users.xml

Add the following roles and user definition to the tomcat-users.xml of your Tomcat installation (feel free to skip the obsolete roles).

<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users>
  <role rolename="admin"/>
	<role rolename="manager"/>
	<role rolename="manager-gui"/>
	<role rolename="manager-script"/>
	<role rolename="manager-jmx"/>
	<role rolename="manager-status"/>
	<user password="tomcat" roles="manager-gui,manager-script" username="tomcat"/>
</tomcat-users>

Modify the Maven goals

Depending on whether you want to deploy, redeploy or undeploy the servletbridge take one of the following goals.

Deploy servletbridge

This goal must only be used to initially deploy the servletbridge to Tomcat. Once a servletbridge has already been deployed to Tomcat this goal does not do anything anymore.

Simple: mvn clean install tomcat7:deploy -DtomcatHost=localhost:8080

Extended: mvn clean install tomcat7:deploy -DtomcatHost=localhost:8080 -Pextended

Redeploy servletbridge

Once a servletbridge artefact has already been deployed to Tomcat you must use this goal to redeploy any changes.

Simple: mvn clean install tomcat7:redeploy -DtomcatHost=localhost:8080

Extended: mvn clean install tomcat7:redeploy -DtomcatHost=localhost:8080 -Pextended

Undeploy servletbridge

If you want to undeploy the servletbridge from your Tomcat instance take this goal.

Simple: mvn clean install tomcat7:undeploy -DtomcatHost=localhost:8080

Extended: mvn clean install tomcat7:undeploy -DtomcatHost=localhost:8080 -Pextended