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