microBean™ Jersey Netty Integration

The microBean™ Jersey Netty Integration project integrates Jersey into Netty in an idiomatic way.

Jersey can be run as a simple handler of sorts in a Netty pipeline. The Netty event loop remains unblocked, there is no locking, reads and writes involve minimal copying of byte arrays, output is streamed where appropriate and it is intended that there be as few object allocations as possible.

HTTP 1.1 and HTTP/2 are both supported, including upgrades via HTTP's upgrade header, ALPN or prior knowledge.

Status

This project uses semantic versioning. It is still in an alpha state.

Installation

Add a dependency on this project in your Netty-based Maven project:

<dependency>
  <groupId>org.microbean</groupId>
  <artifactId>microbean-jersey-netty</artifactId>
  <!-- Always check
  https://search.maven.org/classic/#search%7Cgav%7C1%7Cg%3A%22org.microbean%22%20AND%20a%3A%22microbean-jersey-netty%22
  for the latest available version. -->
  <version>0.25.1</version>
</dependency>

Usage

To use, install an instance of JerseyChannelInitializer as the child handler of a Netty ServerBootstrap:

serverBootstrap.childHandler(new JerseyChannelInitializer(baseUri, // e.g. URI.create("/")
    sslContext, // an SslContext, or null if you don't want TLS support
    true, // yes, HTTP/2 support please
    20971520L, // 20MB maximum incoming payload (arbitrary)
    new DefaultEventExecutorGroup(8), // a DefaultEventExecutorGroup with 8 threads (arbitrary) to run your application
    true, // yes, use Jersey's native dependency injection facilities
    new ApplicationHandler(yourJaxRsApplication), // the ApplicationHandler wrapping your application
    8192, // write in 8K chunks (arbitrary)
    Unpooled::new /* how to create those chunks */));

Background and Motivation

While Jersey itself contains a Netty integration project, it is annotated with @Beta, and the author additionally writes that his "implementation cannot be more experimental". In addition, there are several issues with the Jersey-supplied Netty integration project. The most problematic seems to be issue 3500. This issue and others stem from the fact that the Jersey-supplied Netty integration project sets up its own internal queues for streaming, which overflow. Additionally, new ByteBuffers and InputStreams are allocated throughout. It is also not entirely clear if HTTP/2 is fully supported.

Recently, there have been some efforts to improve this area, but they still do not take advantage of the built in queuing and threading constructs offered up by Netty itself.

Implementation Details

By contrast, microBean™ Jersey Netty Integration approaches the problem of running a Jakarta RESTful Web Services application under Netty by following the spirit of Netty.

Several composable channel pipeline components are provided.

Considering HTTP 1.1 support, the first is a decoder that decodes HttpRequest and HttpContent messages into ContainerRequest objects, which are the objects consumed natively by Jersey.

A ContainerRequest may need an entity stream, and that can be tricky. Since a Jakarta RESTful Web Services application may block whatever thread it is running on for some time (for example, perhaps it is performing synchronous database access over a slow connection), then normally it should be run on its own thread that is not the Netty event loop. But assuming that this is so, the InputStream it will receive by way of a ContainerRequest's entity stream will now be operated on by two threads: the application-hosting thread, and the Netty event loop. microBean™ Jersey Netty Integration ensures that this InputStream implementation is thread-safe, uses as few locks as possible, allocates as little memory as possible, and takes advantage of CompositeByteBuf and other Netty native constructs to ensure this inter-thread messaging is safe and efficient.

Similarly, a ContainerRequest needs a ContainerResponseWriter which is responsible for actually writing the Jakarta RESTful Web Services application's output. microBean™ Jersey Netty Integration provides a ContainerResponseWriter implementation that is also a ChannelInboundHandlerAdapter: it takes ContainerRequests as input, installs itself as their ContainerResponseWriter implementation, and writes the requisite output back to the channel safely and efficiently.

The OutputStream implementation used to do this must, of course, ensure that writes take place on the Netty event loop. microBean™ Jersey Netty Integration ensures that this OutputStream implementation does not needlessly buffer and/or copy byte arrays but instead takes advantage of the built-in outbound event queuing present in the Netty event loop itself.

Similar constructs are provided for HTTP/2 support as well.