欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

Servlet3.1规范翻译——转发请求

程序员文章站 2022-04-12 19:13:53
...

转发请求

 

构建Web应用时,把请求转发给另一个servlet处理、或在response中包含另一个servlet的输出通常是很有用的。RequestDispatcher接口提供了一种机制来实现这种功能。

 

当请求启用异步处理时,AsyncContext允许用户将这个请求转发到servlet容器。

 

9.1 获得一个RequestDispatcher

实现了RequestDispatcher接口的对象,可以从ServletContext中的下面方法得到:

getRequestDispatcher

getNamedDispatcher

 

getRequestDispatcher方法需要一个String类型的参数描述在ServletContext作用域内的路径。这个路径必须是相对于ServletContext的根路径,或以’/’开头,或者为空。该方法根据这个路径使用servlet路径匹配规则(见第12章,请求映射到servlet)来查找servlet,把它包装成RequestDispatcher对象并返回。如果基于给定的路径没有找到相应的servlet,那么返回这个路径内容提供的RequestDispatcher。

 

getNamedDispatcher方法使用一个ServletContext知道的servlet名称作为参数。如果找到一个servlet,则把它包装成RequestDispatcher对象,并返回该对象。如果没有与给定名字相关的servlet,该方法必须返回null。

 

为了让RequestDispatcher对象使用相对于当前请求路径的相对路径(不是相对于ServletContext根路径)获得一个servlet,在ServletRequest接口中提供了getRequestDispatcher方法。

 

此方法的行为与ServletContext中同名的方法相似。Servlet容器根据request对象中的信息把给定的相对路径转换成当前servlet的完整路径。例如,在以’/’作为上下文根路径和请求路径/garden/tools.html中,通过ServletRequest.getRequestDispatcher("header.html")获得的请求调度器和通过调用ServletContext.getRequestDispatcher("/garden/header.html")获得的完全一样。

 

9.1.1 请求调度器路径中的查询字符串

ServletContext和ServletRequest中创建RequestDispatcher对象的方法使用的路径信息中允许附加可选的查询字符串信息。比如,开发人员可以通过下面的代码来获得一个RequestDispatcher:

String path = “/raisins.jsp?orderno=5”;

RequestDispatcher rd = context.getRequestDispatcher(path);

rd.include(request, response);

 

查询字符串中指定的用来创建RequestDispatcher的参数优先于传递给它包含的servlet中的其他同名参数。与RequestDispatcher相关的参数作用域仅适用于包含(include)或转发(forward)调用期间。

 

9.2 请求调度器的使用

要使用请求调度器,servlet可调用RequestDispatcher接口的include或forward方法。这些方法的参数既可以是javax.servlet.Servlet接口的service方法传来的request和response对象实例,也可以是本规范的2.3版本中介绍的request和response包装器类的子类对象实例。对于后者,包装器实例必须包装容器传递到service方法中的request和response对象。

 

容器提供者应该保证分发到目标servlet的请求作为原始请求发生在的同一个JVM的同一个线程中。

 

9.3 Include方法

RequestDispatcher接口的include方法可能随时被调用。Include方法的目标servlet能够访问request对象的各个方法(all aspects),但是使用response对象的方法会受到更多限制。

 

它只能把信息写到response对象的ServletOutputStream或Writer中,或提交在最后写保留在response缓冲区中的内容,或通过显式地调用ServletResponse接口的flushBuffer方法。它不能设置响应头部信息或调用任何影响响应头部信息的方法,HttpServletRequest.getSession()和HttpServletRequest.getSession(boolean)方法除外。任何试图设置头部信息必须被忽略,任何调用HttpServletRequest.getSession()和HttpServletRequest.getSession(boolean)方法将需要添加一个Cookie响应头部信息,如果响应已经提交,必须抛出一个IllegalStateException异常。

 

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

 

9.3.1 内置请求参数

除了可以用getNamedDispatcher方法获得servlet外,已经被另一个servlet使用RequestDispatcher的include方法调用过的servlet,有权访问被调用过的servlet的路径。

 

以下的request属性必须被设置:

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

 

这些属性可以通过包含的servlet的request对象的getAttribute方法访问,它们的值必须分别与被包含servlet的请求RUI、上下文路径、servlet路径、路径信息、查询字符串相等。如果随后的请求包含这些属性,那么这些属性会被后面包含的属性值替换。

 

