javax.ws.rs
Annotation Type Suspend

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

Automatically suspend the request processing executioncontext for the invoked JAX-RS resource or sub-resource method. A suspended request processing can be programmatically resumed using an injectable ExecutionContext instance bound to request being processed:

 @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 {
         final ExecutionContext getRequestCtx = suspended.take();
         getRequestCtx.resume(message); // resumes the processing of one GET request
         return "Message sent";
     }
 }
 

Placing @Suspend annotation on a resource method is equivalent to calling ExecutionContext.suspend() as the first step upon entering the method. This also means that any subsequent programmatic invocation of a ExecutionContext.suspend(...) methods is illegal in the context of a method suspended via @Suspend annotation. 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 programmatically overridden using the ExecutionContext.setSuspendTimeout(long, TimeUnit) method.

If the request processing was suspended with a positive timeout value, and has not been explicitly resumed before the timeout has expired, the processing will be resumed once the specified timeout threshold is reached. 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 or sub-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. Similarly, any explicitly set value lower then or equal to zero will be treated as a "no timeout" value.

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