JSP Server-Side Error Handling, Part 2

by Richard Shaler

In "JSP Server-Side Error Handling, Part 1," I described how to add graceful error handling to your JSP applications. I presented a design that sent an error message to the input form when an error occurred, leaving the form available for user action. In this second installment, I present a different design where the application replaces the input form with a special JSP error page that you create and customize for the application.

Using a separate error page, instead of sending an error message to the offending input form, offers the benefit of displaying an entire page dedicated to the presentation of error information. By using a few built-in JSP directives, you can add this type of server-side error handling to your applications. To illustrate how you can use the JSP error page, I'm including a simple working sample application, comprised of one HTML file (wgroup04.html) and two JSP files (wgroupjsp04.jsp and wgroupErrorPage.jsp).

The Sample Application

The sample application displays a customer list where the customer name matches (it uses the SQL LIKE predicate) the name submitted by the user. The input form contains one text field where the user can key a full or partial customer name:

I couldn't access my iSeries system at the time of this writing, so I created and populated the QCUSTCDT table in DB2 for Windows and used the DB2 Windows JDBC driver instead of the iSeries JDBC driver. However, the JSP code to use the iSeries JDBC driver is included in the source code as commented statements, so you can easily convert the application to run on the iSeries.

Now, what happens if the user doesn't enter a name at all? Without any type of error handling, the application would present some type of cryptic information to the browser that would most likely frustrate a user. This is where the special JSP error page helps out. For the sample application, I created a JSP error page that displays some useful information about the error:

How It Works

Before I get into the error handling, let me explain the basic flow of the application. First, an input form (wgroup04.html) is presented to the user so he can enter a customer name. The input form calls a JSP (wgroupjsp04.jsp) that processes the request and displays the output. The call to the JSP occurs through the action and method attributes of the HTML form tag:

<form action="/examples/rastests/wgroupjsp04.jsp" method="get">

The JSP processing page (wgroupjsp04.jsp) retrieves the customer name from the input form through the getParameter method of the implicit JSP request object:

custName = request.getParameter("name"); 

To handle the submission of a blank customer name, I used the built-in JSP error page feature. The JSP (wgroupjsp04.jsp) used in the sample application contains some conditional code that detects a null or blank name submission. If detected, the JSP throws an exception, which automatically forwards control to the error page. To activate the error page feature you only need to do three things: add a special JSP page directive to the JSP wherever an error can occur, create a custom error page to display error information to the user, and then include a special JSP page directive in the custom error page.

The following list describes the steps you need to take to add this feature to your application. I performed these steps when I created the sample application. As you review the steps it would be helpful to have the source code for the application available. Download the package included in this article and print out each of the three source members so you can see things in context. A few of the modifications I made aren't directly related to generic JSP error page processing, but I used them to add additional information to my error page. I identify these steps as optional, but you should examine them to learn more about JSP technology.

1. Add a JSP page directive with the errorPage attribute to the main JSP (in this case wgroupjsp04.jsp) and specify the name of the page (in this case wgroupErrorPage) that is to display when an error is raised:

<%@ page errorPage="wgroupErrorPage.jsp" %>

2. Trap the error. In the error trap, throw an exception passing a message to the exception object:

throw new Exception("No name specified. Go back and resubmit");

3. (This step is optional.) In the sample application, I want to pass the offending page name contained in the Universal Resource Identifier of the page that causes the error (wgroupjsp04.jsp). To retrieve the URI, I use the getRequestURI method of the request object. I could append the URI to the message text I specified in the throw statement, but, instead, I pass it as a separate item. I do this through the setAttribute method of the JSP request object. The setAttribute method uses two parameters. The first parameter is a string that specifies the attribute name. The second parameter is the value you want to assign to the attribute. Here's the code:

request.setAttribute("faultPage", request.getRequestURI());

I call the attribute faultPage, since it's the page that caused the error. The power of the setAttribute method is that other JSPs and servlets in your application can access the attribute's value. (It's somewhat similar to a local data area that iSeries programmers use.) This is how the value of faultPage can be displayed by the errorPage (see step 6).

4. Create the error page specifying a JSP page directive with the isErrorPage attribute set to true:

<%@ page isErrorPage="true" %>

This identifies the page as an error page and allows a JSP to reference it in the errorPage attribute (see step 1).

5. Retrieve the error message thrown by the JSP (see step 2) with the getMessage method of the JSP exception object. The sample application uses the following code:

Error message: 
<b><font color="red">
<%= exception.getMessage() %> 

</font></b><br><br>

6. (optional) Retrieve the offending page's name through the pageFault attribute (the attribute set in step 2) using the getAttribute method. The sample application uses the following code:

Error in page:
<b>
<%= request.getAttribute("faultPage") %>
</b><br><br>

7. (also optional) If you want to display the StackTrace (all the java error codes) of the error condition, use the following code:

<%
// get the detail from the implicit exception object
StringWriter sw = new StringWriter();
PrintWriter pw = new PrintWriter(sw);
PrintWriter jw = new PrintWriter(sw);
exception.printStackTrace(pw); 
String errorDetail = sw.toString();
%>
The gory detail: <br><br> 

<%= errorDetail%>

Although I used seven steps, only four (1, 2, 4, and 5) are required to add the JSP error page feature to your application.

Error Conditioning

There's no reason to allow your application to present unexpected cryptic error messages when JSP technology offers such easy-to-implement error handling features. You can design well-behaved, user-friendly applications with very little effort. Whether you use the method presented in part one of this series or the more generic method presented here, you will increase your application's ability to handle errors and increase user satisfaction. So go ahead, enjoy more error conditioning in your applications.