javax.ws.rs.container

Annotation Type Suspended

@Target(value=PARAMETER)
@Retention(value=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