The nice thing about JAX-RS is that it offers the abstract “Application” class. So, why not just put your application in the OSGi service registry? That’s very simple and you don’t need to know anything about the JAX-RS implementation. Let someone else worry about how to get the JAX-RS application into the web container at the right place. Here’s how your Application subclass could look like:

public class ContentRepositoryApplication extends Application {

    private static final Set<Class<?>> CLASSES
        = new java.util.HashSet<Class<?>>();

    static {
        CLASSES.add(RootResource.class);
        CLASSES.add(DocumentMetadataResource.class);
        CLASSES.add(DocumentResource.class);
        CLASSES.add(RepositoryResource.class);
        CLASSES.add(URIMessageBodyWriter.class);
    }

    @Override
    public Set<Class<?>> getClasses() {
        return CLASSES;
    }
}

I’d like to demonstrate how to do the publishing part with Jersey (the reference implementation). It’s particularly easy with this one. Actually, I’ve tried and failed with both Apache CXF and Apache Wink (Incubating), probably mostly for lack of in-depth knowledge on how to build a servlet instance from an Application instance.

What we need is simply a ServiceTracker that tracks Application services in the OSGi registry. Whenever a new Application becomes available, build a servlet for it and register that with the OSGi registry. A whiteboard-capable web container can then pick up the servlet and expose it. The code is quite straight-forward:

package ch.jm.rest.jersey;

import java.util.Dictionary;
import java.util.Hashtable;

import javax.servlet.Servlet;
import javax.ws.rs.core.Application;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.framework.ServiceRegistration;
import org.osgi.util.tracker.ServiceTracker;
import org.osgi.util.tracker.ServiceTrackerCustomizer;

import com.sun.jersey.spi.container.servlet.ServletContainer;

/**
 * Bundle activator for the Jersey-based JAX-RS Application deployer. It tracks all JAX-RS
 * {@link Application} services and publishes a servlet for each of them. The "alias" service
 * property is propagated to the servlet service so you can control the endpoint for the JAX-RS
 * service. This follows the whiteboard pattern. Similarly, we publish servlet services
 * in whiteboard style.
 */
public class Activator implements BundleActivator {

    private Log log = LogFactory.getLog(Activator.class);

    private BundleContext context;
    private ServiceTracker tracker;

    /** {@inheritDoc} */
    public void start(BundleContext context) throws Exception {
        this.context = context;

        //Track all JAX-RS Applications
        this.tracker = new ServiceTracker(context,
            Application.class.getName(), new Customizer());
        this.tracker.open();
    }

    /** {@inheritDoc} */
    public void stop(BundleContext context) throws Exception {
        this.tracker.close();
        this.tracker = null;
        this.context = null;
    }

    private class Customizer implements ServiceTrackerCustomizer {

        private Dictionary createProps(ServiceReference reference) {
            String alias = reference.getProperty("alias").toString();
            if (log.isDebugEnabled()) {
                log.debug("Alias: " + alias);
            }

            Dictionary props = new Hashtable();
            props.put("alias", alias);
            return props;
        }

        /** {@inheritDoc} */
        public Object addingService(ServiceReference reference) {
            Application app = (Application)context.getService(reference);
            if (log.isDebugEnabled()) {
                log.debug("Adding JAX-RS application: " + app);
            }

            //For each JAX-RS Application, create a servlet wrapping that Application instance
            ServletContainer servlet = new ServletContainer(app);

            Bundle sourceBundle = reference.getBundle();
            BundleContext sourceContext = sourceBundle.getBundleContext();
            ServiceRegistration reg = sourceContext.registerService(
                    Servlet.class.getName(), servlet, createProps(reference));

            return reg;
        }

        /** {@inheritDoc} */
        public void modifiedService(ServiceReference reference, Object service) {
            ServiceRegistration reg = (ServiceRegistration)service;
            if (log.isDebugEnabled()) {
                log.debug("Modifying JAX-RS application: " + reg);
            }
            reg.setProperties(createProps(reference));
        }

        /** {@inheritDoc} */
        public void removedService(ServiceReference reference, Object service) {
            ServiceRegistration reg = (ServiceRegistration)service;
            if (log.isDebugEnabled()) {
                log.debug("Removing JAX-RS application: " + reg);
            }
            reg.unregister();
            context.ungetService(reference);
        }

    }

}

Please note how the servlet service is published under the BundleContext of the bundle that published the Application service. That’s not really necessary but keeps things in their context.

That’s all I put in that deployer bundle, just this BundleActivator. That already does the whole job in the Jersey case.

This approach may not work for everyone. Like with the whiteboard approach for servlets, there may be some restrictions of what you can do. But so far it has served me well.

