Java Servlet Programming, 2nd Edition > 5. Sending HTML Information > 5.5 Status Codes |
5.5 Status CodesUntil now, our servlet examples have not set HTTP response status codes. We've been taking advantage of the fact that if a servlet doesn't specifically set the status code, the server steps in and sets its value to the default 200 OK status code. That's a useful convenience when we are returning normal successful responses. However, by using status codes, a servlet can do more with its response. For example, it can redirect a request or report a problem. The most common status code numbers are defined as mnemonic constants (public final static int fields) in the HttpServletResponse class. A few of these are listed in Table 5-1. The complete list is available in Appendix D.
5.5.1 Setting a Status CodeA servlet can use setStatus( ) to set a response status code: public void HttpServletResponse.setStatus(int sc) This method sets the HTTP status code to the given value. The code can be specified as a number or with one of the SC_XXX codes defined within HttpServletResponse. Remember, the setStatus( ) method should be called before the response is committed, otherwise the call is ignored. If a servlet sets a status code that indicates an error during the handling of the request, it can call sendError( ) instead of setStatus( ): public void HttpServletResponse.sendError(int sc) throws IOException, IllegalStateException public void HttpServletResponse.sendError(int sc, String sm) throws IOException, IllegalStateException The sendError( ) method causes the server to generate and send an appropriate server-specific page describing the error, letting the servlet error page have a similar appearance to other server error pages. Calling setStatus( ) on an error leaves a servlet with the responsibility of generating the error page. When the two-argument version of this method is used, the status message parameter may be included directly in the body of the response, depending on the server's implementation. This method should be called before the response is committed, otherwise it will throw an IllegalStateException. This method performs an implicit reset on the response buffer before generating the error page. Headers set before sendError( ) remain set. 5.5.2 Improving ViewFile Using Status CodesSo far, we haven't bothered calling any of these methods to set a response's status code. We've simply relied on the fact that the status code defaults to SC_OK. But there are times when a servlet needs to return a response that doesn't have the SC_OK status code when the response does not contain the requested data. As an example, think back to how the ViewFile servlet in Chapter 4, handled the FileNotFoundException: // Return the file try { ServletUtils.returnFile(file, out); } catch (FileNotFoundException e) { out.println("File not found"); } Without setting a status code, the best this servlet can do is write out an explanation of the problem, ironically sending the explanation as part of a page that is supposed to contain the file's contents. With status codes, however, it can do exactly what the DefaultServlet does: set the response code to SC_NOT_FOUND to indicate that the requested file was not found and cannot be returned. Here's the improved version: // Return the file try { ServletUtils.returnFile(file, out); } catch (FileNotFoundException e) { res.sendError(res.SC_NOT_FOUND); } The appearance of the page generated by a sendError( ) call is server dependent but generally appears identical to the server's normal error page. For the Apache/Tomcat server, this call generates the Apache server's own 404 Not Found page, complete with the Apache footer (as shown in Figure 5-1). Note that this page is indistinguishable from every other Apache 404 Not Found page, providing the servlet the ability to blend in with the server. Figure 5-1. The Apache/Tomcat "404 Not Found" page
|