javax.ws.rs.container

Interface TimeoutHandler

public interface TimeoutHandler

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 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);
     }
     …
 }
 

Since:

2.0

Author:

Marek Potociar

Method Summary

Modifier and Type	Method and Description
void	handleTimeout(AsyncResponse asyncResponse) Invoked when the suspended asynchronous response is about to time out.

Method Detail

handleTimeout

void handleTimeout(AsyncResponse asyncResponse)

Invoked when the suspended asynchronous response is about to time out. Implementing time-out handlers may use the callback method to change the default time-out strategy defined by JAX-RS specification (see AsyncResponse API documentation).

A custom time-out handler may decide to either

• resume the suspended response using one of it's resume(...) methods,
• cancel the suspended response using one of it's cancel(...) methods, or
• extend the suspend period by setting a new suspend time-out

In case the time-out handler does not take any of the actions mentioned above, a default time-out strategy is executed by the JAX-RS runtime.

Parameters:

asyncResponse - suspended asynchronous response that is timing out.