org.eclipse.jetty.continuation
Interface Continuation

All Known Implementing Classes:

AsyncRequest

public interface Continuation

Continuation. A continuation is a mechanism by which a HTTP Request can be suspended and restarted after a timeout or an asynchronous event has occurred.

Field Summary

static String

ATTRIBUTE

Method Summary

void	addContinuationListener(ContinuationListener listener)
void	complete() Complete a suspended request.
boolean	isExpired()
boolean	isInitial()
boolean	isResumed()
boolean	isSuspended()
void	keepWrappers() Call to signal that the suspending filter/servlet has kept a reference to any passed requests wrappers, and that these should not be finalized until a onComplete event has been seen.
void	resume() Resume a suspended request.
void	setTimeout(long timeoutMs) Set the continuation timeout
void	suspend() Suspend the processing of the request and associated ServletResponse.
boolean	wrappersKept()

Field Detail

ATTRIBUTE

static final String ATTRIBUTE

See Also:

Constant Field Values

Method Detail

setTimeout

void setTimeout(long timeoutMs)

Set the continuation timeout

Parameters:

timeoutMs - The time in milliseconds to wait before expiring this continuation.

suspend

void suspend()

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. If a request is suspended, then the container will not commit the associated response when the call to the filter chain and/or servlet service method returns to the container. Any exceptions thrown to the container by a filter chain and/or servlet for a suspended requests are silently ignored.

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 pending either:

• a call to ServletRequest#resume().
• a call to ServletRequest#complete().
• the passed or default timeout expires.
• there is IO activity on the connection that received the request, such as the close of the connection or the receipt of a pipelined request.

After any of the events listed above, the suspended request will be redispatched via the filter and servlet processing.

Suspend may only be called by a thread that is within the service calling stack of Filter.doFilter(ServletRequest, ServletResponse, FilterChain) and/or Servlet.service(ServletRequest, ServletResponse). A request that has been dispatched for error handling may not be suspended.

Throws:

IllegalStateException - If the calling thread is not within the calling stack of Filter.doFilter(ServletRequest, ServletResponse, FilterChain) and/or Servlet.service(ServletRequest, ServletResponse) or if the request has been dispatched for error handling.

See Also:

#resume()}, #complete()}

resume

void resume()

Resume a suspended request.

This method can be called by any thread that has been passed a reference to a suspended request. When called the request is redispatched to the normal filter chain and servlet processing.

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 isSuspended() and isResumed() return true.

Multiple calls to resume are ignored

Throws:

IllegalStateException - if the request is not suspended.

See Also:

#suspend()}

complete

void complete()

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 isSuspended() and isResumed() return true.

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 reference after the end of the life cycle or to call any request methods.

Throws:

IllegalStateException - if the request is not suspended.

See Also:

#suspend()}

isSuspended

boolean isSuspended()

Returns:

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

isResumed

boolean isResumed()

Returns:

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

isExpired

boolean isExpired()

Returns:

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

isInitial

boolean isInitial()

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.

keepWrappers

void keepWrappers()

Call to signal that the suspending filter/servlet has kept a reference to any passed requests wrappers, and that these should not be finalized until a onComplete event has been seen.

wrappersKept

boolean wrappersKept()

Returns:

True if keepWrappers() has been called.

addContinuationListener

void addContinuationListener(ContinuationListener listener)

Parameters:

listener -