OSGi R7 Highlights: The JAX-RS Whiteboard

OSGi R7 is more than just an update to the existing OSGi specifications, it also includes a host of new specification chapters adding modularity to Java technologies. Today I want to tell you about about the exciting new support for RESTful services using the JAX-RS Whiteboard specification.

OSGi has long offered support for the web using Servlets, but these can be cumbersome for creating modern APIs which may need to represent data in a variety of ways. JAX-RS streamlines these sorts of applications by separating the routing of requests and serialization of entities from the business logic of your application.

JAX-RS: The Basics

A JAX-RS application uses resources to handle incoming requests. The method used to handle an incoming request is determined using annotations.

public class Upper {
  @Path("rest/upper/{param}")
  @GET
  public String toUpper(@PathParam("param") String param) {
    return param.toUpperCase();
  }
}

JAX-RS resources are then grouped together (along with extension services) in an Application which is hosted by the server runtime. This model is very similar to that used by Servlets in a WAR file, and so unsurprisingly the best way to use JAX-RS resources in an OSGi framework is very similar to the way you would use a Servlet!

The JAX-RS Whiteboard

When in an OSGi framework, we want our applications to be modular and loosely coupled. The best way to contribute a JAX-RS resource is therefore to register it as a service with the JAX-RS whiteboard. Using the new Declarative Services Component Property Types makes this really easy!

@Component(service=Upper.class)
@JaxrsResource
public class Upper {
    @Path("rest/upper/{param}")
    @GET
    public String toUpper(@PathParam("param") String param) {
        return param.toUpperCase();
    }
}

Note that JAX-RS doesn't impose any type restrictions on the resource object, so the whiteboard doesn't either. Any service registered with the "osgi.jaxrs.resource" property set to true (provided here by the @JaxrsResource component property type) will therefore be picked up by the whiteboard and used as a resource.

In addition to individual resources the whiteboard can also host entire JAX-RS Application instances:

@Component(service=Application.class)
@JaxrsApplicationBase("myApp")
public class MyApp extends Application {
    ...
}

These applications are isolated from one another, allowing multiple bundles to contribute RESTful APIs without fear of conflict.

Extending the JAX-RS Whiteboard

A key feature of the JAX-RS model is its extensibility. Support for new media types, content encodings, custom exception mapping and many other facilities are provided using extension types. These extension types are also supported by the JAX-RS whiteboard and can be registered just as easily as any other types!

@Component
@JaxrsExtension
@Produces("application/vnd.acme.foo")
public class MyExt implements MessageBodyReader,
                              MessageBodyWriter {
   ...
}

In summary

The JAX-RS whiteboard offers a powerful, flexible, easy-to-use model for creating RESTful APIs for your OSGi bundles. The Reference Implementation at Apache Aries is available now for you to try out, and there are examples for developing JAX-RS whiteboard applications at OSGi enRoute. More information (and a lot of additional features) are described in the R7 specification. Have Fun!

---

Want to find out more about OSGi R7?

This is one post in a series of 12 focused on OSGi R7 Highlights.  Previous posts are:

1. Proposed Final Draft Now Available
2. Java 9 Support
3. Declarative Services

Coming up next is The JAX-RS Whiteboard. Be sure to follow us on Twitter or LinkedIn or subscribe to our Blog feed to find out when its available.