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

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