EST 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 {@link RequestDispatcher#forward(ServletRequest,ServletResponse) 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 {@link ServletRequest#startAsync()} or{@link 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:
- Invoke, at their {@link AsyncListener#onError onError} method, all{@link AsyncListener} instances registered with the ServletRequestfor which this AsyncContext was created, and make the caught Throwable available via {@link AsyncEvent#getThrowable}.
- If none of the listeners called {@link #complete} or any of the{@link #dispatch} methods, perform an error dispatch with a status codeequal to HttpServletResponse.SC_INTERNAL_SERVER_ERROR, and make the above Throwable available as the value of the RequestDispatcher.ERROR_EXCEPTION request attribute.
- If no matching error page was found, or the error page did not call {@link #complete} or any of the {@link #dispatch} methods, call{@link #complete}.
There can be at most one asynchronous dispatch operation per asynchronous cycle, which is started by a call to one of the {@link ServletRequest#startAsync} methods. Any attempt to perform anadditional 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 {@link #complete} methods may be called.
@throws IllegalStateException if one of the dispatch methodshas been called and the startAsync method has not been called during the resulting dispatch, or if {@link #complete}was called
@see ServletRequest#getDispatcherType