javax.ws.rs.core
Interface ExecutionContext

public interface ExecutionContext

An injectable interface that provides access to asynchronous server side request processing.

The injected execution context instance is bound to the currently processed request and can be used to

• suspend the request processing (with a defined timeout)
• set a default time-out response
• resume the request processing suspended either using this execution context instance or via @Suspend annotation
• cancel the suspended request

TODO example.

Since:

2.0

Author:

Marek Potociar

See Also:

@Suspend

Method Summary

void	cancel() Cancel the request processing.
Response	getResponse() Returns default response to be send back to the client in case the suspended request times out.
void	resume(Exception response) Resume processing of the request bound to the execution context using an exception.
void	resume(Object response) Resume processing of the request bound to the execution context using response data provided.
void	setResponse(Object response) Set the default response to be used in case the suspended request times out.
Future<?>	suspend() Programmatically suspend a request processing without explicitly specifying any timeout.
Future<?>	suspend(long millis) Programmatically suspend a request processing with explicitly specified suspend timeout value in milliseconds.
Future<?>	suspend(long time, TimeUnit unit) Programmatically suspend a request processing with explicitly specified suspend timeout value and its time unit.

Method Detail

resume

void resume(Object response)

Resume processing of the request bound to the execution context using response data provided.

The provided response data can be of any Java type that can be returned from a JAX-RS resource method. The processing of the data by JAX-RS framework follows the same path as it would for the response data returned synchronously by a JAX-RS resource method.

Parameters:

response - data to be sent back in response to the suspended request.

Throws:

IllegalStateException - in case the request has already been resumed or has been canceled previously.

See Also:

resume(java.lang.Exception)

resume

void resume(Exception response)

Resume processing of the request bound to the execution context using an exception.

For the provided exception same rules apply as for the exception thrown by a JAX-RS resource method. The processing of the exception by JAX-RS framework follows the same path as it would for the exception thrown by a JAX-RS resource method.

Parameters:

response - an exception to be raised in response to the suspended request.

Throws:

IllegalStateException - in case the request has already been resumed or has been canceled previously.

See Also:

resume(java.lang.Object)

suspend

Future<?> suspend()

Programmatically suspend a request processing without explicitly specifying any timeout. The method can only be invoked from within the context of a running JAX-RS resource method. Any response value returned from a resource method in which the request processing has been suspended is ignored by the framework.

The effective suspend timeout value is calculated using the following mechanism:

1. Set the effective timeout value to Suspend.NEVER
2. If there is a @Suspend annotation on the enclosing JAX-RS resource method, the effective timeout value is updated to the value of @Suspend.timeOut converted into milliseconds using the value of @Suspend.timeUnit

If the request processing is 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 getResponse() method. Should the getResponse() return null, WebApplicationException is raised with a HTTP 503 error status (Service unavailable). Use setResponse(java.lang.Object) method to customize the default timeout response.

Returns:

handle of the suspended request processing that can be used for querying its current state via one of the Future.isXxx() methods. Invoking any other method on the returned Future instance is not defined and reserved for future extensions of JAX-RS API.

Throws:

IllegalStateException - in case the request has already been suspended, resumed or has been canceled previously.

See Also:

suspend(long), suspend(long, java.util.concurrent.TimeUnit), setResponse(java.lang.Object)

suspend

Future<?> suspend(long millis)

Programmatically suspend a request processing with explicitly specified suspend timeout value in milliseconds. The method can only be invoked from within the context of a running JAX-RS resource method. Any response value returned from a resource method in which the request processing has been suspended is ignored by the framework.

The specified timeout value overrides default timeout value as well as any timeout value specified declaratively for the enclosing resource method.

If the request processing is 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 getResponse() method. Should the getResponse() return null, WebApplicationException is raised with a HTTP 503 error status (Service unavailable). Use setResponse(java.lang.Object) method to customize the default timeout response.

Note that in some concurrent scenarios a call to resume(...) may occur before the call to suspend(...). In which case the call to suspend(...) is ignored. The returned response future will be marked as done.

Parameters:

millis - suspend timeout value in milliseconds.

Returns:

handle of the suspended request processing that can be used for querying its current state via one of the Future.isXxx() methods. Invoking any other method on the returned Future instance is not defined and reserved for future extensions of JAX-RS API.

Throws:

IllegalStateException - in case the request has already been suspended or has been canceled previously.

See Also:

suspend(), suspend(long, java.util.concurrent.TimeUnit), setResponse(java.lang.Object)

suspend

Future<?> suspend(long time,
                  TimeUnit unit)

Programmatically suspend a request processing with explicitly specified suspend timeout value and its time unit. The method can only be invoked from within the context of a running JAX-RS resource method. Any response value returned from a resource method in which the request processing has been suspended is ignored by the framework.

The specified timeout value overrides default timeout value as well as any timeout value specified declaratively for the enclosing resource method.

If the request processing is 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 getResponse() method. Should the getResponse() return null, WebApplicationException is raised with a HTTP 503 error status (Service unavailable). Use setResponse(java.lang.Object) method to customize the default timeout response.

Note that in some concurrent scenarios a call to resume(...) may occur before the call to suspend(...). In which case the call to suspend(...) is ignored. The returned response future will be marked as done.

Parameters:

time - suspend timeout value in the give time unit.

unit - suspend timeout value time unit

Returns:

handle of the suspended request processing that can be used for querying its current state via one of the Future.isXxx() methods. Invoking any other method on the returned Future instance is not defined and reserved for future extensions of JAX-RS API.

Throws:

IllegalStateException - in case the request has already been suspended or has been canceled previously.

See Also:

suspend(), suspend(long, java.util.concurrent.TimeUnit), setResponse(java.lang.Object)

cancel

void cancel()

Cancel the request processing.

This method causes that the underlying network connection is closed without any response being sent back to the client. Invoking this method multiple times has the same effect as invoking it only once. Invoking this method on a request that has already been resumed has no effect and the method call is ignored.

Once the request is canceled, any attempts to suspend or resume the execution context will result in an IllegalStateException being thrown.

setResponse

void setResponse(Object response)

Set the default response to be used in case the suspended request times out.

The provided response data can be of any Java type that can be returned from a JAX-RS resource method. If used, the processing of the data by JAX-RS framework follows the same path as it would for the response data returned synchronously by a JAX-RS resource method.

Parameters:

response - data to be sent back to the client in case the suspended request times out.

See Also:

getResponse()

getResponse

Response getResponse()

Returns default response to be send back to the client in case the suspended request times out. The method may return null if no default response was set in the execution context.

Returns:

default response to be sent back to the client in case the suspended request times out or null if no default response was set.

See Also:

setResponse(java.lang.Object)