Dispatches the request and response objects of this
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:
-
Invoke the
onError
method of all PortletAsyncListener
instances registered with this PortletAsyncContext
and
make the caught Throwable
available via
PortletAsyncEvent#getThrowable
.
-
If none of the listeners called
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 the asynchronous processing cycle by calling
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.