AsyncWeb Service API Overview

The class diagram below shows the three main interfaces you will be working with if you write asyncWeb services:

HttpRequest / HttpResponse

Represent HTTP requests and responses. No methods invoked on either an HttpRequest or an HttpResponse are blocking. In particular, any methods invoked on the the streams returned by HttpRequest#getInputStream() and HttpResponse#getOutputStream() are guaranteed never to block.
Notice how a response is committed to a request using HttpRequest#commitResponse(HttpResponse). Committing a response to a request triggers the response for that request to be sent back down the wire.

HttpService

Represents a service which handles incoming HttpRequests - associating them with an HttpResponse as it becomes available. A response may (and typically should) be committed to a request after the frameworks call in to HttpService#handleRequest returns.
That is - a service may (and is encouraged to) process incoming requests in a non-blocking fashion.