OSGi as a Web Application Server

Did you know that with an OSGi framework and a handful of bundles, you can set up your own light-weight web application server in a matter of minutes?  I will walk you through the process of running the most basic web application server, and then show you how to add serious performance by using the Jetty bundle.

Target Platform

Start by setting up a target platform that contains the Eclipse Equinox OSGi implementation.

1. Open the Preferences
2. Select Plug-in Development -> Target Platform
3. Click Add…
4. Select Nothing: Start with an empty target definition
5. Click Next
6. Name the target
7. Click Add…
8. Select Software Site
9. Click Next
10. Work with: Galileo or Helios (I’m using Helios)
11. Expand EclipseRT Target Platform Components
12. Check Equinox Project SDK
13. Click Finish

You will probably want to grab a quick drink as it will take a few minutes to provision your target platform.  Once your target platform is provisioned, click Finish in the New Target Definition dialog.  When you are taken back to the Preferences dialog, check the target platform you just created (I named mine Equinox) and click OK.

Hello World Servlet

Now that we have our target platform set up, let’s create a simple “Hello World” servlet.  There’s nothing special about the servlet, it’s simply a class that extends HttpServlet as you would expect.  The difference is in the packaging.  The servlet is packaged in an OSGi bundle and deployed as a bundle instead of the typical WAR file.

1. Create a new Plug-in Project
2. Name the project com.example.servlet
3. Click Next
4. Uncheck Generate an activator
5. Uncheck This plug-in will make contributions to the UI
6. Click Finish
7. In the manifest editor, switch to the Dependencies tab
8. Add the following Imported Packages:
   • javax.servlet
   • javax.servlet.http
9. Add the following Required Plugins:
   • org.eclipse.equinox.http.registry
10. Create a package called com.example.servlet
11. Create a new class called HelloWorldServlet
12. Override the doGet() function

/*******************************************************************************
 * Copyright (c) 2010 Bryan Hunt.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Bryan Hunt - initial API and implementation
 *******************************************************************************/

package com.example.servlet;

import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * @author bhunt
 *
 */
public class HelloWorldServlet extends HttpServlet
{
	@Override
	protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException
	{
		PrintWriter out = resp.getWriter();
		out.println("Hello Servlet World");
	}

	private static final long serialVersionUID = -7578840142400570555L;
}

Register the Servlet

Since we are not using a WAR file to deploy our servlet, how do you register the servlet with the container?  The easiest way is with an extension point.  In the manifest editor:

1. Click on the Overview tab
2. Check This plug-in is a singleton
3. Click on the Extensions tab
4. Add the extension point org.eclipse.equinox.http.registry.servlets
5. Set the class to com.example.servlet.HelloWorldServlet
6. Set the alias to /hello

Launch Configuration

The last step is launching our web application.  Let’s launch our application from the workbench using an OSGi launch configuration.

1. From the Run toolbar, select Run Configurations…
2. Select OSGi Framework
3. On the toolbar, click New Launch Configuration
4. Click Deselect All
5. Check the following bundles
   • com.example.servlet
   • javax.servlet
   • org.eclipse.equinox.common
   • org.eclipse.equinox.http
   • org.eclipse.equinox.http.registry
   • org.eclilpse.equinox.registry
   • org.eclipse.osgi
   • org.eclipse.osgi.services
6. Click on the Arguments tab
7. Add the Program argument -console
8. Add the VM argument -Dorg.osgi.service.http.port=8080
9. Click Run

Note that Default Auto-Start is set to true.  If you set it to false, you must Auto-Start the following bundles:

• org.eclipse.equinox.common
• org.eclipse.equinox.http
• org.eclipse.equinox.http.registry
• org.eclipse.osgi

Once the OSGi framework has launched, start up your favorite browser and point it to:  http://localhost:8080/hello and you should see it respond with Hello Servlet World.  If you are running OS X, there’s a simple program called HTTP Client that is nice for playing around with HTTP.

Jetty

The setup I explained above is great for a light-weight, non-performance critical, deployment of an OSGi based web application.  If you are looking for a more robust solution, then I’d recommend switching out the http bundle for the Jetty bundles.  While the http bundle is compatible with Servlet 2.4, there are limitations.  Jetty 7 has full support for Servlet 2.4, and it looks like Jetty 8 will have support for Servlet 3.0.  To switch to Jetty, edit your launch configuration as follows:

• Remove Bundles
  • org.eclipse.equinox.http
• Add Bundles
  • org.eclipse.equinox.http.jetty
  • org.eclipse.equinox.http.servlet
  • org.mortbay.jetty.server
  • org.mortbay.jetty.util

Keep the same arguments as in the http launcher above.  You primarily need to set -Dorg.osgi.service.http.port=8080 otherwise Jetty will  default to port 80 which requires you to run your application as root.

Again, Default Auto-Start is set to true. If you set it to false, you must Auto-Start the following bundles:

• org.eclipse.equinox.common
• org.eclipse.equinox.http.jetty
• org.eclipse.equinox.http.registry
• org.eclipse.osgi

Running OSGi inside a web container

There is another option for running OSGi as a web service.  You can embed OSGi inside a web container like Tomcat using the servlet bridge.  This setup is a bit more complicated and beyond the scope of the blog entry.  If you are interested, please see the following:

• http://www.eclipse.org/equinox/server/http_in_container.php
• http://eclipsesource.com/blogs/2009/08/15/building-your-equinox-based-appserver-part-1/
• http://eclipsesource.com/blogs/2009/08/17/building-your-equinox-appserver-p2/
• http://eclipsesource.com/blogs/2009/08/20/building-your-equinox-osgi-application-server-part-3/

Finally, as I was working on this blog post, Peter Friese wrote up a couple of entries on this topic that you may find interesting:

• http://www.peterfriese.de/osgi-servlets-flexibility-by-simplicity/
• http://www.peterfriese.de/osgi-servlets-deploying-on-amazon-ec2/
• http://www.peterfriese.de/osgi-servlets-a-happy-marriage/

Advertisement