AsyncContext源码翻译

package javax.servlet;
/**
 * 目的：异步操作执行环境的初始化
 * 
 * <p>调用{@link ServletRequest#startAsync()}或{@link ServletRequest#startAsync()}
 * 去创建AsyncContext对象并初始化。这些方法的重复调用将返回相同的AsyncContext实例，重新初始化为为佳。
 * 
 * <p>异步操作超时，容器将经过以下步骤：
 *   a.ServletRequest异步操作初始化时，注册的所有{@link AsyncListener}实例，这些实例都将调用
 *     {@link AsyncListener#onTimeout onTimeout}方法。
 *   b.如果没有一个监听器调用{@link #complete}或{@link #dispatch}方法时，将执行一个错误调度
 *     状态码，这相当于HttpServletResponse.SC_INTERNAL_SERVER_ERROR。
 *   c.如果没有找到错误页面或错误页面没有调用{@link #complete}或{@link #dispatch}时，将调用
 *     {@link #complete}
 * @author TCM
 * @create 2017年10月25日上午10:04:49
 * @since Servlet 3.0
 */
public interface AsyncContext {

    /**
     * 获取该环境对应的请求
     * 即：请求启动异步时，生成的AsyncContext，该环境对应的请求
     * @exception IllegalStateException
     */
    public ServletRequest getRequest();
    public ServletResponse getResponse();


    /**
     * 检查AsyncContext初始化时，对应的原始请求和响应
     * 
     * 在过滤器outbound时调用，之后请求进入异步模式。
     */
    public boolean hasOriginalRequestAndResponse();


    /**
     * 目的：AsyncContext调度请求和响应到servlet容器中，进行转发等操作
     * @throws IllegalStateException
     * @see ServletRequest#getDispatcherType
     */
    public void dispatch();
    public void dispatch(String path);
    public void dispatch(ServletContext context, String path);


    /**
     * AsyncContext完成异步操作，关闭响应。
     * 响应完成后，监听器调用{@link AsyncListener#onComplete(AsyncEvent) onComplete}
     */
    public void complete();


    /**
     * 容器从线程池中调度一个线程去启动。
     * @param run 异步操作手
     */
    public void start(Runnable run);


    /**
     * {@link ServletRequest#startAsync}调用时，注册一个异步监听器。
     * 
     * 该监听器监听{@link AsyncEvent}事件，异步环：成功完成、超时、错误等。
     * @param listener 
     * @throws IllegalStateException 
     */
    public void addListener(AsyncListener listener);
    public void addListener(AsyncListener listener,
                            ServletRequest servletRequest,
                            ServletResponse servletResponse);
    public <T extends AsyncListener> T createListener(Class<T> clazz)
        throws ServletException; 


    /**
     * 为AsyncContext设置超时时间，单位：毫秒
     */
    public void setTimeout(long timeout);
    public long getTimeout();
    

    static final String ASYNC_REQUEST_URI = "javax.servlet.async.request_uri";
    static final String ASYNC_CONTEXT_PATH = "javax.servlet.async.context_path";
    static final String ASYNC_PATH_INFO = "javax.servlet.async.path_info";
    static final String ASYNC_SERVLET_PATH = "javax.servlet.async.servlet_path";
    static final String ASYNC_QUERY_STRING = "javax.servlet.async.query_string";

}