Asynchronous response suspend time-out handler. JAX-RS users may utilize this callback interface to provide custom resolution of time-out events.

By default, JAX-RS runtime generates a javax.ws.rs.WebApplicationException with a HTTP 503 (Service unavailable) error response status code. A custom time-out handler may be set on an asynchronous response instance to provide custom time-out event resolution.

In case of a suspend time-out event, a custom time-out handler takes typically one of the following actions:

• Resumes the suspended asynchronous response using a custom response or a custom exception
• Cancels the response by calling one of the AsyncResponse cancel(...) methods.
• Extends the suspend period of the response by setting a new suspend time-out

If the registered time-out handler does not take any of the actions above, the default time-out event processing continues and the response is resumed with a generated WebApplicationException containing the HTTP 503 status code.

Following example illustrates the use of a custom TimeoutHandler:

public class MyTimeoutHandler implements TimeoutHandler {
    …
    public void handleTimeout(AsyncResponse ar) {
        if (keepSuspended) {
            ar.setTimeout(10, SECONDS);
        } else if (cancel) {
            ar.cancel(retryPeriod);
        } else {
            ar.resume(defaultResponse);
        }
    }
    …
}

@Path("/messages/next")
public class MessagingResource {
    …
    @GET
    public void readMessage(@Suspended AsyncResponse ar) {
        ar.setTimeoutHandler(new MyTimeoutHandler());
        suspended.put(ar);
    }
    …
}