org.eclipse.jetty.server
Class AsyncContinuation

java.lang.Object
  org.eclipse.jetty.server.AsyncContinuation

All Implemented Interfaces:

Continuation, AsyncContext

public class AsyncContinuation
extends Object
implements AsyncContext, Continuation

Implementation of Continuation and AsyncContext interfaces.

Nested Class Summary

class

AsyncContinuation.AsyncEventState

Field Summary

protected HttpConnection

_connection

Fields inherited from interface org.eclipse.jetty.server.AsyncContext

ASYNC_CONTEXT_PATH, ASYNC_PATH_INFO, ASYNC_QUERY_STRING, ASYNC_REQUEST_URI, ASYNC_SERVLET_PATH

Fields inherited from interface org.eclipse.jetty.continuation.Continuation

ATTRIBUTE

Constructor Summary

protected

AsyncContinuation()

Method Summary

void	addContinuationListener(ContinuationListener listener) Add a ContinuationListener.
void	cancel()
protected void	cancelTimeout()
void	complete() Complete a suspended request.
void	dispatch()
void	dispatch(ServletContext context, String path)
void	dispatch(String path)
protected void	doComplete()
protected void	expired()
AsyncContinuation.AsyncEventState	getAsyncEventState()
long	getAsyncTimeout()
Object	getAttribute(String name) Get a request attribute.
ContextHandler	getContextHandler()
String	getHistory()
ServletRequest	getRequest()
ServletResponse	getResponse()
ServletResponse	getServletResponse() Get the suspended response.
String	getStatusString()
protected boolean	handling()
boolean	hasOriginalRequestAndResponse()
boolean	isAsync()
boolean	isAsyncStarted()
boolean	isComplete()
boolean	isCompleting()
boolean	isExpired()
boolean	isInitial()
boolean	isResponseWrapped() Is the suspended response wrapped.
boolean	isResumed()
boolean	isSuspended()
protected void	recycle()
void	removeAttribute(String name) Remove a request attribute.
void	resume() Resume a suspended request.
protected void	scheduleDispatch()
protected void	scheduleTimeout()
void	setAsyncTimeout(long ms)
void	setAttribute(String name, Object attribute) Set a request attribute.
protected void	setConnection(HttpConnection connection)
void	setTimeout(long timeoutMs) Set the continuation timeout.
void	start(Runnable run)
void	suspend() Suspend the processing of the request and associated ServletResponse.
protected void	suspend(ServletContext context, ServletRequest request, ServletResponse response)
void	suspend(ServletResponse response) Suspend the processing of the request and associated ServletResponse.
String	toString()
void	undispatch() Undispatch the request.
protected boolean	unhandle() Signal that the HttpConnection has finished handling the request.

Methods inherited from class java.lang.Object

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

Field Detail

_connection

protected HttpConnection _connection

Constructor Detail

AsyncContinuation

protected AsyncContinuation()

Method Detail

setConnection

protected void setConnection(HttpConnection connection)

addContinuationListener

public void addContinuationListener(ContinuationListener listener)

Description copied from interface: Continuation

Add a ContinuationListener.

Specified by:

addContinuationListener in interface Continuation

setAsyncTimeout

public void setAsyncTimeout(long ms)

getAsyncTimeout

public long getAsyncTimeout()

getAsyncEventState

public AsyncContinuation.AsyncEventState getAsyncEventState()

isResponseWrapped

public boolean isResponseWrapped()

Description copied from interface: Continuation

Is the suspended response wrapped.

Filters that wrap the response object should check this method to determine if they should destroy/finish the wrapped response. If the request was suspended with a call to Continuation.suspend(ServletResponse) that passed the wrapped response, then the filter should register a ContinuationListener to destroy/finish the wrapped response during a call to ContinuationListener.onComplete(Continuation).

Specified by:

isResponseWrapped in interface Continuation

Returns:

True if Continuation.suspend(ServletResponse) has been passed a ServletResponseWrapper instance.

See Also:

Continuation.isResponseWrapped()

isInitial

public boolean isInitial()

Specified by:

isInitial in interface Continuation

Returns:

true while the request is within the initial dispatch to the filter chain and/or servlet. Will return false once the calling thread has returned to the container after suspend has been called and during any subsequent redispatch.

isSuspended

public boolean isSuspended()

Specified by:

isSuspended in interface Continuation

Returns:

true after #suspend(long) has been called and before the request has been redispatched due to being resumed, completed or timed out.

toString

