Annotation Type Suspended


  • @Target(PARAMETER)
    @Retention(RUNTIME)
    @Documented
    public @interface Suspended
    Inject a suspended AsyncResponse into a parameter of an invoked JAX-RS resource or sub-resource method. The injected AsyncResponse instance is bound to the processing of the active request and can be used to resume the request processing when a response is available.

    By default there is no suspend timeout set and the asynchronous response is suspended indefinitely. The suspend timeout as well as a custom timeout handler can be specified programmatically using the AsyncResponse.setTimeout(long, TimeUnit) and AsyncResponse.setTimeoutHandler(TimeoutHandler) methods. For example:

      @Stateless
      @Path("/")
      public class MyEjbResource {
        …
        @GET
        @Asynchronous
        public void longRunningOperation(@Suspended AsyncResponse ar) {
          ar.setTimeoutHandler(customHandler);
          ar.setTimeout(10, TimeUnit.SECONDS);
          final String result = executeLongRunningOperation();
          ar.resume(result);
        }
    
        private String executeLongRunningOperation() { … }
      }
     

    A resource or sub-resource method that injects a suspended instance of an AsyncResponse using the @Suspended annotation is expected be declared to return void type. Methods that inject asynchronous response instance using the @Suspended annotation and declare a return type other than void MUST be detected by the JAX-RS runtime and a warning message MUST be logged. Any response value returned from such resource or sub-resource method MUST be ignored by the framework:

     @Path("/messages/next")
     public class MessagingResource {
         …
         @GET
         public String readMessage(@Suspended AsyncResponse ar) {
             suspended.put(ar);
             return "This response will be ignored.";
         }
         …
     }
     
    Since:
    2.0
    Author:
    Marek Potociar