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!

I had started a new job back then which began with a project that should format invoices from the health sector to PostScript and print them on large-scale printers including automatic packaging. And for that XSL-FO looked like the right technology, but FOP had to learn how to use fonts other than the base 14 set (Helvetica, Times, Courier, Symbol and ZapfDingbats). Finishing some work started by someone else, my first contribution was initial support for custom Type 1 fonts.

Today, I’m probably the FOP contributor with the longest service record in the project.

I went through the hype phase (2001-2003) as well as the difficult time of the redesign after the famous 0.20.5 release which saw an almost complete exchange of the project team between 2003 and 2005. From 2005 on, we worked towards a stable FOP again that quickly surpassed the old 0.20.5 release for which soon there was almost no expertise around anymore. It’s unbelievable how many people still use 0.20.5 and say “we can’t upgrade”. Many of the problems they have are simply solved in the current release. Anyway, since this year’s 1.0 release, FOP finally doesn’t carry that undeserved taint of an 0.x software anymore. It was just a version number but not an indicator of FOP’s production readiness. The initial goal of a complete implementation of the XSL 1.0 standard was just unrealistic. There’s not even one commercial implementation on the market which achieved that goal. Many people came and went during all that time. FOP is what it is today through contributions from all of them.

Lately, AFP is a big topic where FOP took big leaps forward in the last 2-3 years. Color is also becoming more and more important as color printing gets cheaper and transpromo is gaining interest. Even in today’s world the number of pages printed still increases every year. Apache FOP is well positioned to cover the printed document as well as the electronic document. XSL is an established and accepted technology today. And Apache FOP is often the “entry drug” for people who start XSL. Many stay with it producing millions of pages each year. During the stagnation of the redesign phase, some FOP users turned to commercial implementations like RenderX or AntennaHouse. After 2005 I saw many switch back again after the major improvements because some of the commercial implementations couldn’t offer much more but had a higher TCO depending on the use case or because they offered unsatisfactory support and couldn’t influence the development direction enough. Apache FOP might face some difficult time ahead since the layout engine (the core) didn’t see considerable development lately. Some features like table markers, flow maps and auto-table layout would do FOP some good but it won’t be easy to implement.

Between 2000 and 2003, Apache FOP was part of my job and quickly became a hobby, too. I’ve developed Barcode4J (an open source barcode generator) during that time which plugs nicely into FOP. From 2004 to 2005, FOP was just a hobby as I worked part-time for a small company maintaining a model-driven application framework. In 2005 I went freelance offering commercial support, consulting and development services around Apache FOP. At times, FOP created up to 90% of my income. I did not get rich, of course, but the fun counts, too. It wasn’t always fun. Heated arguments over mostly non-features nibbled at my motivation which triggered me to reduce my involvement in FOP a bit. This year was dominated by two interesting projects that involved producing full-color PDFs, both Web-to-Print. One is Swiss Post’s DirectFactory, a web plattform where you can design and send postcards (or even chocolate wrappers now). The other was for a company that produces photo books, calendars and other gifts from within the browser. That finally got me back to a user role a bit. Before that I basically just hacked FOP without really using it myself. It’s interesting how the perspective shifts again when switching back to the user side. This is particularly important to me now that the EUR, GBP and USD are very weak against the CHF. My commercial support business gets increasingly more difficult because most of my clients are located outside Switzerland. And that means I have to shift my main focus to domestic clients but without leaving my past clients in a void.

I’d like to note something interesting in that context: In all my freelancer time since 2005, I’ve never picked up the phone to look around for projects. I was lucky that they always found me, often even at the right times. A large part of it, I’m sure, is my presence on the Apache FOP Users Mailing List. By answering questions, people recognize a recurring name at some point. When some users run into a problem they can’t solve easily, they often turn to me for a higher service level than is possible on the users mailing list. That said, I believe there is room for a good developer to get challenging tasks as part of a commercial support service for Apache FOP, especially if he’s not afraid of the complicated topic of paper layout and he’s not located in Switzerland which is currently just too expensive due to the currency weaknesses. Such an additional resource would be good for FOP.

Last year, I’ve started to develop an output management server which uses Apache FOP as its main formatter. Although a minimal version is now live working nicely for the DirectFactory, it turned out to be too big an endeavour for a one-man show besides end-user projects and the FOP commercial support. So I’ll be investing in a smaller product first that hopefully will create a little multiplicator for me which commercial support services simply can’t provide. To wrap up this admittedly lengthy post, I need to say that Open Source is a very important topic for me. When done right, it is such an effective way to pool resources and to create high-quality software. Getting rich with it (not that I need to be) is difficult, so the right way is probably somewhere in between commercial and open source products. My wish is that more users of Open Source software think about contributing something back to the many products they use. There are various ways to do that. Too often, people treat OSS as freeware which it simply isn’t.

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>

Thanks to Jürgen for pointing this out to me!

I must say: it was simply fun to work with this setup. DocBook is well documented. The documentation always had an option for all of my wishes. No wasted time, no crashes, no despair (I pity those who do this with MS Word). I can only recommend to do any larger documentation work like this.

• JVM Classpath on Windows (semicolon): “-cp my1.jar;my2.jar”
• JVM Classpath on Unix (colon): “-cp my1.jar:my2.jar”
• Class-Path entry in a JAR manifest (space): “Class-Path: my1.jar my2.jar”
• OSGi’s Bundle-Classpath entry in a bundle manifest (comma): “Bundle-Classpath: .,META-INF/lib/my1.jar,META-INF/lib/my2.jar”

I’m sure someone will eventually come up with yet another separator for classpath entries.

This will make especially ODFDOM interesting for Apache FOP.  One of the missing puzzle pieces in FOP surely is an ODF output plug-in to replace the RTF format in the long run. Somehow I’ve got the feeling that we won’t have to wait all too long for that…

There’s also a detailed list of changes for this release.