public interface PortletAsyncContext
Portlet asynchronous support is modeled after servlet asynchronous support, and in
general, the portlet async methods behave in the same manner as their
AsyncContext
analog.
A PortletAsyncContext
is created and initialized by a call to
ResourceRequest#startAsync()
or
ResourceRequest#startAsync(ServletRequest, ServletResponse)
.
Repeated invocations of these methods will return the same
PortletAsyncContext
instance, reinitialized as appropriate.
In the event that an asynchronous operation times out, the container will
invoke the onTimeout method of all PortletAsyncListener
instances registered
with the PortletAsyncContext
on which the asynchronous operation was initiated.
If none of the listeners call complete()
or any of the
dispatch()
methods, the portlet container will
complete the request on behalf of the application and may respond with error information.
AsyncContext
,
PortletAsyncListener
,
PortletAsyncEvent
Modifier and Type | Method and Description |
---|---|
void |
addListener(PortletAsyncListener listener)
Registers the given
PortletAsyncListener with the most recent
asynchronous cycle that was started by a call to one of the
ResourceRequest.startAsync() methods. |
void |
addListener(PortletAsyncListener listener,
ResourceRequest request,
ResourceResponse response)
Registers the given
PortletAsyncListener with the most recent
asynchronous cycle that was started by a call to one of the
ResourceRequest.startAsync() methods. |
void |
complete()
Completes the
PortletAsynchronous operation
and closes the response associated with this PortletAsyncContext object. |
<T extends PortletAsyncListener> |
createPortletAsyncListener(Class<T> cls)
Instantiates the given
PortletAsyncListener class. |
void |
dispatch()
Dispatches the request and response objects of this
PortletAsyncContext to
the portlet container. |
void |
dispatch(String path)
Dispatches the request and response objects of this
PortletAsyncContext to
the given path within the PortletContext . |
ResourceRequest |
getResourceRequest()
Gets the request that was used to initialize this
PortletAsyncContext by calling
ResourceRequest.startAsync() or ResourceRequest.startAsync(ServletRequest, ServletResponse) . |
ResourceResponse |
getResourceResponse()
Gets the response that was used to initialize this
PortletAsyncContext by calling
ResourceRequest.startAsync() or ResourceRequest.startAsync(ServletRequest, ServletResponse) . |
long |
getTimeout()
Gets the timeout (in milliseconds) for this PortletAsyncContext.
|
boolean |
hasOriginalRequestAndResponse()
Checks if this
PortletAsyncContext was initialized with the original or
application-wrapped request and response objects. |
void |
setTimeout(long time)
Sets the timeout (in milliseconds) for this
PortletAsyncContext . |
void |
start(Runnable run)
Causes the container to dispatch a thread, possibly from a managed thread pool,
to run the specified
Runnable . |
void addListener(PortletAsyncListener listener) throws IllegalStateException
PortletAsyncListener
with the most recent
asynchronous cycle that was started by a call to one of the
ResourceRequest.startAsync()
methods.
The given PortletAsyncListener
will receive an
PortletAsyncEvent
when the
asynchronous cycle completes successfully, times out, results in an error, or a
new asynchronous cycle is being initiated via one of the
ResourceRequest.startAsync()
methods.
PortletAsyncListener
instances will be notified in the order in
which they were added.
When one of the listener methods is invoked, the
PortletAsyncListener
getSuppliedRequest()
and
getSuppliedResponse()
methods of the
PortletAsyncEvent
object will return null
.
listener
- the listener to be addedIllegalStateException
- if this method is called after the container-initiated dispatch, during which
one of the ResourceRequest.startAsync()
methods was called, has
returned to the containerPortletAsyncListener
,
PortletAsyncEvent
void addListener(PortletAsyncListener listener, ResourceRequest request, ResourceResponse response) throws IllegalStateException
PortletAsyncListener
with the most recent
asynchronous cycle that was started by a call to one of the
ResourceRequest.startAsync()
methods.
The given PortletAsyncListener
will receive an
PortletAsyncEvent
when the
asynchronous cycle completes successfully, times out, results in an error, or a
new asynchronous cycle is being initiated via one of the
ResourceRequest.startAsync()
methods.
PortletAsyncListener
instances will be notified in the order in
which they were added.
The given ResourceRequest
and ResourceResponse
objects will be made
available to the given PortletAsyncListener
via the
getSuppliedRequest
and
getSuppliedResponse
methods, respectively, of the
PortletAsyncEvent
delivered to
it. These objects should not be read from or written to at the
time the PortletAsyncEvent
is delivered, because additional wrapping
may have
occurred since the given PortletAsyncListener
was registered.
However, they may be used to release any resources associated with them.
listener
- the listener to be addedrequest
- the request object to be included in the PortletAsyncEvent
response
- the response object to be included in the PortletAsyncEvent
IllegalStateException
- if this method is called after the container-initiated dispatch, during which
one of the ResourceRequest.startAsync()
methods was called, has
returned to the containerPortletAsyncListener
,
PortletAsyncEvent
void complete() throws IllegalStateException
PortletAsynchronous
operation
and closes the response associated with this PortletAsyncContext
object.
The onComplete
method of any registered listeners that were registered
with the PortletAsyncContext
object for this asynchronous cycle
will be invoked.
It is legal to call this method any time after a call to
ResourceRequest#startAsync()
or
ResourceRequest#startAsync(ResourceRequest, ResourceResponse)
,
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
PortletAsyncListener#onComplete(PortletAsyncEvent)
will
be delayed) until after the container-initiated dispatch has returned to the
container.
IllegalStateException
- if this method is called before an asynchronous processing cycle was started,
after it has already been completed, or after a call to
one of the dispatch()
methods<T extends PortletAsyncListener> T createPortletAsyncListener(Class<T> cls) throws PortletException
PortletAsyncListener
class.
The returned PortletAsyncListener
instance may be further customized before it is
registered with this PortletAsyncContext
via a call to one of the addListener methods.
The given PortletAsyncListener
class must define a zero argument constructor, which is
used to instantiate it.
This method supports resource injection if contextual support is available, and if the given class represents a Managed Bean. See the Java EE platform and JSR 299 specifications for additional details about Managed Beans and resource injection.
cls
- the class to be instantiatedPortletException
- if the given class cannot be instantiatedvoid dispatch() throws IllegalStateException
PortletAsyncContext
to
the portlet container.
The portlet container will dispatch the the request and response to the portlet resource method in which the first asynchronous processing cycle was initiated.
This method returns immediately after passing the request and response objects to a container managed thread which will perform the dispatch operation. If this method is called before the container-initiated dispatch that called startAsync has returned to the container, the dispatch operation will be delayed until after the container-initiated dispatch has returned to the container.
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 ResourceRequest#startAsync()
or
ResourceRequest#startAsync(ResourceRequest, ResourceResponse)
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 of all PortletAsyncListener
instances registered with this PortletAsyncContext
and
make the caught Throwable
available via
PortletAsyncEvent#getThrowable
.
complete()
or any of the dispatch()
methods, set the status code equal to
HttpResourceResponse.SC_INTERNAL_SERVER_ERROR
, make the
Throwable
leading to the error available as the value of the
RequestDispatcher.ERROR_EXCEPTION
request attribute, and perform
an error dispatch to generate a platform-specific error message.
complete()
.
There can be at most one asynchronous dispatch operation per asynchronous
cycle, which is started by a call to one of the ResourceRequest#startAsync
methods. Any attempt to perform an additional asynchronous dispatch
operation within the same asynchronous cycle will result in an
IllegalStateException
. When the container performs the dispatch operation,
startAsync()
may be invoked on the dispatched request to initiate a new
asynchronous processing cycle, after which any of the dispatch methods or the
complete()
method may be called.
IllegalStateException
- if called before an asynchronous processing cycle has been started,
if one of the dispatch methods has been called but the startAsync
method has not
been called during the resulting dispatch, or if complete()
was calledvoid dispatch(String path) throws IllegalStateException
PortletAsyncContext
to
the given path within the PortletContext
.
The path parameter is interpreted in the same way as in
PortletContext#getRequestDispatcher(String)
scoped to
the current portlet context.
There can be at most one asynchronous dispatch operation per asynchronous
cycle, which is started by a call to one of the ResourceRequest#startAsync
methods. Any attempt to perform an additional asynchronous dispatch
operation within the same asynchronous cycle will result in an
IllegalStateException
. When the container performs the dispatch operation,
startAsync()
may be invoked on the dispatched request to initiate a new
asynchronous processing cycle, after which any of the dispatch methods or the
complete()
method may be called.
See dispatch()
for additional details, including error handling.
path
- the path of the dispatch target, scoped to the PortletContext from which
this PortletAsyncContext was initializedIllegalStateException
- if called before an asynchronous processing cycle has been started,
if one of the dispatch methods has been called but the startAsync
method has not
been called during the resulting dispatch, or if complete()
was calledResourceRequest getResourceRequest() throws IllegalStateException
PortletAsyncContext
by calling
ResourceRequest.startAsync()
or ResourceRequest.startAsync(ServletRequest, ServletResponse)
.
IllegalStateException
- if one of the dispatch methods has been called but the startAsync
method has not
been called during the resulting dispatch, or if complete()
was calledResourceResponse getResourceResponse() throws IllegalStateException
PortletAsyncContext
by calling
ResourceRequest.startAsync()
or ResourceRequest.startAsync(ServletRequest, ServletResponse)
.
IllegalStateException
- if one of the dispatch methods has been called but the startAsync
method has not
been called during the resulting dispatch, or if complete()
was calledlong getTimeout()
This method returns the container's default timeout for asynchronous operations,
or the timeout value passed to the most recent invocation of
setTimeout(long)
.
A timeout value of zero or less indicates no timeout.
boolean hasOriginalRequestAndResponse()
PortletAsyncContext
was initialized with the original or
application-wrapped request and response objects.
This 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.
true
if this PortletAsyncContext
was initialized with the original
request and response objects by calling ResourceRequest.startAsync()
,
or if it was initialized by calling
ResourceRequest.startAsync(ResourceRequest, ResourceResponse)
, and neither
the ResourceRequest
nor ResourceResponse
arguments carried any
application-provided wrappers; false
otherwisevoid setTimeout(long time)
PortletAsyncContext
.
The timeout applies to this PortletAsyncContext
once the
container-initiated dispatch
during which one of the ResourceRequest.startAsync()
methods was
called has returned to the container.
The timeout will expire if neither the complete()
method nor any of
the dispatch
methods are called. A timeout value of zero or less indicates no timeout.
If setTimeout(long)
is not called, then the container's default timeout,
which is available via a call to getTimeout()
, will apply.
The default value is 30000 ms.
time
- the timeout in millisecondsvoid start(Runnable run) throws IllegalStateException
Runnable
. The container may propagate appropriate
contextual information to the Runnable
.
run
- the asynchronous handlerIllegalStateException
- if this method is called before an asynchronous processing cycle was started,
after it has already been completed, or after a call to
one of the dispatch()
methodsJava Portlet 3.0 API Specification. See the Copyright and License provided with this distribution. Use is subject to license terms.