OSGi Equinox in a Servlet Container [step1]

In [step0], I have introduced the capability to use OSGi bundles in WEB Application with Server-Side Equinox which works with 2 means :

• Embedding an HTTP server in Equinox :

  OSGi container -> HTTP Server (bundle) -> WEB Application (bundle).

• Equinox in a Servlet Container :

  HTTP Server -> WEB Application -> OSGi container.

Those articles will speak about Equinox in a Servlet Container which provides a bridge.war WEB application to start using Equinox in a Servlet Container and a basic OSGi bundle sample.http, example which provides as an OSGi service an HTTP Servlet.

• When OSGi bundle sample.http is started, the servlet http://localhost:8080/bridge/helloworld is available :
  
• When OSGi bundle sample.http is stopped, the servlet http://localhost:8080/bridge/helloworld is NOT available :
  

This sample show you it’s possible to available/disable a servlet WITHOUT stopping the HTTP server. In this article I will explain step by step how use bridge.war and show in action the using of sample.http. Steps of this article will be :

• create an empty bridge WEB Application with WTP Dynamic Web Project to launch the WEB application with Run As->Run on server. Tomcat 6.0 server will be used in this article.
• copy the content of the bridge.war to the empty bridge WEB Application (WTP Dynamic Web Project) and launch it.
• install and use the OSGi bundle sample.http.

This article introduce just the features of the bridge.war but will not explain the bridge architecture and will not explain the code of the sample.http. I will do that in the next article [step2].

Prerequisites

Before starting read this article, you must :

• install Eclipse IDE for Java EE Developers distribution to use WTP to configure and launch Tomcat 6.0 server. In this article I have used Helios (Eclipse 3.6) version. You can download it at Eclipse download.
• install Tomcat 6.0. But another Tomcat version will works or even any HTTP server (JBoss Application Server, Jetty…) can be used. In this article I have used Tomcat 6.0 that I have installed with Eclipse JEE (WTP).

Download

You can download servletbridge_step1.zip which contains following explained projects :

• brige which is a « Dynamic Web Project » of the the original bridge.war. It contains too the JAR sample.http.
• sample.http : eclipse bundle OSGi project of the original sample.http.
• Servers which contains the configuration of the Tomcat 6.0 which was generated with WTP.

How test servletbridge*.zip immediately?

If you wish test immediately projects coming from servletbridge_step1.zip, unzip it in a folder. Start Eclipse and choose this folder as workspace.

Go at menu File/Import… and select General/Existing Projects into Workspace :

Select with Browse… button your workspace folder, projects must appears :

Click on Finish button, your workspace looks like this :

bridge project has Compilation problem if your Tomcat Apache 6.0 Server is not defined. If your server is already installed, select bridge project and go at menu Run As->Run on Server to select your server, otherwise Define an New Server.

Why Equinox in a Servlet Container?

Why I have chosen Equinox in a Servlet Container although
Embedding an HTTP server in Equinox is recommended?

The answer is the server choice. Indeed Embedding an HTTP server in Equinox require that the server is an OSGi bundle (it exists some distribution of the Tomcat, Jetty… which are an OSGi bundle). The server choice is a big problem when you are working for a big customer, who use often a big (and complex) server like WAS, Weblogic…(I know that WAS 7.0 use internally OSGi but I don’t know if it’s possible to use it for the WEB Application which wish use OSGi bundles).

With Equinox in a Servlet Container, it’s the WEB Application which host and start the OSGi container. This solution works with any HTTP server.

If server choice is not a problem, it’s recommended to use Embedding an HTTP server in Equinox because you can for instance benefit with PDE tool (ex : check if your OSGi launch is valid).

Initialize empty Bridge WEB application with WTP

Here we will transform the bridge.war into a WTP Dynamic Web Project.

Create Dynamic Web Project

In this section we create empty bridge WEB application with Dynamic Web Project. To do that go at menu File/New /Dynamic Web Project :

New Dynamic Web Project wizard opens. Fill project name with bridge and select Target runtime with your Server. If no server is defined, click on New Runtime… button to define it.

Define New Server

Click on New Runtime… button, open the wizard to create server. Select Tomcat 6.0 server :

Click on Next button, the wizard page display the selection of the Tomcat directory (existing Tomcat or empty folder where Tomcat must be installed).
In my case I install Tomcat with WTP, to do that select an existing empty folder with Browse… Button where tomcat must be installed. In my case I have selected the existing empty folder D:\Server\apache-tomcat-6.0.26 :

