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 {@link javax.ws.rs.WebApplicationException}with a {@link javax.ws.rs.core.Response.Status#SERVICE_UNAVAILABLE HTTP 503(Service unavailable)} error response status code. A custom time-out handlermay be {@link AsyncResponse#setTimeoutHandler(TimeoutHandler) set} on anasynchronous 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 {@link AsyncResponse#resume(Object) custom response} or a {@link AsyncResponse#resume(Throwable) custom exception}
- Cancels the response by calling one of the {@link AsyncResponse} {@code cancel(...)}methods.
- Extends the suspend period of the response by {@link AsyncResponse#setTimeout(long,java.util.concurrent.TimeUnit) 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 {@code WebApplicationException} containing the HTTP 503 status code.
Following example illustrates the use of a custom {@code 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); } … }
@author Marek Potociar
@since 2.0