org.glassfish.jersey.process.internal
Class AsyncInflectorAdapter<REQUEST,RESPONSE>

java.lang.Object
  com.google.common.util.concurrent.AbstractFuture<RESPONSE>
      org.glassfish.jersey.process.internal.AsyncInflectorAdapter<REQUEST,RESPONSE>

Type Parameters:

REQUEST - request processing data type.

RESPONSE - response processing data type.

All Implemented Interfaces:

com.google.common.util.concurrent.ListenableFuture<RESPONSE>, ExecutionContext, java.util.concurrent.Future<RESPONSE>, Inflector<REQUEST,com.google.common.util.concurrent.ListenableFuture<RESPONSE>>, ProcessingContext

public abstract class AsyncInflectorAdapter<REQUEST,RESPONSE>
extends com.google.common.util.concurrent.AbstractFuture<RESPONSE>
implements Inflector<REQUEST,com.google.common.util.concurrent.ListenableFuture<RESPONSE>>, ProcessingContext

Suspendable, asynchronous inflector adapter that provides implementation of the request suspend/resume capabilities of the invocation context and returns a listenable response future instead of a plain response object.

Author:

Marek Potociar (marek.potociar at oracle.com)

Nested Class Summary

static interface

AsyncInflectorAdapter.Builder<REQUEST,RESPONSE> Asynchronous inflector adapter factory.

Nested classes/interfaces inherited from interface org.glassfish.jersey.process.internal.ProcessingContext

ProcessingContext.State

Constructor Summary

protected

AsyncInflectorAdapter(Inflector<REQUEST,RESPONSE> wrapped, ProcessingCallback<RESPONSE> callback) Construct and initialize asynchronous inflector adapter for an inflector.

Method Summary

com.google.common.util.concurrent.ListenableFuture<RESPONSE>	apply(REQUEST request) Invoke request on the wrapped inflector.
void	cancel() Cancel the request processing.
protected abstract RESPONSE	convertResponse(REQUEST originatingRequest, Response response) Convert the JAX-RS response to supported response data type.
Response	getResponse() Returns default response to be send back to the client in case the suspended request times out.
protected void	interruptTask()
boolean	isSuspended() Returns true if this execution context has been suspended and has not {finished processing yet.
void	resume(java.lang.Object response) Resume processing of the request bound to the execution context using response data provided.
void	resume(java.lang.Throwable response) Resume processing of the request bound to the execution context using a throwable.
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.
ProcessingContext.State	state() Get the current state of the processing context.
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.
java.lang.String	toString()
boolean	trySuspend() Try to suspend the current request processing.

Methods inherited from class com.google.common.util.concurrent.AbstractFuture

addListener, cancel, get, get, isCancelled, isDone, set, setException

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface deprecated.javax.ws.rs.ExecutionContext

isCancelled, isDone

Constructor Detail

AsyncInflectorAdapter

protected AsyncInflectorAdapter(Inflector<REQUEST,RESPONSE> wrapped,
                                ProcessingCallback<RESPONSE> callback)

Construct and initialize asynchronous inflector adapter for an inflector.

Parameters:

wrapped - wrapped inflector.

callback - invocation callback.

Method Detail

apply

public com.google.common.util.concurrent.ListenableFuture<RESPONSE> apply(REQUEST request)

Invoke request on the wrapped inflector. The adapter itself serves as a listenable response future.

Specified by:

apply in interface Inflector<REQUEST,com.google.common.util.concurrent.ListenableFuture<RESPONSE>>

Parameters:

request - request data to be processed.

Returns:

data transformation result. Return value must not be null.

state

public ProcessingContext.State state()

Description copied from interface: ProcessingContext

Get the current state of the processing context.

Specified by:

state in interface ProcessingContext

Returns:

current state of the processing context.

resume

public void resume(java.lang.Object response)

Description copied from interface: ExecutionContext

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.

Specified by:

resume in interface ExecutionContext

Parameters:

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

See Also:

ExecutionContext.resume(java.lang.Throwable)

resume

public void resume(java.lang.Throwable response)
            throws java.lang.IllegalStateException

Description copied from interface: ExecutionContext

Resume processing of the request bound to the execution context using a throwable. For the provided throwable same rules apply as for an exception thrown by a JAX-RS resource method. The processing of the throwable by JAX-RS framework follows the same path as it would for any exception thrown by a JAX-RS resource method.

Specified by:

resume in interface ExecutionContext

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:

ExecutionContext.resume(java.lang.Object)

setSuspendTimeout

public void setSuspendTimeout(long time,
                              java.util.concurrent.TimeUnit unit)

Description copied from interface: ExecutionContext

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.

Specified by:

setSuspendTimeout in interface ExecutionContext

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.

trySuspend

public boolean trySuspend()

Description copied from interface: ProcessingContext

Try to suspend the current request processing. Unlike the suspend() method, this method does not throw an exception in case the suspend operation fails. Instead, the method returns true if the request processing has been suspended successfully, returns false otherwise.

Specified by:

trySuspend in interface ProcessingContext

Returns:

true if the request processing has been suspended successfully, returns false otherwise.

suspend

public void suspend()

Description copied from interface: ExecutionContext

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 ExecutionContext.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.

Specified by:

suspend in interface ExecutionContext

See Also:

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

suspend

public void suspend(long millis)

Description copied from interface: ExecutionContext

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 ExecutionContext.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 ExecutionContext.getResponse() method. Should the getResponse() return null, WebApplicationException is raised with a HTTP 503 error status (Service unavailable). Use ExecutionContext.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.

Specified by:

suspend in interface ExecutionContext

Parameters:

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

See Also:

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

suspend

public void suspend(long time,
                    java.util.concurrent.TimeUnit unit)

Description copied from interface: ExecutionContext

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 ExecutionContext.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 ExecutionContext.getResponse() method. Should the getResponse() return null, WebApplicationException is raised with a HTTP 503 error status (Service unavailable). Use ExecutionContext.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.

Specified by:

suspend in interface ExecutionContext

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

See Also:

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

cancel

public void cancel()

Description copied from interface: ExecutionContext

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.

Specified by:

cancel in interface ExecutionContext

isSuspended

public boolean isSuspended()

Description copied from interface: ExecutionContext

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

Specified by:

isSuspended in interface ExecutionContext

Returns:

true if this task was canceled before it completed.

See Also:

ExecutionContext.isCancelled(), ExecutionContext.isDone()

interruptTask

protected void interruptTask()

Overrides:

interruptTask in class com.google.common.util.concurrent.AbstractFuture<RESPONSE>

setResponse

public void setResponse(java.lang.Object response)

Description copied from interface: ExecutionContext

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.

Specified by:

setResponse in interface ExecutionContext

Parameters:

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

See Also:

ExecutionContext.getResponse()

getResponse

public Response getResponse()

Description copied from interface: ExecutionContext

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.

Specified by:

getResponse in interface ExecutionContext

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:

ExecutionContext.setResponse(java.lang.Object)

convertResponse

protected abstract RESPONSE convertResponse(REQUEST originatingRequest,
                                            Response response)

Convert the JAX-RS response to supported response data type.

Parameters:

originatingRequest - originating request data.

response - JAX-RS response.

Returns:

JAX-RS response converted to supported response data type.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object