The Request
request对象囊括了客户端请求的所有信息。在HTTP协议中，这些信息放在request的HTTP头部和消息体中从客户端传到服务端。
1. HTTP 协议参数
Servlet请求参数作为请求的一部分，通过客户端以字符串的方式传给servlet容器。当请求是一个HttpServletRequest对象，并且满足一些条件，容器会从URI查询字符串和POST形式的数据中获取。
参数被以name-value的键值对存储。对于给定的参数名可以对应多个参数值。下面这些ServletRequest接口的方法可以用来获取参数：
- getParameter
- getParameterNames
- getParameterValues
- getParameterMap
getParameterValues 方法返回一个包含与键名关联的值的字符串数组。getParameter 方法返回的值一定是getParameterValues 方法返回的字符串数组的第一个值。getParameterMap方法返回request的参数的java.util.Map对象，这个对象包含了作为key的参数名，和对应的值。
查询字符串和post实体中的数据会汇总到request参数集合中。查询字符串的数据排在post实体数据之前。比如，一个请求有一个查询字符串a=hello和一个post数据体a=goodbye&a=world, 结果集将会按以下顺序排列：a=(hello, goodbye, world)。
属于Get请求一部分的路径参数并不通过这些API来暴露。它们必须从getRequestURI 方法或者 getPathInfo 方法返回的字符串中解析。
1.1 可用的参数
在表单数据被放到参数集中之前，下列条件必须要满足：
- 请求是一个HTTP或者HTTPS请求。
- HTTP方式是POST。
- content type是 application/x-www-form-urlencoded。
- servlet在请求对象上调用一次任意一个getParameter系列的方法。
如果这些条件不满足并且post表单数据不包括在参数集中，servlet也可以通过请求对象的输入流获取到post数据。如果这些条件满足，post数据不再需要直接从请求对象的输入流中获取。
2. 文件上传
如果请求是 multipart/form-data 类型并且servlet处理请求的方式是使用@MultipartConfig，HttpServletRequest对象能通过下面的方法获取multipart请求的各个部分：
- public Collection<Part> getParts()
- public Part getPart(String name)
每一部分都提供获取头部、相关content-type的方法，并且也能通过getInputStream方法获取到content。
对于把form-data作为Content-Disposition的部分，但是没有一个文件名，使用part的名字，可以通过HttpServletRequest的getParameter/getParameterValues方法获取part的字符串值。
3. 属性
属性是与一个请求相关的对象。属性可以由容器来设置表达一些通过API不能表达的信息，或者由servlet设置来与其它servlet的交流信息(通过RequestDispatcher)。
属性通过下列ServletRequest接口的方法来获取：
- getAttribute
- getAttributeNames
- setAttribute
一个属性名只能有一个属性值。
对于属性名字的命名规范，以java和javax为前缀的名字已经作为这份文档中的保留关键字，不能使用。同样的，已sun，com.sun开始的字符串也是被Sun MicroSystem作为保留关键字。建议属性集合中的所有属性命名应该与Java Programming Language Specification给包命名建议的保留域命名规范一致。
4. Headers
一个servlet可以通过HttpServletRequest接口的下述方法获取HTTP头部:
- getHeader
- getHeaders
- getHeaderNames
getMethod方法返回一个指定名字的头部。HTTP请求中，相同的名字可以关联多个头部，比如 Cache-Control头部。如果相同的名字有多个头部，getHeader方法返回request中的第一个头部。getHeaders方法允许获取一个头部名字相关的所有头部值，并返回一个字符串对象的枚举对象。
头部可以包含代表int或者Date类型的字符串。下列HttpServletRequest接口的方法可以获取对应的数据：
- getIntHeader
- getDataHeader
如果getIntHeader方法不能把头部值转换为int，将会抛出NumberFormatException异常。如果getDateHeader不能把头部转换为Date对象，将会抛出IllegalArgumentException异常。
5. 请求路径元素
引导一个servlet服务一个客户端请求的路径由很多重要的部分组成。下列元素从请求URI路径中获得并且通过请求对象暴露。
- Context Path 是与当前servlet所属ServletContext 的前缀路径。如果这个上下文是基于Web服务器URL名称空间的默认上下文，这个路径将会是空串。否则，如果这个上下文在根服务器名称空间不作为根路径，那么这个路径以'/'开头，但是不以'/'结尾。
- Servlet Path 直接对应相应这次请求的映射。这个路径由'/'符号开头，但是请求匹配'/*'或者""模式的情况除外。
- PathInfo 不是Context Path或者Servlet Path的一部分。如果没有额外的路径它就是null，否则就是一个以'/'开头的字符串。
HttpServletRequest接口中的下列方法可以获取到这些信息：
- getContextPath
- getServletPath
- getPathInfo
需要注意的是除了请求URI和路径部分之间的URI编码差异，下面的等式总是成立的：
requestURI = contextPath + servletPath + pathInfo
为了说明上面几点，请看下面几个示例：
Table5-1 Example Context Set Up
| Context Path | /catalog |
|---|---|
| Servlet Mapping | Pattern: /lawn/* Servlet: LawnServlet |
| Servlet Mapping | Pattern: /garden/* Servlet: GardenServlet |
| Servlet Mapping | Pattern: *.jsp Servlet: JSPServlet |
Table5-2 Observed Path Element Behavior
| Request Path | Path Elements |
|---|---|
| /catalog/lawn/index.html | ContextPath: /catalog Servletpath: /lawn PathInfo: /index.html |
| /catalog/garden/implements/ | ContextPath: /catalog Servletpath: /garden PathInfo: /implements |
| /catalog/help/feedbach.jsp | ContextPath: /catalog ServletPath: /help/feedback.jsp PathInfo: null |
6. 路径转换方法
API中有两个简便方法让开发者获取与一个特定路径对应的文件系统路径。这两个方法是：
- ServletContext.getRealPath
- HttpServletRequest.getPathTranslated
getRealPath 方法传入一个字符串参数，返回一个与路径对应的本地文件系统上的文件路径字符串。
getPathTranslated 方法翻译出请求中pathInfo的真正路径。
在servlet容器不能为这些方法决定一个合法文件路径的情况下，比如当Web应用是在归档文件中执行，在不能本地访问的远程文件系统，或者数据库中，这些方法必须返回null。
调用getRealPath()时，仅当容器解压它们当中的JAR文件时，JAR文件中META-INF/resources目录下的资源必须要考虑到，这种情况下，必须返回一个未解压文件的路径。
7. Cookies
HttpServletRequest接口提供了getCookies方法获取请求中cookie的一个数组。这些cookie是客户端在每次请求中发送到服务端的数据。通常客户端发回cookie的部分信息仅仅是cookie名字和值。当cookie发送给浏览器时，能设置的一些其他cookie属性，比如注释通常不会被发回。规范也允许cookie是HTTPOnly cookies。 HttpOnly cookie告诉客户端不应该把cookie暴露给客户端的脚本代码(除非知道寻找这个属性，否则不会被过滤)。HttpOnly cookie的使用缓解了某种跨域脚本攻击。
8. SSL属性
如果一个请求在安全协议上传输，比如HTTPS，那么这个信息就必须通过ServletRequest接口的isSecure方法来暴露。这个Web容器必须把下列属性暴露给servlet程序员：
Table8-1 协议属性
| Attribute | Attribute Name | Java Type |
|---|---|---|
| cipher suite | javax.servlet.request.cipher_suite | String |
| bit size of the algorithm | javax.servlet.request.key_size | Integer |
| SSL session id | javax.servlet.request.ssl_session_id | String |
如果请求中带着SSL证书，servlet容器必须要把java.security.cert.X509Certificate类型对象数组传递给servlet程序员，并且通过javax.servlet.request.X509Certificate的ServletRequest属性访问到。
数组的顺序按信任度升序排序。序列中的第一证书是客户端设置的，接下来的一个是用来鉴定第一个的，剩下的依次类推。
9. 国际化
客户端可以选择告诉Web服务它们期望response返回的语言。这个信息可以使用Accept-Language头部，并结合HTTP/1.1规范中的其它机制来与客户端沟通。ServletRequest接口提供了下列方法来决定发送者期望的区域：
- getLocale
- getLocales
getLocale方法将返回客户端期望接收内容的首选区域。RFC 2616（HTTP/1.1）的14.4章提供了更多的信息说明了Accept-Language头部怎样被解析来决定客户端首选的语言。
getLocales方法将返回Locale对象的一个枚举，它们将以首选区域开头并按照降序排序。这些区域必须是客户端可以接受的。
如果客户端没有指定首选区域，getLocale方法返回的locale必须是servlet容器的默认值，并且getLocales方法必须包含默认locale的单个Locale元素的枚举。
10. 请求数据编码
当前很多浏览器并不发送带Content-Type头部的字符编码标识符，它会把字符编码的决定留在读取HTTP请求的时候。如果客户端没有指明编码，容器用来创建请求读和解析POST数据的默认编码必须是"ISO-8859-1"。然而，为了提示开发者客户端没有成功发送一个字符编码，容器中getCharacterEncoding方法会返回null。
如果客户端没有设置字符编码，并且请求数据使用了不同编码而不是上述的默认编码，程序将会出现中断。为了纠正这种状态，一个新的方法setCharacterEncoding(String enc) 被添加到ServletRequest接口。开发者调用这个方法能重写容器提供的字符编码。这个方法必须在解析request中任何post数据或者读任何输入之前调用。一旦数据已经被读取，调用这个方法不会影响它的编码。
11. 请求对象的生命周期
每一个请求对象仅在一个servlet的service方法范围内或者一个filter的doFilter方法范围内有效，除非异步处理对组件可用并且request对象上调用startAsync方法。在有异步处理的场景，请求对象直到AsyncContext调用complete都是有效的。容器通常都会重复利用请求对象，以避免创建请求对象的性能消耗。开发者必须要意识到，维护startAsync在上述范围之外没有被调用的请求对象的引用这种做法并不推荐，因为它有可能得到不确定的结果。
翻译自 Java Servlet Specification
Version 3.0 Rev a
Author:Rajiv Mordani
Date: December 2010
