Equinox in a Servlet Container

One of the original objectives for the server-side work was to look at what's involved in launching and interacting with various server-side containers. Currently, there is actively maintained work in support of embedding in a servlet container.

Bundles

There are four Eclipse projects involved:

• org.eclipse.equinox.servletbridge
  Launches the framework and provides a place for the framework to hook back into the servlet container.
• org.eclipse.equinox.servletbridge.http
  Hooks back into the servlet bridge and proxies requests through to the servlet container to provide an OSGi Http Service.
• org.eclipse.equinox.http.servlet
  Provides the HttpServiceServlet used by http.servletbridge that when initialized registers an OSGi Http Service.
• [optional] org.eclipse.equinox.http.registry
  Provides servlet, resource, and httpcontext extension points based on an OSGi HttpService.

These four project can be downloaded from the equinox CVS depot.
(e.g. cvsroot/eclipse/org.eclipse.equinox.servletbridge)

To develop web applications you'll also need the javax.servlet bundle from the Orbit CVS depot.
(e.g. cvsroot/tools/org.eclipse.orbit/javax.servlet [branch v2_3 or v2_4])]

[Suggested] If you're using Eclipse it might be far simpler to "import" a team project set with everything needed. (regular) or (proxied)

Additional Notes:

• To build and use these projects you'll need to be running the Eclipse SDK 3.2 or later.

Quickstart

This set of instructions should get you up and running in a just a few minutes.

1. Install a servlet container (e.g. Tomcat, Jetty, or whatever is handy)
2. Download and deploy this pre-built web application archive. (bridge.war) [built 2007.04.02]
3. Start the web container and verify things are installed correctly by going to "/sp_test". (e.g. http://localhost:8080/bridge/sp_test)

At this point you should begin familiarizing yourself with the use of the OSGi console to manage the platform.

Here are a couple of Eclipse projects that might help get you started using the OSGi Http Service:

• sample.http - demonstrates basic Hello World type use of the OSGi Http Service
• sample.http.registry - same as sample.http but instead uses extension points from org.eclipse.equinox.http.registry

You might also see if you can install and start the http-console bundle described here.

Configuration

The servletbridge web.xml provides a couple of initial parameters:

• commandline Allows all non-VM command line parameterizations of Eclipse.
  The default value is "-console" to allow you to use the console to "experiment" with managing an active framework (e.g. installing, starting, stopping, uninstalling bundles etc.). Currently the console is configured to run directly off standard input/output of the launching appserver's process.
• enableFrameworkControls (true / false) - Controls whether or not the sp_* control URLs are accessible
  
  • sp_deploy - Copies the contents of /platform to the install area (the servlet context tempdir is used - parameterizable someday)
  • sp_undeploy - Removes the copy of Eclipse from the install area
  • sp_redeploy - Resets the platform (e.g. stops, undeploys, deploys, starts)
  • sp_start - Starts a deployed platform
  • sp_stop - Stops the platform
  • sp_test - Provides a sanity check and determines if an OSGi based servlet is ready to accept requests
  These commands are available at http://yourhost/yourcontext/sp_command. ( for example, http://localhost/bridge/sp_stop )

Extending

Currently there are two approaches for extending the basic installation:

1. Write a bundle that uses the OSGi HttpService registered by org.eclipse.eqinox.servletbridge.http
2. Write a bundle that adds extensions from org.eclipse.equinox.http.registry

The functionality offered by either approach is very similar. The extension points in org.eclipse.equinox.http.registry are simply a mapping of the OSGi HttpService.

Build Information

The current eclipse build tools and wizards do not directly support building this style of application so for the time being the build is performed with a series of Ant scripts and resource templates

At a high-level the idea is to create a WAR file structured as follows:

• /WEB-INF
  • /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

The above structure is meant to be very close to an RCP application with the /eclipse directory holding something similar to an RCP application (but naturally containing components more suitable for server side interaction).

A reasonable way to think of the build is to divide into two initial pieces:

1. The web-app portion (based on the servletbridge)
2. The eclipse portion

These two pieces should then be combined by placing the eclipse portion in the "/eclipse" directory.

org.eclipse.equinox.servletbridge contains an ant script in "/scripts/webAppBuilder.xml" that can be used from the IDE for constructing the war file structure above. (It can also be used for a head-less build by customizing various properties) Additionally "/tempates" provides the resource content like the web.xml, launch.ini, and config.ini which might also be customized.

To create the WAR file's contents from the Quickstart section:

1. Synch the following project from the equinox-incubator CVS site
   • org.eclipse.equinox.servletbridge.feature
2. Right-Click on the webAppBuilder.xml script in the IDE and "Run Ant".
   (Note: So that the pde.exportFeatures task is available in the IDE select "Run in the same JRE as the workspace" on the JRE tab from "Run Ant..")

As with RCP applications there are a wide variety of possible configurations. What's given in org.eclipse.equinox.servletbridge.feature is just one possibility.