Apache Felix

...

HTTP Service

This is an implementation of the Http HTTP Service Specification as described in chapter 102 of the OSGi Compendium. The goal is to provide a standard and simplified way to register servlets and resources in a Servlet container, and to associate them with URIs. It also implement a non-standard extension for registering servlet filters as well as a whiteboard implementation. Complete set of features:

• Standard Http HTTP Service implementation.
• Extended Http HTTP Service implementation that allows for servlet filter registration.
• Run either with Jetty or inside your own application server using the servlet bridge.
• A whiteboard implementation for easy registration of servlets and filters.
• One complete bundle that includes everything to simplify deployment.

Installing

The Apache Felix Http HTTP Service project includes several bundles.

• org.apache.felix.http.jetty - Http HTTP Service implementation that is embedding Jetty server.
• org.apache.felix.http.whiteboard - Whiteboard implementation that uses any Http HTTP Service implementation.
• org.apache.felix.http.bridge - Http HTTP Service implementation that uses the host applicaiton server (bridged mode). Must be used with proxy.
• org.apache.felix.http.bundle - All in one bundle that includes all of the above.
• org.apache.felix.http.proxy - Proxy that is needed inside WAR when deployed inside an application server.

So, in most cases you could just use org.apache.felix.http.bundle and forget about all the other ones.

Using the HttpService

The main components provided by the Apache Felix Http HTTP Service bundle are:

• HttpService - Service used to dynamically register resources and servlets
• HttpContext - Additional (optional) component to handle authentication, resource and mime type mappings

...

The Servlet alias must begin with a slash and must not end with a slash. When a request is processed, the Http HTTP Service will try to exact match the requested URI with a registered Servlet. If not existent, it will remove the last '/' in the URI and everything that follows, and try to match the remaining part, and so on.

...

public class Activator implements BundleActivator
{
  public void start(BundleContext context) throws Exception 
  {
    ServiceReference sRef = context.getServiceReference(HttpService.class.getName());
    if (sRef != null)
    {
      HttpService service = (HttpService) context.getService(sRef);
      HttpContext myHttpContext = new MyHttpContext());
      service.registerResources("/static", "/etc/www", myHttpContext);
    }
  }
}

Using the ExtHttpService

To be able to register filters, it is possible to get hold of org.apache.felix.http.api.ExtHttpService. This is exported by both jetty and the bridged implementation. Let's see the simplest example of a filter registration.

...

Notice the pattern for filters is using regular expressions. So .* is the same as a simple
* using standard servlet patterns.

Using the Whiteboard

The whiteboard implementation simplifies the task of registering servlets and filters. A servlet (or filter) can be registered by exporting it as a service. The whiteboard implementation detects all javax.servlet.Servlet, javax.servlet.Filter and org.osgi.service.http.HttpContext services with the right service properties. Let us illustrate the usage by registering a servlet:

...

• contextId - Id of context to be referenced by a servlet or filter service.

Using the Servlet Bridge

The servlet bridge is used if you want to use the Http service inside a WAR deployed on a 3rd part applicaiton server. A little setup is needed for this to work:

...

A detailed example can be found here.

Configuration Properties

The service can both be configured using OSGi environment properties and using Configuration Admin. The service PID for this service is "org.apache.felix.http". If you use both methods, Configuration Admin takes precedence. The following properties can be used (some legacy property names still exist but are not documented here on purpose):

...

• org.apache.felix.http.jettyEnabled - True to enable jetty as the http container. The default is false.
• org.apache.felix.http.whiteboardEnabled - True to enable the whiteboard implementation. The default is false.

Examples

A set of simple examples illustrating the various features are available.

• Filter registration sample: http://svn.apache.org/repos/asf/felix/trunk/http/samples/filter/
• Servlet bridge sample: http://svn.apache.org/repos/asf/felix/trunk/http/samples/bridge/
• Whiteboard sample: http://svn.apache.org/repos/asf/felix/trunk/http/samples/whiteboard/

Maven Artifacts

<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.api</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.base</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.bridge</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.bundle</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.jetty</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.proxy</artifactId>
  <version>2.0.2</version>
</dependency>
<dependency>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.http.whiteboard</artifactId>
  <version>2.0.2</version>
</dependency>