|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectorg.eclipse.jetty.server.AsyncContinuation
public class AsyncContinuation
Implementation of Continuation and AsyncContext interfaces
| Nested Class Summary | |
|---|---|
class |
AsyncContinuation.AsyncEventState
|
class |
AsyncContinuation.AsyncTimeout
|
| Field Summary | |
|---|---|
protected HttpConnection |
_connection
|
| Fields inherited from interface javax.servlet.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 |
addListener(AsyncListener listener)
Registers the given AsyncListener with the most recent
asynchronous cycle that was started by a call to one of the
ServletRequest.startAsync() methods. |
|
void |
addListener(AsyncListener listener,
ServletRequest request,
ServletResponse response)
Registers the given AsyncListener with the most recent
asynchronous cycle that was started by a call to one of the
ServletRequest.startAsync() methods. |
|
void |
cancel()
|
|
protected void |
cancelTimeout()
|
|
void |
complete()
Completes the asynchronous operation that was started on the request that was used to initialze this AsyncContext, closing the response that was used to initialize this AsyncContext. |
|
|
createListener(java.lang.Class<T> clazz)
Instantiates the given AsyncListener class. |
|
void |
dispatch()
Dispatches the request and response objects of this AsyncContext to the servlet container. |
|
void |
dispatch(ServletContext context,
java.lang.String path)
Dispatches the request and response objects of this AsyncContext to the given path scoped to the given context. |
|
void |
dispatch(java.lang.String path)
Dispatches the request and response objects of this AsyncContext to the given path. |
|
protected void |
doComplete(java.lang.Throwable ex)
|
|
protected void |
expired()
|
|
AsyncContinuation.AsyncEventState |
getAsyncEventState()
|
|
java.lang.Object |
getAttribute(java.lang.String name)
Get a request attribute. |
|
Request |
getBaseRequest()
|
|
ContextHandler |
getContextHandler()
|
|
ServletRequest |
getRequest()
Gets the request that was used to initialize this AsyncContext by calling ServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse). |
|
ServletResponse |
getResponse()
Gets the response that was used to initialize this AsyncContext by calling ServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse). |
|
ServletResponse |
getServletResponse()
Get the suspended response. |
|
java.lang.String |
getStatusString()
|
|
long |
getTimeout()
Gets the timeout (in milliseconds) for this AsyncContext. |
|
protected boolean |
handling()
|
|
boolean |
hasOriginalRequestAndResponse()
Checks if this AsyncContext was initialized with the original or application-wrapped request and response objects. |
|
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(java.lang.String name)
Remove a request attribute. |
|
void |
resume()
Resume a suspended request. |
|
protected void |
scheduleDispatch()
|
|
protected void |
scheduleTimeout()
|
|
void |
setAttribute(java.lang.String name,
java.lang.Object attribute)
Set a request attribute. |
|
protected void |
setConnection(HttpConnection connection)
|
|
void |
setTimeout(long ms)
Sets the timeout (in milliseconds) for this AsyncContext. |
|
void |
start(java.lang.Runnable run)
Causes the container to dispatch a thread, possibly from a managed thread pool, to run the specified Runnable. |
|
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. |
|
java.lang.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 |
|---|
protected HttpConnection _connection
| Constructor Detail |
|---|
protected AsyncContinuation()
| Method Detail |
|---|
protected void setConnection(HttpConnection connection)
public void addListener(AsyncListener listener)
AsyncContextAsyncListener with the most recent
asynchronous cycle that was started by a call to one of the
ServletRequest.startAsync() methods.
The given AsyncListener will receive an AsyncEvent when
the asynchronous cycle completes successfully, times out, or results
in an error.
AsyncListener instances will be notified in the order in which they were added.
addListener in interface AsyncContextlistener - the AsyncListener to be registered
public void addListener(AsyncListener listener,
ServletRequest request,
ServletResponse response)
AsyncContextAsyncListener with the most recent
asynchronous cycle that was started by a call to one of the
ServletRequest.startAsync() methods.
The given AsyncListener will receive an AsyncEvent when
the asynchronous cycle completes successfully, times out, or results
in an error.
AsyncListener instances will be notified in the order in which they were added.
The given ServletRequest and ServletResponse objects will
be made available to the given AsyncListener via the
getSuppliedRequest and
getSuppliedResponse methods,
respectively, of the AsyncEvent delivered to it. These objects
should not be read from or written to, respectively, at the time the
AsyncEvent is delivered, because additional wrapping may have
occurred since the given AsyncListener was registered, but may be used
in order to release any resources associated with them.
addListener in interface AsyncContextlistener - the AsyncListener to be registeredrequest - the ServletRequest that will be included
in the AsyncEventresponse - the ServletResponse that will be included
in the AsyncEventpublic void addContinuationListener(ContinuationListener listener)
Continuation
addContinuationListener in interface Continuationpublic void setTimeout(long ms)
AsyncContextThe timeout applies to this AsyncContext once the
container-initiated dispatch during which one of the
ServletRequest.startAsync() methods was called has
returned to the container.
The timeout will expire if neither the AsyncContext.complete() method
nor any of the dispatch methods are called. A timeout value of
zero or less indicates no timeout.
If AsyncContext.setTimeout(long) is not called, then the container's
default timeout, which is available via a call to
AsyncContext.getTimeout(), will apply.
setTimeout in interface AsyncContextsetTimeout in interface Continuationms - the timeout in millisecondspublic long getTimeout()
AsyncContextThis method returns the container's default timeout for
asynchronous operations, or the timeout value passed to the most
recent invocation of AsyncContext.setTimeout(long).
A timeout value of zero or less indicates no timeout.
getTimeout in interface AsyncContextpublic AsyncContinuation.AsyncEventState getAsyncEventState()
public boolean isResponseWrapped()
Continuation
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).
isResponseWrapped in interface ContinuationContinuation.suspend(ServletResponse) has been passed a
ServletResponseWrapper instance.Continuation.isResponseWrapped()public boolean isInitial()
isInitial in interface Continuationpublic boolean isSuspended()
isSuspended in interface ContinuationContinuation.suspend() has been called and before the
request has been redispatched due to being resumed, completed or
timed out.public java.lang.String toString()
toString in class java.lang.Objectpublic java.lang.String getStatusString()
protected boolean handling()
protected void suspend(ServletContext context,
ServletRequest request,
ServletResponse response)
protected boolean unhandle()
public void dispatch()
AsyncContextIf the asynchronous cycle was started with
ServletRequest.startAsync(ServletRequest, ServletResponse),
and the request passed is an instance of HttpServletRequest,
then the dispatch is to the URI returned by
HttpServletRequest.getRequestURI().
Otherwise, the dispatch is to the URI of the request when it was
last dispatched by the container.
The following sequence illustrates how this will work:
// REQUEST dispatch to /url/A
AsyncContext ac = request.startAsync();
...
ac.dispatch(); // ASYNC dispatch to /url/A
// FORWARD dispatch to /url/B
getRequestDispatcher("/url/B").forward(request,response);
// Start async operation from within the target of the FORWARD
// dispatch
ac = request.startAsync();
...
ac.dispatch(); // ASYNC dispatch to /url/A
// FORWARD dispatch to /url/B
getRequestDispatcher("/url/B").forward(request,response);
// Start async operation from within the target of the FORWARD
// dispatch
ac = request.startAsync(request,response);
...
ac.dispatch(); // ASYNC dispatch to /url/B
This method returns immediately after passing the request and response objects to a container managed thread, on which the dispatch operation will be performed.
The dispatcher type of the request is set to
DispatcherType.ASYNC. Unlike
forward dispatches, the response buffer and
headers will not be reset, and it is legal to dispatch even if the
response has already been committed.
Control over the request and response is delegated
to the dispatch target, and the response will be closed when the
dispatch target has completed execution, unless
ServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse)
are called.
Any errors or exceptions that may occur during the execution of this method must be caught and handled by the container, as follows:
onError method, all
AsyncListener instances registered with the ServletRequest
for which this AsyncContext was created, and make the caught
Throwable available via AsyncEvent.getThrowable().AsyncContext.complete() or any of the
AsyncContext.dispatch() methods, perform an error dispatch with a status code
equal to HttpServletResponse.SC_INTERNAL_SERVER_ERROR, and
make the above Throwable available as the value of the
RequestDispatcher.ERROR_EXCEPTION request attribute.AsyncContext.complete() or any of the AsyncContext.dispatch() methods, call
AsyncContext.complete().There can be at most one asynchronous dispatch operation per
asynchronous cycle, which is started by a call to one of the
ServletRequest.startAsync() methods. Any attempt to perform an
additional asynchronous dispatch operation within the same
asynchronous cycle will result in an IllegalStateException.
If startAsync is subsequently called on the dispatched request,
then any of the dispatch or AsyncContext.complete() methods may be called.
dispatch in interface AsyncContextServletRequest.getDispatcherType()protected void expired()
public void complete()
AsyncContextAny listeners of type AsyncListener that were registered
with the ServletRequest for which this AsyncContext was created will
be invoked at their onComplete method.
It is legal to call this method any time after a call to
ServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse),
and before a call to one of the dispatch methods
of this class.
If this method is called before the container-initiated dispatch
that called startAsync has returned to the container, then
the call will not take effect (and any invocations of
AsyncListener.onComplete(AsyncEvent) will be delayed) until
after the container-initiated dispatch has returned to the container.
complete in interface AsyncContextcomplete in interface ContinuationContinuation.suspend()
public <T extends AsyncListener> T createListener(java.lang.Class<T> clazz)
throws ServletException
AsyncContextAsyncListener class.
The returned AsyncListener instance may be further customized
before it is registered with this AsyncContext via a call to one of
the addListener methods.
The given AsyncListener class must define a zero argument constructor, which is used to instantiate it.
This method supports resource injection if the given clazz represents a Managed Bean. See the Java EE platform and JSR 299 specifications for additional details about Managed Beans and resource injection.
This method supports any annotations applicable to AsyncListener.
createListener in interface AsyncContextclazz - the AsyncListener class to instantiate
ServletException - if the given clazz fails to be
instantiatedprotected void doComplete(java.lang.Throwable ex)
protected void recycle()
public void cancel()
protected void scheduleDispatch()
protected void scheduleTimeout()
protected void cancelTimeout()
public boolean isCompleting()
public boolean isComplete()
public boolean isAsyncStarted()
public boolean isAsync()
public void dispatch(ServletContext context,
java.lang.String path)
AsyncContextThe path parameter is interpreted in the same way
as in ServletRequest.getRequestDispatcher(String), except that
it is scoped to the given context.
All path related query methods of the request must reflect the
dispatch target, while the original request URI, context path,
path info, servlet path, and query string may be recovered from
the AsyncContext.ASYNC_REQUEST_URI, AsyncContext.ASYNC_CONTEXT_PATH,
AsyncContext.ASYNC_PATH_INFO, AsyncContext.ASYNC_SERVLET_PATH, and
AsyncContext.ASYNC_QUERY_STRING attributes of the request. These
attributes will always reflect the original path elements, even under
repeated dispatches.
There can be at most one asynchronous dispatch operation per
asynchronous cycle, which is started by a call to one of the
ServletRequest.startAsync() methods. Any attempt to perform an
additional asynchronous dispatch operation within the same
asynchronous cycle will result in an IllegalStateException.
If startAsync is subsequently called on the dispatched request,
then any of the dispatch or AsyncContext.complete() methods may be called.
See AsyncContext.dispatch() for additional details, including error
handling.
dispatch in interface AsyncContextcontext - the ServletContext of the dispatch targetpath - the path of the dispatch target, scoped to the given
ServletContextServletRequest.getDispatcherType()public void dispatch(java.lang.String path)
AsyncContextThe path parameter is interpreted in the same way
as in ServletRequest.getRequestDispatcher(String), within
the scope of the ServletContext from which this
AsyncContext was initialized.
All path related query methods of the request must reflect the
dispatch target, while the original request URI, context path,
path info, servlet path, and query string may be recovered from
the AsyncContext.ASYNC_REQUEST_URI, AsyncContext.ASYNC_CONTEXT_PATH,
AsyncContext.ASYNC_PATH_INFO, AsyncContext.ASYNC_SERVLET_PATH, and
AsyncContext.ASYNC_QUERY_STRING attributes of the request. These
attributes will always reflect the original path elements, even under
repeated dispatches.
There can be at most one asynchronous dispatch operation per
asynchronous cycle, which is started by a call to one of the
ServletRequest.startAsync() methods. Any attempt to perform an
additional asynchronous dispatch operation within the same
asynchronous cycle will result in an IllegalStateException.
If startAsync is subsequently called on the dispatched request,
then any of the dispatch or AsyncContext.complete() methods may be called.
See AsyncContext.dispatch() for additional details, including error
handling.
dispatch in interface AsyncContextpath - the path of the dispatch target, scoped to the
ServletContext from which this AsyncContext was initializedServletRequest.getDispatcherType()public Request getBaseRequest()
public ServletRequest getRequest()
AsyncContextServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse).
getRequest in interface AsyncContextpublic ServletResponse getResponse()
AsyncContextServletRequest.startAsync() or
ServletRequest.startAsync(ServletRequest, ServletResponse).
getResponse in interface AsyncContextpublic void start(java.lang.Runnable run)
AsyncContext
start in interface AsyncContextrun - the asynchronous handlerpublic boolean hasOriginalRequestAndResponse()
AsyncContextThis information may be used by filters invoked in the outbound direction, after a request was put into asynchronous mode, to determine whether any request and/or response wrappers that they added during their inbound invocation need to be preserved for the duration of the asynchronous operation, or may be released.
hasOriginalRequestAndResponse in interface AsyncContextServletRequest.startAsync(), or if it was initialized by
calling
ServletRequest.startAsync(ServletRequest, ServletResponse),
and neither the ServletRequest nor ServletResponse arguments
carried any application-provided wrappers; false otherwisepublic ContextHandler getContextHandler()
public boolean isResumed()
isResumed in interface ContinuationContinuation.resume(). Returns false after any subsequent call to
suspendContinuation.isResumed()public boolean isExpired()
isExpired in interface ContinuationContinuation.isExpired()public void resume()
Continuation
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 Continuation.suspend() 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.
resume in interface ContinuationContinuation.resume()public void suspend(ServletResponse response)
ContinuationServletResponse.
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:
Continuation.resume().Continuation.complete().
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).
suspend in interface Continuationresponse - The response to return via a call to Continuation.getServletResponse()Continuation.suspend()public void suspend()
ContinuationServletResponse.
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:
Continuation.resume().Continuation.complete().
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.
suspend in interface ContinuationContinuation.suspend()public ServletResponse getServletResponse()
Continuation
getServletResponse in interface ContinuationServletResponse passed to Continuation.suspend(ServletResponse).Continuation.getServletResponse()public java.lang.Object getAttribute(java.lang.String name)
ContinuationServletRequest.getAttribute(String)
method on the associated request object.
This is a thread safe call and may be called by any thread.
getAttribute in interface Continuationname - the attribute name
Continuation.getAttribute(java.lang.String)public void removeAttribute(java.lang.String name)
ContinuationServletRequest.removeAttribute(String)
method on the associated request object.
This is a thread safe call and may be called by any thread.
removeAttribute in interface Continuationname - the attribute nameContinuation.removeAttribute(java.lang.String)
public void setAttribute(java.lang.String name,
java.lang.Object attribute)
ContinuationServletRequest.setAttribute(String, Object)
method on the associated request object.
This is a thread safe call and may be called by any thread.
setAttribute in interface Continuationname - the attribute nameattribute - the attribute valueContinuation.setAttribute(java.lang.String, java.lang.Object)public void undispatch()
Continuation
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.
undispatch in interface ContinuationContinuation.undispatch()
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||