javax.ws.rs
Annotation Type Suspend

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Documented
public @interface Suspend

Marks a request processed by the @Suspend-annotated JAX-RS resource method for suspending. Suspended request processing can be resumed using an injectable ExecutionContext instance bound to the processed request:

 @Path("/messages/next")
 public class SimpleAsyncEventResource {
     private static final BlockingQueue<ExecutionContext> suspended = new ArrayBlockingQueue<ExecutionContext>(5);
     @Context ExecutionContext ctx;

     @GET
     @Suspend
     public void pickUpMessage() throws InterruptedException {
         suspended.put(ctx);
     }

     @POST
     public String postMessage(final String message) throws InterruptedException {
         suspended.take().resume(message);
         return "Message sent";
     }
 }
 

Using @Suspend on a resource method is equivalent to calling ExecutionContext.suspend() as the first step upon entering the method. Typically resource method annotated with @Suspend annotation declare void return type, but it is not a hard requirement to do so. Any response value returned from the @Suspend-annotated resource method is ignored by the framework:

 @Path("/messages/next")
 public class SimpleAsyncEventResource {
     …
     @GET
     @Suspend
     public String pickUpMessage() throws InterruptedException {
         suspended.put(ctx);
         return "This response will be ignored.";
     }
     …
 }
 

By default there is no suspend timeout set and request processing is suspended indefinitely. The suspend timeout can be specified using the annotation values. Declaratively specified timeout can be further overridden using one of the suspend(...) methods in the ExecutionContext programmatic API.

If the request processing was suspended with a positive timeout value, the processing will be resumed once the specified timeout threshold is reached provided the request processing was not explicitly resumed before the suspending has expired. The request processing will be resumed using response data returned by the associated ExecutionContext.getResponse() method. Should the method return null, a WebApplicationException is raised with a HTTP 503 error status (Service unavailable). Use ExecutionContext.setResponse(java.lang.Object) method to programmatically customize the default timeout response.

The annotation is ignored if it is used on any method other than JAX-RS resource method.

Since:

2.0

Author:

Marek Potociar

Optional Element Summary

long	timeOut Suspend timeout value in the given time unit.
java.util.concurrent.TimeUnit	timeUnit The suspend timeout time unit.

timeOut

public abstract long timeOut

Suspend timeout value in the given time unit. A default value is no timeout.

Default:

0L

timeUnit

public abstract java.util.concurrent.TimeUnit timeUnit

The suspend timeout time unit. Defaults to TimeUnit.MILLISECONDS.

Default:

java.util.concurrent.TimeUnit.MILLISECONDS