You can notice the error message « Tomcat installation directory is not valid » in the wizard page. Click on Download and Install button, accept the license and validate the existing empty folder. A background job process to download and install Tomcat. Once the install is finished the error message about « Tomcat installation directory is not valid » must disappear and Finish button is enable.

New Dynamic Web Project configurated

Click on Finish button, the New Dynamic Web Project wizard page appears :

Fileds of this wizard are pre-filled like 2.5 Dynamic Module Web version which means that Tomcat 6.0 support 2.5 servlet. Click on Finish Button, the empty bridge WEB application is generated :

Launch Empty Bridge WEB application

No you can start the Tomcat server and launching the empty bridge WEB Application. Select the bridge project, click on right mouse and select menu Run As->Run on Server

This action opens the wizard to select the server :

Select Tomcat 6.0 server and click on Finish button. This action create a Server folder in your workspace which is the configuration of your Tomcat and launch the bridge WEB Application.

You can notice you will have a 404 error because the web.xml generated is like this :

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>bridge</display-name>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>default.html</welcome-file>
    <welcome-file>default.htm</welcome-file>
    <welcome-file>default.jsp</welcome-file>
  </welcome-file-list>
</web-app>

And your web application contains no such files.

Install/Start bridge.war

Now we have an empty bridge WEB Application that we can start with a server, we can use the bridge.war from Equinox in a Servlet Container. To do that, download bridge.war, unzip it and copy paste the WEB-INF folder from the bridge.war to the WEB-INF of the Dynamic Web Project bridge. Your workspace looks like this :

You can notice WEB-INF contains several folder/files :

• /web.xml (with one servlet entry assigning all incoming requests to the BridgeServlet).
• /lib/servletbridge.jar (the classes associated with the equinox.servletbridge)
• /eclipse (the eclipse platform directory) :
  • launch.ini (contains framework properties that will allow override of any eclipse specific System Properties)
  • /configuration (contains config.ini which lists the bundles you want to have available)
  • /features
  • /plugins which contains several JAR which are OSGi bundles (Equinox OSGi container, Equinox Server side…)

  Stop and restart your server with Server View :

  

  If you go at Console View, you will notice some log of Tomcat and the prompt >osgi :

  

  The prompt >osgi means that OSGi console is launched. If you don »t know OSGi console, I suggest you read Explore Eclipse’s OSGi console. This console is useful to manage (install/start/stop) OSGi bundles. If you type in the console view the command (Short Status) :

  ss

  and key on enter, the console display :

  Framework is launched.

  id State Bundle
0 ACTIVE org.eclipse.osgi_3.3.0.200704022148
Fragments=10
1 ACTIVE org.eclipse.equinox.common_3.3.0.200704022148
2 ACTIVE org.eclipse.update.configurator_3.2.100.v20070322
3 ACTIVE org.eclipse.equinox.http.servletbridge_1.0.0.200704022148
4 ACTIVE org.eclipse.equinox.http.registry_1.0.0.200704022148
8 ACTIVE org.eclipse.equinox.http.servlet_1.0.0.200704022148
9 ACTIVE org.eclipse.equinox.registry_3.3.0.v20070318
10 RESOLVED org.eclipse.equinox.servletbridge.extensionbundle_1.0.0
Master=0
11 RESOLVED org.eclipse.osgi.services_3.1.100.200704022148


  This OSGi console display the whole OSGi bundles installed. Those OSGi bundles comes from the WEB-INF/eclipse/plugins. You can notice that OSGi bundles are ACTIVE state. We will see how start/stop the bundles in the next section.

  Check bridge installation

  To verify things are installed correctly go at http://localhost:8080/bridge/sp_test, your page must display :

  

  The message :

  Servlet delegate registered - org.eclipse.equinox.http.servlet.HttpServiceServlet

  means that bridge WEB Application is installed correctly.

  Install sample.http

  Bridge WEB Application launch the OSGi Equinox Container (we will see how it works it next article [step2]). That’s cool, but what is this? Equinox in a Servlet Container provides a basic sample called sample.http which is an OSGi bundle which give an access of a Servlet with the URL http://localhost:8080/bridge/helloworld.

  Donwload the sample.http, unzip it in your workspace and import it from your Eclipse workspace. Your workspace looks like this :

  

  Create and deploy sample.http_1.0.0.jar

  To use this OSGi bundle, you must create a JAR and copy/paste it in the WEB-INF/eclipse/plugins folder. To do that you can :

  • use the webAppBuilder.xml ANT script (never used).
  • build the JAR with Eclipse PDE Tool.

  We will create the JAR with Eclipse (PDE tools). To do that, select the sample.http project and go at the menu File/Export…. The Export wizard opens. Select Plug-in Development/Deployable plug-ins and fragment node :

  

  Select the bundle sample.http (1.0.0) and select directory WORKSPACE_LOC/bridge/WebContent/WEB-INF/eclipse where WORKSPACE_LOC is your workspace directory. You will notice that it’s NOT WORKSPACE_LOC/bridge/WebContent/WEB-INF/eclipse/plugins (with /plugins folder) which is selected, because PDE Tools generate this folder.

  

  Click on Finish button, refresh the /plugins folder from the bridge Dynamic Web Project, and sample.http_1.0.0.jar must appear :

  

  start/stop sample.http

  Restart your server and type in the console View

  ss

  The OSGi console display the Short Status of the bundles installed :

  
