Servlet Specification V2.4——SRV.5 The Response

SRV.5 The Response

response对象封装了用来从server返回client的全部信息。根据HTTP协议，这些信息经过HTTP header和request的message body二者中的任意一个从server传送至client。

 

 

SRV.5.1 Buffering

        Servlet container容许为了提升效率而缓冲发送至client的output，但不是必须的。通常状况下，server默认启用buffering，但容许servlet制定buffering参数。
        如下来自ServletResponse接口的方法容许servlet存取buffering信息：

• getBufferSize

• setBufferSize

• isCommitted

• reSet

• resetBuffer

• flushBuffer

        这些方法由ServletResponse接口提供，用来执行buffering操做，无论servlet使用的是ServletOutputStream仍是Writer。
        getBufferSize方法返回当前缓冲使用的大小。若是没有使用buffering，该方法返回0（int型）。
        Servlet能够经过setBufferSize方法设置一个首选的缓冲大小。分配的缓冲不必定要和servlet默认的大小同样，但至少要等于默认大小。这样才可使container能够重用整套的固定大小的缓冲，提供比要求的更大的缓存，若是须要的话。setBufferSize方法必须在使用ServletOutputStream或者Writer写任何内容以前被调用。若是由任何内容已经被写入或者response对象已经被提交，这个方法就会抛出IllegalStateException。
        isCommitted方法经过返回一个boolean值来代表是否有response字节已经被返回给客户端。flushBuffer方法将缓冲中的内容强制发送给客户端。
        若是response没有被commit，reSet方法能够清除buffer中的数据。servlet在reSet方法被调用前set的headers和status codes也必定会被清除。resetBuffer方法也会清除buffer中的内容，若是response没有被提交的话，resetBuffer不会清除headers和status code。
        若是response被commit后reset方法或者resetBuffer方法被调用，IllegalStateException会被抛出。Response和与它关联的buffer将不会产生变化。
        当使用了缓冲时，container必定会当即把已经装满的缓存的内容flush到client。If this is the first data is sent to the client, the response is considered to be committed 。

 

 

SRV.5.2 Headers

Servlet能够经过如下的HttpServletResponse接口的方法设置HTTP response的headers：

• setHeader

• addHeader

        setHeader方法使用给定的name和value来set header。以前的header会被新的header替换，当header集合中出现了相同的name时，新value会替代原value。
        addHeader方法使用给定的name和value来add header。若是没有header与指定的name相关联，就建立一个新的集合。
        Headers能够以int或者Date行对象存储数据。下面的HttpServletResponse接口的便利的方法容许servlet经过正确的格式来set a header：

• setIntHeader

• setDateHeader

• addIntHeader

• addDateHeader

        为了成功地回传给client，headers必须在response被commit以前set。在response提交后被set的headers会被servlet container忽略。
        Servlet程序员有责任确保response对象中的Content-Type header被正确地设置，为了由servlet生成的内容。HTTP 1.1规范中并无要求这个header必须被set到HTTP response中。若是servlet程序员没有set这个type，Servlet container必定也不会设置一个默认的content type。
        通常来讲，containers被推荐使用X-Powered-By HTTP header来发布它的实现信息。这个字段的值应当由一个或多个implementation type组成，好比“Servlet/2.4”。还有一些可选的补充信息能够经过小括号被追加到implementation type。The container should be configurable to suppress this header.
        这里有一些header的例子：

• X-Power-By: Servlet/2.4

• X-Power-By: Servlet/2.4 JSP/2.0 (Tomcat/5.0 JRE/1.4.1)

 

 

SRV.5.3 Convenience Methods

如下是HttpServletResponse提供的接口：

• sendRedirect

• sendError

        sendRedirect方法会恰当地设置headers和content body，来redirect client到一个不一样的URL，必须以相对URL路径调用此方法，然而，底层的container必须将相对路径翻译成完整的合法的URL，以便回传至client。若是传入了不完整的URL，无论什么缘由，不能被转换成合法的URL的话，方法就会抛出IllegalArgumentException。
        sendError方法会恰当地设置headers和content body，以便返回给client一个错误信息。sendError方法有一个可选的String类型的参数，能够用在error的content body里面。
        若是response尚未被commit的话，这些方法会使response commit掉，而且终止response。在这些方法被调用之后，servlet不会再输出任何东西到client。若是数据数据在这些方法被调用后写入response，它们会被忽略。
若是数据已经被写入response缓冲，但没有return、到client（response没有被commit），response 缓冲里的数据必定会被清除而且被这些方法set的数据替换。若是response被commit了，这些方法会抛出IllegalStateException。

 

 

SRV.5.4 Internationalization

        servlet应该被设置locale和response字符编码。Locale使用ServletResponse.setLocale方法设置。此方法能够重复调用；可是response提交后调用无效。若是servlet没有在页面被提交前set locale，container会启用自身的默认locale以决定response的locale，但不生成任何关于与client交互的说明 ，好比Content-Language header，若是是HTTP的话。

        见图SRV.5.4-1.png

        若是元素没有出现或者没有提供一个映射，setLocale方法会使用container依赖的映射。setCharacterEncoding，setContentType和setLocale方法能够被重复调用来改变字符编码。在servlet response的getWriter方法已经被调用或者在response被commit后调用这些方法不会对字符编码产生任何做用。调用setContentType方法设置字符编码，只有在给定的content type string 为字符集属性提供了一个值的状况下才有效。调用setLocale方法设置字符编码，只有在setCharacterEncoding方法或者setContentType都没有被使用来设置了字符编码的状况下才有效。
        若是servlet没有在ServletResponse接口的getWriter方法被调用以前或者response被提交以前指定一个字符编码，那么会使用默认的ISO-8859-1。
        Container必须经过发送给client的servlet response的writer来与locale和字符编码通信，若是启用的协议提供了这么作的方式。在HTTP的状况下，locale经过Content-Language header传达，字符编码则做为文本媒体类型的Content-Type header的一部分。须要注意的是，在servlet没有设定content-type的状况下，字符编码不能经过HTTP header被传达;然而，它仍被用于经过servlet response的writer来编码输入的文本。

 

 

SRV.5.5 Closure of Response Object

当response关闭时，container必须当即flush发往client的response的buffer中全部剩余的content。如下事件代表servlet已经知足了request的要求而且response对象即将关闭:

• servlet的service方法的终止

• responses的setContentLength方法设置的content的总长度已经被写到response

• sendError方法被调用

• sendRedirect方法被调用

 

 

SRV.5.6 Lifetime of the Response Object

        每一个response对象都只在servlet的service方法范围内有效，或者在filter的doFilter方法范围内。通常来讲，container为了不建立response对象对性能的额外开销影响而回收response对象。开发者必须注意的是，在上述范围以外维持response对象的引用可能致使不可预测的行为。