Quick Recap: Chapters 25 to 29

Let us now quickly recap what we learnt in the previous few chapters on Servlet Exception Handling…

Introduction to Servlet Exception Handling:

• Exception Handling is a powerful feature of the J2EE Technology and we can use it to handle unexpected behavior in our code
• There are categories of error codes that give us a fair idea of what went wrong. For ex: error codes 5XX signifies that something was wrong on the server side

The sendError Method:

• You can use the sendError method of the HttpResponse to send error messages to the browser
• It takes two parameters – the error code and a error message
• You can override the default behavior of the method and have custom code to handle exceptional cases
• The sendError method will set the appropriate headers and content body for an error message to return to the client.
• Using this method will commit the response (if not already committed) and terminate it. The data stacked in the output stream to the client before calling sendError() method is ignored

The setStatus Method:

• The setStatus method sets the status code for a given response
• Use this method, instead of sendError, when there is no exception or serious error
• If there is a serious error, the sendError method should be used; otherwise use setStatus.

The WebApp Log:

• Log files get written with the sequence of events handled by the Servlet
• You can write custom content into the log file in order to help us handle exceptional situations better

Key Terms we learnt in this section are:

• exception
• sendError()
• setStatus()
• Logging
• Status codes
• Error codes

Previous Chapter: Chapter 29 - WebApp Log

Next Chapter: Self Test - Chapters 25 to 29

Chapter 28: The setStatus Method

In the previous chapter, we saw the sendError method. We saw how Tomcat implements it and we saw a wrapper method that used it but did some handling for custom error messages. Well, in this chapter, we are going to see the twin brother of the sendError method, the setStatus method.

So, lets get started…

The setStatus Method

The setStatus method sets the status code for a given response. Use this method, instead of sendError, when there is no exception or serious error (such as a blocked or a page inaccessible to the user). If there is a serious error, the sendError method should be used; otherwise use setStatus. Like the sendError method, using this method clears the buffer, but leaves cookies and other headers unmodified.

Let us now take a look at how Tomcat has implemented the setStatus method.

Code:

/**
* Set the HTTP status and message to be returned
* with this response.
*
* @param status The new HTTP status
* @param message The associated text message
*
* @deprecated As of Version 2.1 of the Java Servlet
* API, this method has been deprecated due to the
* ambiguous meaning of the message
* parameter.
*/
public void setStatus(int status, String message) {

if (included)
return; //Ignore any call from included servlet

this.status = status;
this.message = message;

}

As you can see in the code above, this method has been deprecated because the message functionality isn't reliable. The setStatus method will remain (the one taking only a status code), but without a message parameter in a future version, Maybe.

However, you can always write a wrapper to use the setStatus method effectively. (Just like we did for the sendError method)

Code:

/**
* statusManager Method.
*/
void checkCarStatus(HttpServletResponse response)
throws ServletException
{
if( !isValid(carName) )
{
response.setStatus(response.SC_BAD_REQUEST);
} else if( !isValid(carModel) )
{
response.setStatus(response.SC_BAD_REQUEST);
} else if( !isValid(carMakeYear) )
{
response.setStatus(response.SC_BAD_REQUEST);
} else if( !isValid(creditCardNumber) )
{
response.setStatus(response.SC_BAD_REQUEST);
} else
{
response.setStatus(response.SC_OK);
}
}

The code above is pretty straight forward. I suppose this can be used in a car repair garage. We first check if the cars name is valid and then check if the cars model is valid and then check its manufacture year. We also check the credit card number of the customer (because we need to get paid right) and if all these are valid, we set a OK response, else we set a bad request response. It's a simple implementation and you can alter it anyway you want, as long as it serves your purpose and uses the setStatus method, we are good…

The same status codes that are used for the sendError method can be used for the setStatus method, too. The primary difference is that the former prevents any further response to the client and throws an exception if you try. This is not so for the latter. There is one point of confusion with the setStatus method. The specification says the buffer is cleared when called. In other words, you should set this first before you send anything back to the client. However, I looked in Tomcat and did not observe the buffer being cleared. The following snippet:

out.println("pre setStatus message.");
response.setStatus(HttpServletResponse.SC_OK);
out.println("post setStatus message.");

produced this:
pre setStatus message.
post setStatus message.

Exam Trivia:
Containers don't always follow the specifications! As you can see, Tomcat does not clear the buffer as the specification says. The specification doesn't make sense as of this moment because, the way Tomcat implemented it is better. However, since other containers may follow the specification here and the exam will be based on the specification, assume that is how it actually works.

Previous Chapter: Chapter 27 - sendError Method

Next Chapter: Chapter 29 - WebApp Log