Asynchronous API

Introduction

Initially, the Restlet API was fully synchronous, blocking a thread during the whole call processing. The Restlet edition for GWT however had to work in an asynchronous way due to the constraints of AJAX. The goal is to move towards a unified API properly supporting asynchronous call processing.

These specifications are related to the internal NIO connectors introduced at the end of version 2.0 development cycle and described in this other specification document. It is also leveraged by the new SIP effort described here.

Requirements

High priorities

• [143] Support asynchronous processing
• [862] Add callback per request
• Asynchronous representation writing (preventing the blocking of thread)

Medium priorities

• Allow asynchronous responses to go through the Restlet filters
• Handle the call processing flow without the Java stack
• [825] Add Comet support
• [939] Support call monitoring

References

• Wikipedia - Reactor pattern
• Node.js - About

Analysis

Lifecycle of a HTTP call

On the client-side

1. Send this request : call Uniform#handle(Request, Response)
2. My request headers have been sent
3. My request entity is about to be sent : ConnectorService#beforeSend(Representation)
4. My request entity was fully sent : ConnectorService#afterSend(Representation)
5. My request was fully sent, including its entity
6. The response to my request has just arrived, at least its headers : Uniform#handle(Request, Response) returns
7. The response was fully read : Representation fully processed
8. My request was aborted by the server

On the server-side

1. A request has just arrived, at least its headers : Uniform#handle(Request, Response) is called
2. The request has been processed and the response is ready : Uniform#handle(Request, Response) returns
3. My response headers have been sent
4. My response entity is about to be sent : ConnectorService#beforeSend(Representation)
5. My response entity was fully sent : ConnectorService#afterSend(Representation)
6. My response was fully sent, including its entity
7. The request was aborted by the client

Design

Restlet API changes

• Request#onResponse : Uniform, called back when the response has been received, at least its headers
• Message#onSent : Uniform, called back when the message is fully sent
• Message#abort() method to prematurely end the sending of a request or a response
• Response#autoCommitting : boolean, indicates if the response should be written with the current status
• Response#commit() : triggers the sending of a provisional or final response (new separate Response instances)
• Representation#write(WritableByteChannel, Result<Integer>) : asynchronous write leveraging non-blocking NIO if possible