Spring之请求分发（Dispatching Requests） 之include方法

9.3  the include methon

RequestDispacher接口的include方法可能在任何时候被调用。include方法的目标servlet，虽然可以访问请求对象的所有信息，但是响应对象的使用上受限很大。

其可能仅写信息到响应对象的ServletOutputStream或者Writer并通过写内容到响应缓冲区中提交一个响应，或者直接调用ServletResponse接口的flushBuffer方法。其不能设置消息头或者调用任何方法影响响应的消息头，并带有HttpServletRequest.getSession()和HttpServletRequest.getSession(boolean)方法的异常。任何尝试设置消息头必须被忽略，任何调用HttpServletRequest.getSession()或者HttpServletRequest.getSession(boolean)，（会需要添加一个Cookie响应头），必须跑出一个异常，如果响应提交的话。

如果默认的servlet是RequestDispatch.include()的目标，并且请求资源不存在，那么默认的servlet必须抛出FileNotFoundException的异常。如果这个异常没有被铺货和处理，并且响应还没有提交，状态码必须设置为500。

9.3.1 包含的请求参数

除了使用getNamedDispatcher方法获取servlet外，一个servlet也可以通过另一个servlet使用RequestDispacher的include方法调用，可以访问其调用的路径。

必须设置下述的请求属性：

javax.servlet.include.request_uri
javax.servlet.include.context_path
javax.servlet.include.servlet_path
javax.servlet.include.path_info
javax.servlet.include.query_string

这些属性可以通过请求对象的getAttribute方法从所包含的servlet中访问并且它们的值必须分别与request URI,context path,servlet path, path info,和所包含的servlet的查询字符串对应。如果这个请求时随后包含的，这些属性就被后面包含的替代。

如果通过使用getNamedDispatcher方法获取到所包含的servlet，这些属性不必设置。

9.4 forward方法

RequestDispacher接口的forward方法可能被那个调用的servlet调用，仅当没有输出提交到客户端时。如果响应数据存在于响应缓冲区，还没有被提交，内容在目标servlet的service方法调用前必须被清空。如果响应还没有提交，必将抛出一个IllegalStateException异常。

请求对象的路径元素，暴露给目标servlet，必须反射到路径，用于获取RequestDispacher。

对此仅有的异常在此抛出，如果RequestDispatcher通过getNamedDispatcher方法获取。在这种情况下，请求对象的路径参数，必须反射到原始请求的那些路径参数。

在RequestDispatcher接口的forward方法没有任何异常返回之前，响应内容必须被发送和提交，并通过servlet容器关闭。如果一个错误发生在RequestDispatcher.forward()的目标中，异常可能通过调用的过滤器和servlets传播回并最终返回到容器。

9.4.1 查询字符串

请求分发机制负责聚集查询字符参数，当转递或者包括请求时。

9.4.2 转递的请求参数

除了通过getNamedDispatcher方法获取的servlet外，被另一个servlet使用RequestDispatcher的forward方法调用的servlet，可访问原始请求的路径。

必须设置下面 请求参数：

javax.servlet.forward.request_uri
javax.servlet.forward.context_path
javax.servlet.forward.servlet_path
javax.servlet.forward.path_info
javax.servlet.forward.query_string

这些属性的值必须分别与HttpServletRequest方法，getRequestURI, getContextPath, getServletPath,
getPathInfo, getQueryString相同，在传递给调用链中的第一个servlet对象的请求对象上调用，并从客户端中接收请求。

这些属性通过请求对象上的getAttribute方法从forwarded的servlet上是可访问的。注意这些属性必须总是反应原始请求的信息，即使在多个forwards和includes被调用的情况下。

如果这个forwarded servlet被getNamedDispatcher方法获取，这些属性不必设置。

9.5 错误处理

如果这个servlet（请求分发的目标）抛出了一个运行期异常或者检查型异常（ServletException或者IOException），其应该被传到正在调用的servlet。所有其他的异常应该被封装为ServletExceptions并且异常的根本原因设置为原始异常，因为其不应该不传递。

9.6 获取一个AsyncContext（异步上下文）

实现了AsyncContext接口的对象可能从ServletRequest中通过startAsync方法之一获取。一旦有了一个AsyncContext,你可以使用它要不借助complete()方法请求处理或者使用以下分发方法中的一个。

9.7 分发方法

下面的方法可以用于从AsyncContext:中分发方法：

dispatch(path)

dispatch方法传递一个字符串类型的参数，其描述了ServletContext范围内的路径。这个路径必须是相对于ServletContext的根目录并且以'/'开始

dispatch(servletContext，path)

dispatch方法传递了一个字符串的路径，其描述了指定ServletContext范围内的路径。这个路径必须是相对于指定ServletContext的根目录并且以'/'开始。

dispatch()

这个dispatch方法不传递任何参数。使用原始的URI作为路径。如果这个AsyncContext通过startAsync(ServletRequest,
ServletResponse)初始化，并且传递的请求是HttpServletRequest的一个实例，那么分发的是由HttpServletRequest.getRequestURI()返回的URI。否则，分发的请求URI是由容器最后一次分发的。

AsyncContext接口的分发方法中的一个，可能被应用程序调用，直到异步事件发生。如果AsyncContext上已经调用了complete()，必须抛出IllegalStateException异常。此时，所有的分发方法必须立即返回并且不提交这个响应。

暴露给目标servlet的请求对象的路径元素必须体现AsyncContext.dispatch中指定的路径。

9.7.1 查询字符创

请求分发机制负责当分发请求时 聚集查询字符串参数。

9.7.2 分发请求参数

一个Servlet 使用AsyncContext的dispatch方法调用的，可以访问原始请求路径。

必须设置下述的请求属性：

javax.servlet.async.request_uri
javax.servlet.async.context_path
javax.servlet.async.servlet_path
javax.servlet.async.path_info
javax.servlet.async.query_string

这些属性值必须分别于HttpServletRequest的方法getRequestURI, getContextPath, getServletPath,getPathInfo, getQueryString的返回值相同，在请求对象上调用，并传递给调用链（接受来自客户端的请求）中的第一个servlet对象。

这些属性通过请求对象上的getAttribute方法从分发的servlet上是可访问的。注意，这些属性必须总是反应原始请求的信息，即使在调用多种分发的情形下。