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:

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