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

For an example usage of ExecutionContext kindly consult the @Suspend annotation API documentation.

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.
boolean	isCancelled() Returns true if this execution context was canceled before it completed normally.
boolean	isDone() Returns true if this execution context has finished processing.
boolean	isSuspended() Returns true if this execution context has been suspended and has not {finished processing yet.
void	resume(java.lang.Exception response) Resume processing of the request bound to the execution context using an exception.
void	resume(java.lang.Object response) Resume processing of the request bound to the execution context using response data provided.
void	setResponse(java.lang.Object response) Set the default response to be used in case the suspended request times out.
void	setSuspendTimeout(long time, java.util.concurrent.TimeUnit unit) Set the new suspend timeout.
void	suspend() Programmatically suspend a request processing without explicitly specifying any timeout.
void	suspend(long millis) Programmatically suspend a request processing with explicitly specified suspend timeout value in milliseconds.
void	suspend(long time, java.util.concurrent.TimeUnit unit) Programmatically suspend a request processing with explicitly specified suspend timeout value and its time unit.

Method Detail

resume

void resume(java.lang.Object response)
            throws java.lang.IllegalStateException

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:

java.lang.IllegalStateException - in case the request has not been suspended.

See Also:

resume(java.lang.Exception)

resume

void resume(java.lang.Exception response)
            throws java.lang.IllegalStateException

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:

java.lang.IllegalStateException - in case the request has not been suspended.

See Also:

resume(java.lang.Object)

suspend

void suspend()
             throws java.lang.IllegalStateException

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 that has not been previously suspended either programmatically using one of the suspend(...) methods on this execution context instance or declaratively by placing a @Suspend annotation on the JAX-RS resource or sub-resource method associated with the current request processing execution context.

While the execution context is still suspended, the suspend timeout value may be updated using the setSuspendTimeout(long, TimeUnit) method.

Any response value returned from the resource method in which the request processing has been suspended is ignored by the framework.

Throws:

java.lang.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), setSuspendTimeout(long, TimeUnit), setResponse(java.lang.Object)

suspend

void suspend(long millis)
             throws java.lang.IllegalStateException

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 that has not been previously suspended either programmatically using one of the suspend(...) methods on this execution context instance or declaratively by placing a @Suspend annotation on the JAX-RS resource or sub-resource method associated with the current request processing execution context.

The specified timeout value overrides the default no timeout value. While the execution context is still suspended, the suspend timeout value may be updated using the setSuspendTimeout(long, TimeUnit) 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 suspend operation has timed-out. A timed-out request processing will be resumed using response 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.

Parameters:

millis - suspend timeout value in milliseconds. Value lower or equal to 0 causes the context to suspend indefinitely.

Throws:

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

See Also:

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

suspend

void suspend(long time,
             java.util.concurrent.TimeUnit unit)
             throws java.lang.IllegalStateException

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 that has not been previously suspended either programmatically using one of the suspend(...) methods on this execution context instance or declaratively by placing a @Suspend annotation on the JAX-RS resource or sub-resource method associated with the current request processing execution context.

The specified timeout value overrides the default no timeout value. While the execution context is still suspended, the suspend timeout value may be updated using the setSuspendTimeout(long, TimeUnit) 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 suspend operation has timed-out. A timed-out request processing will be resumed using response 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.

Parameters:

time - suspend timeout value in the give time unit. Value lower or equal to 0 causes the context to suspend indefinitely.

unit - suspend timeout value time unit

Throws:

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

See Also:

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

setSuspendTimeout

void setSuspendTimeout(long time,
                       java.util.concurrent.TimeUnit unit)
                       throws java.lang.IllegalStateException

Set the new suspend timeout. The new suspend timeout values override any timeout value specified either programmatically via one of the suspend(...) methods or declaratively. The execution context must be suspended for this method to succeed.

Parameters:

time - suspend timeout value in the give time unit. Value lower or equal to 0 causes the context to suspend indefinitely.

unit - suspend timeout value time unit.

Throws:

java.lang.IllegalStateException - in case the context has not been suspended.

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.

isSuspended

boolean isSuspended()

Returns true if this execution context has been suspended and has not {finished processing yet.

Returns:

true if this task was canceled before it completed.

See Also:

isCancelled(), isDone()

isCancelled

boolean isCancelled()

Returns true if this execution context was canceled before it completed normally.

Returns:

true if this task was canceled before it completed.

See Also:

isSuspended(), isDone()

isDone

boolean isDone()

Returns true if this execution context has finished processing. Completion may be due to normal termination, a suspend timeout, or cancellation -- in all of these cases, this method will return true.

Returns:

true if this execution context has finished processing.

See Also:

isSuspended(), isCancelled()

setResponse

void setResponse(java.lang.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)