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對象的引用可能致使不可預測的行爲。