Over the past year I’ve developed a goal of making it easier to build and deploy the Equinox runtime as a web application server. Not only does this fit my technical skills having previously worked on a commercial application server, it also fits my technical interests. It also seems that an ever increasing set of other people have been interested in running the Equinox OSGi runtime as a application server. Furthermore, many people may not be aware that there are now a number of really excellent technologies available via the EclipseRT project that are relevant to creating modern application servers:
There’s a lot more to come, for example, ECF’s work on supporting Google Wave server protocol as well as commercial technologies from EclipseSource and other technology companies devoted to the OSGi stackless stack.
However, in my opinion it’s far more difficult to build, deploy, configure and run an Equinox server than it should be. There is existing documentation on doing so from scratch here, but it is a little dated. I am contributing to the Equinox project to get the documentation updated with community help.
So, I would like to do a short set of blogs about building your own Equinox-based application server. Hopefully this will be helpful to those who are interested. It’s possible to create two ‘kinds’ of Equinox-based application servers. Those that are actually run stand-alone (i.e., as a Equinox OSGi application) or those that are run within an existing servlet container such as Jetty or most commercial application servers. For this series, I’m going to focus on the servlet container method as I think this will ultimately be the more common and popular method. Furthermore, servlet containers now make deployment, installation and configuration very easy (which goes a long way toward my goal).
Ok, so how to create an Equinox-based application server? Well, with the Eclipse Galileo PDE build, p2, features, and products, it turns out it’s now very easy to do so (compliments to the particularly to the folks who worked on PDE, Equinox, and P2 in this area). I’ve created a simple feature and product that does so and contributed them to this bug. Here are the steps:
1) Download the zip attached to bug 245267
2) In Eclipse, open a new workspace and import the projects from the downloaded zip (File->Import…->Existing Projects in Workspace->Select Archive File). This will put two very small projects into your workspace

3) There are two other projects (from Equinox CVS area) required before you can create your app server. To add these projects right click on the equinox-servletbridge.psf file and select Import Project Set… from the menu (use anonymous CVS login when prompted). Now you should have four projects in the workspace

4) Now, open the PDE product editor by double clicking on equinox-milli.product file
5) Select Eclipse product export link in lower right of product editor

6) In the export wizard dialog set the following fields
a) The Root Directory field must be set to: WEB-INF
b) The Synchronize before exporting check box can be unchecked
c) The Destination must be set to Archive file, and given a location/name of your choosing (e.g. myappserver.zip)
d) The Generate metadata repository should be checked (to include p2 metadata)

e) Click Finish
This will run PDE build and create a zip named (in the above case): myappserver.zip
6) Now comes the fun part. Simply rename this zip file to a .war…i.e. myappserver.war
7) Start your servlet container (in this case I’m using tomcat)

Hot deploy the war file (in this case myappserver.war) in the manner appropriate for your servlet container (in tomcat’s case this is copying the myappserver.war file into the webapps directory). After a few seconds, you should see something like the following output to the tomcat console…with the nice little osgi> prompt, indicating your Equinox server is deployed and running!

9) Give some OSGi console commands with the osgi> prompt just to convince yourself everything is working…e.g.

10) Go show your colleagues how easy it was to create, deploy and run your Equinox application server!
There’s a lot more that you can now do with your Equinox application server like:
- Adding servlets (via bundles)
- Using P2 to update your application server
- Creating your web applications in a modular fashion using bundles and features
- Reuse your favorite bundles from Eclipse or other projects
- Deploy and maintain your web application as bundles (and using PDE to do it)
In the future, I’ll describe how to do some of these things.
If people are interested in particular things to do, please comment and let me know.
Tags: ecf, equinox, OSGi, p2, rap