Tuesday, May 22, 2018

OSGi R7 Highlights: The Http Whiteboard Service

The OSGi Compendium Release 7 specification contains version 1.1 of the Http Whiteboard specification which includes a number of new features.

Before we dive into the new features, let's start with a summary of what the Http Whiteboard Specification is about: It provides a light and convenient way of using servlets, servlet filters, listeners and web resources in an OSGi environment through the use of the Whiteboard Pattern. The specification supports registration of the above-mentioned web entities and grouping them together in context. A three-part introduction into the Release 6 version of the Http Whiteboard can be found here, here and here.

Component Property Types

Registering web entities using the Http Whiteboard usually requires specifying several service registration properties. In Release 7, Declarative Services added the ability to use component property types to annotate components and set property values in a type-safe manner. A set of annotations has been added to the Http Whiteboard specification to make use of this new feature in Declarative Services, simplifying the development of such web entities.

For example, registering a servlet at the path /game looks now like this:
@Component(service = Servlet.class)
public class MyServlet extends HttpServlet {

Similarly, defining additional service properties can easily be done by adding more annotations to the class. In the following example, we declare the servlet to support asynchronous processing and mount the servlet in a specific Http Context (in contrast to using the default context as above):
@Component(service = Servlet.class)
  + HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_NAME
  + "=mycontext)")
public class MyServlet extends HttpServlet {

Further annotations have been added to simplify the development of servlet filters, resources, listeners error pages, and servlet context. A full list of these can be found here.

Multipart File Upload

Support for multipart file upload handling and configuring this handling has been added. The possibilities are the same as supported by the servlet specification. The multipart handling can be enabled for a servlet by specifying additional service registration properties. Again, using a component property types simplifies the specification of the required properties. In the following example we enable multipart file upload for the servlet and restrict the size of the uploaded files to 500,000 bytes:
@Component(service = Servlet.class)
public class UploadServlet extends HttpServlet {

The chapter about Multipart File Upload contains a complete description of the service properties for multipart file upload.


A servlet filter is registered with an Http Context together with some rules when the filter is applied, e.g., by specifying a path pattern or a servlet name. However, servlet filters are run after a potential user authentication and therefore never get run when this authentication fails. In addition, these filters are only run if the request is targeting an existing endpoint, either a servlet or a resource.

On the other hand, some use cases require running some code with every request or before authentication. For example, logging all requests, regardless of whether authentication is successful is one of those use cases. Preparing the request by adding additional information from a third party system might be another one.

With the updated Http Whiteboard specification, a new web entity, the Preprocessor has been added. All services registered with this interface are invoked before request dispatching or authentication is performed. Therefore such a preprocessor will receive all requests. The Preprocessor interface is just an extension of the servlet filter interface and just acts as a marker to distinguish a preprocessor from a normal servlet filter. The following example implements a simple preprocessor, logging all requests:
@Component(service = Preprocessor.class)
public class LoggingFilter implements Preprocessor {

  public void doFilter(ServletRequest request,
                       ServletResponse response,
                       FilterChain chain)
  throws IOException, ServletException {
    System.out.println("New request to "
      + ((HttpServletRequest)request).getRequestURI());
    chain.doFilter(request, response);

  public void init(FilterConfig filterConfig)
  throws ServletException {
    // initialize the preprocessor

  public void destroy() {
    // clean up

As a preprocessor is invoked for every request, there are no special service properties for this type of service, especially this service is not associated with any Http Context as the dispatching to a context happens after the preprocessors are invoked.

Updated Security Handling

Security handling or authentication can be implemented by registering your own implementation of the ServletContextHelper service and implementing the handleSecurity method. Web entities like servlets or filters can then be associated with this context ensuring that they are only invoked if the authentication is successful.

While the handleSecurity methods provide a good mechanism to check for authentication and potentially add additional information to the current request like a user context which can then be used by the web components, a method for cleaning up such state was missing. With the update of the Http Whiteboard, a new method finishSecurity has been added which is now closing this gap. This new method is the counterpart of handleSecurity and is invoked when the request processing is done. By implementing this method any resources allocated through handleSecurity can be cleaned up.

More on the Http Whiteboard Update

This blog post mentions only those new features which I think are the most important ones of the new version 1.1. You can find the full list of changes at the end of the Http Whiteboard specification.

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
  4. The JAX-RS Whiteboard
  5. The Converter
  6. Cluster Information
  7. Transaction Control
Be sure to follow us on Twitter or LinkedIn or subscribe to our Blog feed to find out when it's available.

No comments:

Post a Comment