如果包含的servlet通过getNamedDispatcher方法获得,那么这些属性不能被设置。

 

9.4 Forward方法

RequestDispatcher接口的forward方法,只有在没有输出提交到向客户端时,通过正在被调用的servlet调用。如果response缓冲区中存在尚未提交的输出数据,这些数据内容必须在目标servlet的service方法调用前清除。如果response已经提交,必须抛出一个IllegalStateException异常。

 

request对象暴露给目标servlet的路径元素(path elements)必须反映获得RequestDispatcher使用的路径。

 

唯一例外的是,如果RequestDispatcher是通过getNamedDispatcher方法获得。这种情况下,request对象的路径元素必须反映这些原始请求。

 

在RequestDispatcher接口的forward方法无异常返回之前,响应的内容必须被发送和提交,且由Servlet容器关闭,除非请求处于异步模式。如果RequestDispatcher.forward()的目标发生错误,异常信息会传回所有调用它经过的过滤器和servlet,且最终传回给容器。

 

9.4.1 查询字符串

在转发或包含请求时请求调度机制负责聚集(aggregating)查询字符串参数。

 

9.4.2 转发的请求参数

除了可以用getNamedDispatcher方法获得servlet外,已经被另一个servlet使用RequestDispatcher的forward方法调用过的servlet,有权访问被调用过的servlet的路径。

 

以下的request属性必须设置:

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方法的返回值相等,这些方法在从客户端接收到的request对象上调用,值传递给调用链中的第一个servlet对象。

(在request对象上调用从客户端接收请求的调用链中的第一个servlet对象)

 

这些属性通过转发servlet的request对象的getAttribut方法访问。请注意,即使在多个转发和相继的包含(subsequent includes)被调用的情况下,这些属性必须始终反映原始请求中的信息。

 

如果转发的servlet使用getNamedDispatcher方法获得,这些属性必须不能被设置。

 

9.5 错误处理

如果请求分发的目标servlet抛出运行时异常或受检查类型异常ServletException 或 IOException,异常应该传播到调用的servlet。所有其它的异常都应该被包装成ServletExceptions,异常的根本原因设置成原来的异常,因为它不应该被传播。

 

9.6 获得一个异步上下文对象

实现了AsyncContext接口的对象可从ServletRequest的一个startAsync方法中获得,一旦有了AsyncContext对象,你就能够使用它的complete()方法来完成请求处理,或使用下面描述的转发方法。

 

9.7 Dispatch方法

可以使用AsyncContext中下面的方法来转发请求:

dispatch(path)

这个dispatch方法的String参数描述了一个在ServletContext作用域中的路径。这个路径必须是相对于ServletContext的根路径并以’/’开头。

 

dispatch(servletContext, path)

这个dispatch方法的String参数描述了一个在ServletContext指定作用域中的路径。这个路径必须是相对于ServletContext的根路径并以’/’开头。

 

dispatch()

这个方法没有参数,它使用原来的URI路径。如果AsyncContext已经通过startAsync(ServletRequest, ServletResponse)初始化,且传递过来的request是HttpServletRequest的实例,那么这个请求分发到HttpServletRequest.getRequestURI()返回的URI。否则当最后转发时当由容器转发到request的URI。

 

AsyncContext接口中的dispatch方法可被等待异步事件发生的应用程序调用。如果AsyncContext已经调用了complete()方法,必须抛出IllegalStateException异常。所有不同的dispatch方法会立即返回并且不会提交response。

 

request对象暴露给目标servlet的路径元素(path elements)必须反映AsyncContext.dispatch中指定的路径。

 

9.7.1 查询字符串

请求调度机制是在调度请求时负责聚焦(aggregating)查询字符串。

 

9.7.2 调度请求参数

使用AsyncContext的dispatch方法调用过的servlet能够访问原始请求的路径。

 

下面的request属性必须设置:

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方法的返回值相等,这些方法在从客户端接收到的request对象上调用,值传递给调用链中的第一个servlet对象。

 

这些属性通过转发servlet的request对象的getAttribut方法访问。请注意,即使在多个转发和相继的包含(subsequent includes)被调用的情况下,这些属性必须始终反映原始请求中的信息。