Recipe 9.3 Sending an Error from a Servlet

Problem

You want to use a servlet to manually send a response error to the client.

Solution

Use the javax.servlet.HttpServletResponse.sendError( ) method.

Discussion

The javax.servlet.http.HttpServletResponse class has two versions of the sendError( ) method: one that takes an int parameter representing the HTTP response code (such as 500), and the other taking an int parameter and a String error message. The String parameter is used to display a message to the client if an error page is not configured for that particular response code. Example 9-3 shows the skeleton of a servlet whose commented sections describe various scenarios for sending response codes.

Use the two-parameter method version, so that a meaningful message is displayed in the event that the application has not configured an error page for a particular error code.

Example 9-3. Sending a response code from a servlet

 package com.jspservletcookbook; import javax.servlet.*; import javax.servlet.http.*; public class Sender extends HttpServlet {     public void doPost(HttpServletRequest request,     HttpServletResponse response) throws ServletException,      java.io.IOException { /* if the servlet tries to access a resource and finds out that the client is not authorized to access it - "401 Unauthorized" */  //response.sendError(401,         //  "You are not authorized to view the requested component");  /* if the servlet tries to access a resource that is forbidden for this client and there is no further information on it - "403 Forbidden" */  //response.sendError(403,         //  "You are forbidden from viewing the requested component; no         //further information");  /* if the servlet tries to access a resource that is not found given the client's provided URL - "404 Not Found" */  //response.sendError(404,         //"The server could not find the requested component");  }       public void doGet(HttpServletRequest request, HttpServletResponse response)     throws ServletException, java.io.IOException {     doPost(request,response);   } } 

If an error page is configured for the error code that you specified in the sendError( ) method, the web container invokes the error page mapped to that error code. If the error code does not have an error page configured for it in web.xml , the web container generates a default HTML page containing the message you included as the String parameter to the sendError( ) method, as in Figure 9-3. The server leaves cookies and other response headers unmodified when it returns this HTML to the client.

If you call sendError( ) after already committing the response to the client (such as when the response buffer, a temporary storage location for the response data, is full and "auto-flushed"), sendError( ) throws a java.lang.IllegalStateException . You can set the buffer size with the javax.servlet.ServletResponse.setBufferSize( ) method.

Figure 9-3. Server response to HttpServletResponse.sendError when there is no error page is configured for the error code

See Also

Recipe 9.1 on declaring exception handlers in the deployment descriptor; Recipe 9.2 on developing a servlet error handler; Recipe 9.4 on sending an error from a JSP; Recipe 9.5 on using JSPs to handle errors; Recipe 9.6 on declaring in a JSP that another JSP will handle its exceptions; Chapter 1 on the deployment descriptor; the Java servlet specification, which covers error handling in Chapter SRV.9.9: http://java.sun.com/products/servlet/index.html.