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

    Methods
    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.

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.