...
19 RESOLVED sample.http_1.0.0

  You will notice sample.http is deployed but with RESOLVED state. The first column of the console OSGi of the Short Status display an identifier for each OSGi bundles installed. In my case, sample.http is linked to the 19 identifier. This identifier can be used to install/uninstall/start/stop bundles with OSGi console. Now we start the OSGi bundle sample.http. To do that, get the identifier of the sample.http (in my case 19) and type :

  start 19

  If you display the Short Status with command :

  ss

  the state of the sample.http is ACTIVE:

  
19 ACTIVE sample.http_1.0.0

  Go at http://localhost:8080/bridge/helloworld and you will see that /helloworld Servlet is available :

  

  Stop the sample.http with command :

  stop 19

  Go at http://localhost:8080/bridge/helloworld : and you will have a 404 error.

  

  Modify config.ini

  At this step, when the bridge WEB application is launched, the bundle sample.http has RESOLVED sate and not ACTIVE state. So we need to start the sample.http with OSGi console to available /helloword Servlet. It’s possible to start it, when bridge WEB application is launched. To do that, we must modify the WEB-INF/eclipse/configuration/config.ini by adding the sample.http in the osgi.bundles property like this :

  osgi.bundles=...,sample.http@start

  Here the full osgi.bundles property :

  osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@start, org.eclipse.equinox.http.servletbridge@start, org.eclipse.equinox.http.registry@start,sample.http@start

  The @start means that the bundle sample.http must be started when OSGi container is started.

  Before try this feature, I advice to start your server, go at http://localhost:8080/bridge/sp_redeploy to clean the /eclipse folder deployed. Stop your server and restart it.

  If you display the Short Status with command :

  ss

  you will notice that the state of the sample.http is ACTIVE:

  
19 ACTIVE sample.http_1.0.0

  sample.http is started.

  The config.ini must be modified ONLY when bundles must be added (to start it). I advice to do http://localhost:8080/bridge/sp_redeploy + stop server + restart server when you modify it.

  Control the Framework with URL /sp_*

  Bridge WEB Application provides several URL which start with /sp_* to control the Framework :

  • /sp_deploy (http://localhost:8080/bridge/sp_deploy) – Copies the contents of /platform to the install area (the servlet context tempdir is used – parameterizable someday).
  • /sp_undeploy (http://localhost:8080/bridge/sp_undeploy) – Removes the copy of Eclipse from the install area.
  • /sp_redeploy (http://localhost:8080/bridge/sp_redeploy) – Resets the platform (e.g. stops, undeploys, deploys, starts).
  • /sp_start (http://localhost:8080/bridge/sp_start) – Starts a deployed platform.
  • /sp_stop (http://localhost:8080/bridge/sp_stop) – Stops the platform.
  • /sp_test (http://localhost:8080/bridge/sp_test) – Provides a sanity check and determines if an OSGi based servlet is ready to accept requests.

  Conclusion

  In this article we explained how use the bridge.war from the Equinox in a Servlet Container and show it in action with sample.http OSGi bundle. sample.http give you the capability to available/disable a servlet WITHOUT stopping the HTTP server. This feature is very interesting :

  • In development mode, you start ONCE time your server and you develop your bundle (ex : sample.http). When you want test it, you stop/restart your bundle. This feature is very interesting when your server take a long time to start (this case comes from often when you develop a big WEB application).
  • In production mode, you can easily available/disable some Servlet WITHOUT stopping the server. This feature is very interesting when you fix a problem with a bundle :
    • No need to build and provides a big WAR/EAR which fix the problem.
    • No need to stop the server to install the bundles patched. The bundle patched can be provided and started to fix the problem WITHOUT stopping the server.

  In the next article [step2], I will explain more how bridge WEB application works (explains the content of the web.xml which use BridgeServlet) and explains how sample.http works.