One catch I ran into was multipart support. The old story. I was forced to introduce a hard dependency on Jersey’s multipart support in one of my JAX-RS applications. Unfortunately, Jersey Core 1.5 exports the JAX-RS API directly instead of in a separate bundle, and hasn’t assigned versions to exported packages. That would make it difficult to use its multipart support with Apache CXF (it properly imports the JAX-RS API with a version range). Maybe I should look at doing it the other way around (use CXF’s multipart with Jersey). But to deploy the huge CXF package including dependencies just for getting multipart support (as long as I don’t manage to create a JAX-RS servlet) is probably not the best of ideas. BTW, the problem with CXF is that I didn’t find a way to instantiate/configure the servlet without having to rely on web-inf.xml for the initialization parameters. Probably just lack of knowledge. If you have a suggestion, I’m all ears.

I think it would be cool if all JAX-RS implementations that strive to be OSGi-compatible implemented such a whiteboard support for JAX-RS Applications. All you have to do as a user is register your Application object with the OSGi registry. Ideally, you don’t have a dependency on any JAX-RS implementation. I’m still hoping for that multipart support in the next JAX-RS API version.

So, if you produce OSGi bundles using Apache Ant and you’re not quite happy with Bnd or writing bundle metadata by hand, my OSGi Bundle Utility might be something for you. The utility is published under the Apache License v2.0. Source and Binary distributions and documentation is available here.

Hopefully, I’ve followed all the best practice and it is useful to some people. I’ve been using it for over a year now for dozens of bundles and for converting third-party JARs to OSGi bundles. Feedback is welcome!

public interface Greeter {
    void sayHello();
}

Then let’s implement this interface:

public class GreeterImpl implements Greeter {

    private ComponentContext context;

    protected void activate(ComponentContext context) {
        this.context = context;
        System.out.println("Creating new greeter for " + getName()
                + ": " + context.getComponentInstance().toString());
    }

    protected void deactivate(ComponentContext context) {
        System.out.println("Deactivating greeter for " + getName()
                + ": " + context.getComponentInstance().toString());
        this.context = null;
    }

    public void sayHello() {
        System.out.println("Hello, I'm " + getName());
    }

    private String getName() {
        return (String)this.context.getProperties().get("name");
    }

}

Through the activate(ComponentContext) method, we’ll get the component’s configuration once an instance is activated.
Now, we need the component descriptor for our Greeter component (OSGI-INF/component.xml):

<?xml version="1.0" encoding="UTF-8"?>
<component name="demo.scr.componentfactory.greeter">
  <!-- No factory attribute here! -->
  <implementation class="demo.scr.componentfactory.impl.GreeterImpl"/>
  <service>
    <provide interface="demo.scr.componentfactory.Greeter"/>
  </service>
  <property name="service.description"
      value="A nice component that can say hello"/>
</component>

If you know a little bit about Declarative Services, you might at first expect a factory attribute on the component, since we’re going to create multiple instances, but it would really just wrong with the approach I’m showing here. The final missing clue to make this work with multiple configurations lies with the MetaType descriptor we need to build (OSGI-INF/metatype/metatype.xml):

<?xml version="1.0" encoding="UTF-8"?>
<metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.0.0"
    localization="OSGI-INF/metatype/metatype">
  <metatype:OCD id="demo.scr.componentfactory.greeter"
      name="SCR Component Factory Demo">
    <metatype:AD id="name" type="String"
        name="%name.name" description="%name.desc"/>
  </metatype:OCD>
  <metatype:Designate pid="demo.scr.componentfactory.greeter"
      factoryPid="demo.scr.componentfactory.greeter">
    <metatype:Object ocdref="demo.scr.componentfactory.greeter"/>
  </metatype:Designate>
</metatype:MetaData>

Note especially the “Designate” Element which has both a “pid” and a “factoryPid” attribute. The important part is the “factoryPid” attribute which will enable the desired “factory” functionality.
If you want, a properties file with the translations (OSGI-INF/metatype/metatype.properties):

name.name=Name
name.desc=The name. D'oh!

Just for completeness and illustration, here’s the effective bundle manifest:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: DemoScrComponentFactory
Bundle-SymbolicName: demo.scr.componentfactory
Bundle-Version: 1.0.0
Export-Package: demo.scr.componentfactory
Import-Package: org.osgi.framework,
 org.osgi.service.cm,
 org.osgi.service.component,
Service-Component: OSGI-INF/component.xml

If you deploy the resulting bundle in Felix, for example, you should see our new component in the dropdown list of factory configurations on the configuration page of Felix’s WebConsole.
Besides the UI in the WebConsole, you can also use Apache Felix FileInstall’s configuration feature. Just create a properties file (ex. “demo.scr.componentfactory.greeter-C3PO.cfg”) in the directory observed by FileInstall:

name=C3PO, human cyborg relations

Just use the component’s PID followed by a dash and a name of your choosing. You can create as many configuration files as you like. For each one, SCR will create a service for you.

Update, 2010-05-19:
There may be a little problem with the above. If there are no configurations in ConfigurationAdmin, one component instance will still always be activated which may have unwanted side-effects if your component depends on certain values in the configuration. If you experience that, you can switch to the version 1.1 of Declarative Services and use the configuration policy to control this. The following example will require at least one configuration in the ConfigurationAdmin before the component is activated:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
    name="demo.scr.componentfactory.greeter"
    configuration-policy="require">
[..]
</scr:component>