public String toString()

Overrides:

toString in class Object

getStatusString

public String getStatusString()

handling

protected boolean handling()

suspend

protected void suspend(ServletContext context,
                       ServletRequest request,
                       ServletResponse response)

unhandle

protected boolean unhandle()

Signal that the HttpConnection has finished handling the request. For blocking connectors, this call may block if the request has been suspended (startAsync called).

Returns:

true if handling is complete, false if the request should be handled again (eg because of a resume that happened before unhandle was called)

dispatch

public void dispatch()

Specified by:

dispatch in interface AsyncContext

expired

protected void expired()

complete

public void complete()

Description copied from interface: Continuation

Complete a suspended request.

This method can be called by any thread that has been passed a reference to a suspended request. When a request is completed, the associated response object commited and flushed. The request is not redispatched.

If complete is called before a suspended request is returned to the container (ie the thread that called #suspend(long) is still within the filter chain and/or servlet service method), then the complete does not take effect until the call to the filter chain and/or servlet returns to the container. In this case both Continuation.isSuspended() and Continuation.isResumed() return true.

Typically resume() is used after a call to Continuation.suspend(ServletResponse) with a possibly wrapped response. The async handler should use the response provided by Continuation.getServletResponse() to write the response before calling Continuation.complete(). If the request was suspended with a call to Continuation.suspend() then no response object will be available via Continuation.getServletResponse().

Once complete has been called and any thread calling the filter chain and/or servlet chain has returned to the container, the request lifecycle is complete. The container is able to recycle request objects, so it is not valid hold a request or continuation reference after the end of the life cycle.

Specified by:

complete in interface Continuation

Specified by:

complete in interface AsyncContext

See Also:

#suspend()}

doComplete

protected void doComplete()

recycle

protected void recycle()

cancel

public void cancel()

scheduleDispatch

protected void scheduleDispatch()

scheduleTimeout

protected void scheduleTimeout()

cancelTimeout

protected void cancelTimeout()

isCompleting

public boolean isCompleting()

isComplete

public boolean isComplete()

isAsyncStarted

public boolean isAsyncStarted()

isAsync

public boolean isAsync()

dispatch

public void dispatch(ServletContext context,
                     String path)

Specified by:

dispatch in interface AsyncContext

dispatch

public void dispatch(String path)

Specified by:

dispatch in interface AsyncContext

getRequest

public ServletRequest getRequest()

Specified by:

getRequest in interface AsyncContext

getResponse

public ServletResponse getResponse()

Specified by:

getResponse in interface AsyncContext

start

public void start(Runnable run)

Specified by:

start in interface AsyncContext

hasOriginalRequestAndResponse

public boolean hasOriginalRequestAndResponse()

Specified by:

hasOriginalRequestAndResponse in interface AsyncContext

getContextHandler

public ContextHandler getContextHandler()

isResumed

public boolean isResumed()

Specified by:

isResumed in interface Continuation

Returns:

true if the request has been redispatched by a call to Continuation.resume(). Returns false after any subsequent call to suspend

See Also:

Continuation.isResumed()

isExpired

public boolean isExpired()

Specified by:

isExpired in interface Continuation

Returns:

true after a request has been redispatched as the result of a timeout. Returns false after any subsequent call to suspend.

See Also:

Continuation.isExpired()

resume

public void resume()

Description copied from interface: Continuation

Resume a suspended request.

This method can be called by any thread that has been passed a reference to a continuation. When called the request is redispatched to the normal filter chain and servlet processing with Continuation.isInitial() false.

If resume is called before a suspended request is returned to the container (ie the thread that called #suspend(long) is still within the filter chain and/or servlet service method), then the resume does not take effect until the call to the filter chain and/or servlet returns to the container. In this case both Continuation.isSuspended() and Continuation.isResumed() return true. Multiple calls to resume are ignored.

Typically resume() is used after a call to Continuation.suspend() with no arguments. The dispatch after a resume call will use the original request and response objects, even if Continuation.suspend(ServletResponse) had been passed a wrapped response.

Specified by:

resume in interface Continuation

See Also:

Continuation.resume()

setTimeout

public void setTimeout(long timeoutMs)

Description copied from interface: Continuation

Set the continuation timeout.

Specified by:

setTimeout in interface Continuation

Parameters:

timeoutMs - The time in milliseconds to wait before expiring this continuation after a call to Continuation.suspend() or Continuation.suspend(ServletResponse)

See Also:

Continuation#suspend(long)

suspend

public void suspend(ServletResponse response)

Description copied from interface: Continuation

Suspend the processing of the request and associated ServletResponse.

After this method has been called, the lifecycle of the request will be extended beyond the return to the container from the Servlet.service(ServletRequest, ServletResponse) method and Filter.doFilter(ServletRequest, ServletResponse, FilterChain) calls. When a suspended request is returned to the container after a dispatch, then the container will not commit the associated response (unless an exception other than ContinuationThrowable is thrown).

When the thread calling the filter chain and/or servlet has returned to the container with a suspended request, the thread is freed for other tasks and the request is held until either:

• a call to ServletRequest#resume().
• a call to ServletRequest#complete().
• the timeout expires.

Typically suspend with a response argument is uses when a call to Continuation.complete() is expected. If a call to Continuation.resume() is expected, then the Continuation.suspend() method should be used instead of this method.

Filters that may wrap the response object should check Continuation.isResponseWrapped() to decide if they should destroy/finish the wrapper. If Continuation.isResponseWrapped() returns true, then the wrapped request has been passed to the asynchronous handler and the wrapper should not be destroyed/finished until after a call to Continuation.complete() (potentially using a ContinuationListener.onComplete(Continuation) listener).

Specified by:

suspend in interface Continuation

Parameters:

response - The response to return via a call to Continuation.getServletResponse()

See Also:

Continuation.suspend()

suspend

public void suspend()

Description copied from interface: Continuation

Suspend the processing of the request and associated ServletResponse.

After this method has been called, the lifecycle of the request will be extended beyond the return to the container from the Servlet.service(ServletRequest, ServletResponse) method and Filter.doFilter(ServletRequest, ServletResponse, FilterChain) calls. When a suspended request is returned to the container after a dispatch, then the container will not commit the associated response (unless an exception other than ContinuationThrowable is thrown).

When the thread calling the filter chain and/or servlet has returned to the container with a suspended request, the thread is freed for other tasks and the request is held until either:

• a call to ServletRequest#resume().
• a call to ServletRequest#complete().
• the timeout expires.

Typically suspend with no arguments is uses when a call to Continuation.resume() is expected. If a call to Continuation.complete() is expected, then the Continuation.suspend(ServletResponse) method should be used instead of this method.

Specified by:

suspend in interface Continuation

See Also:

Continuation.suspend()

getServletResponse

public ServletResponse getServletResponse()

Description copied from interface: Continuation

Get the suspended response.

Specified by:

getServletResponse in interface Continuation

Returns:

the ServletResponse passed to Continuation.suspend(ServletResponse).

See Also:

Continuation.getServletResponse()

getAttribute

public Object getAttribute(String name)

Description copied from interface: Continuation

Get a request attribute. This method is a convenience method to call the ServletRequest.getAttribute(String) method on the associated request object. This is a thread safe call and may be called by any thread.

Specified by:

getAttribute in interface Continuation

Parameters:

name - the attribute name

Returns:

the attribute value

See Also:

Continuation.getAttribute(java.lang.String)

removeAttribute

public void removeAttribute(String name)

Description copied from interface: Continuation

Remove a request attribute. This method is a convenience method to call the ServletRequest.removeAttribute(String) method on the associated request object. This is a thread safe call and may be called by any thread.

Specified by:

removeAttribute in interface Continuation

Parameters:

name - the attribute name

See Also:

Continuation.removeAttribute(java.lang.String)

setAttribute

public void setAttribute(String name,
                         Object attribute)

Description copied from interface: Continuation

Set a request attribute. This method is a convenience method to call the ServletRequest.setAttribute(String, Object) method on the associated request object. This is a thread safe call and may be called by any thread.

Specified by:

setAttribute in interface Continuation

Parameters:

name - the attribute name

attribute - the attribute value

See Also:

Continuation.setAttribute(java.lang.String, java.lang.Object)

undispatch

public void undispatch()

Description copied from interface: Continuation

Undispatch the request.

This method can be called on a suspended continuation in order to exit the dispatch to the filter/servlet by throwing a ContinuationThrowable which is caught either by the container or the ContinuationFilter. This is an alternative to simply returning from the dispatch in the case where filters in the filter chain may not be prepared to handle a suspended request.

This method should only be used as a last resort and a normal return is a prefereable solution if filters can be updated to handle that case.

Specified by:

undispatch in interface Continuation

See Also:

Continuation.undispatch()

getHistory

public String getHistory()