Customizing the Look of Error Messages in JSP
Date: Feb 22, 2002
The Web application framework provides a simple way to customize the look of error messages that can occur while users are accessing your pages. As you know, error messages are thrown because of syntax problems in your code, because of database connection problems, or just because the user has left out one or more required fields while filling out a form.
The application framework enables you to customize any of these error messages. You can even hide them from the user's view entirely, if you want. This enables you to maintain a consistent look and feel throughout an application, even when those dreaded error messages are thrown.
Creating an Error Page
The first step in outputting errors is to create an error page. Take a look at the error1.jsp page shown in Listing 1.
Listing 1—error1.jsp—A Simple Error Page
<%-- Name: error1.jsp Author: Drew Falkman (iam@drewfalkman.com) Description: simple sample error page Created: 7/8/01 --%> <%-- set page as error page --%> <%@page isErrorPage="true" %> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Error Page</title> </head> <body> <h1>Error!!</h1> You seem to have encountered an error in an otherwise perfect Web Site. If you would like to report this error, you may email the site administrator, or call him directly. </body> </html>
There is only one distinction between this page and a regular error page:
<%@page isErrorPage="true" %>
This line allows the page to accept and display any exception information from the page that sent it. So, for example, if a file called whatever.jsp has an exception, and it is told to load error1.jsp as the error page, error1.jsp obtains all the exception information from whatever.jsp.
Setting Error Pages with the page Directive
Within each page, you have the power to define the error page. To do so, use the errorPage attribute of the page directive:
<%@page errorPage="error1.jsp" %>
This tells the page that if an exception occurs, it should automatically redirect to error1.jsp. To use this method, you must remember to enter this line of code in all your pages (you could also use the include directive to include this in the header). You also don't have the ability to send different types of errors to different error pages.
NOTE
Using error pages with the page directive works for other errors besides compilation errors. If you have any invalid syntax, such as missing semicolons, nonclosed JSP tags, or other errors in code syntax, you still get the normal error and stack trace.
Setting Error Pages by Using the web.xml Template
Suppose you want to define a page to go for 404 errors that give a site search and abbreviated site map, a page to go to for java.SQL.exceptions that automatically e-mails the database administrator, or another custom error page based specifically on the type of error. The web.xml template lets you do this. Take a look at the revised web.xml template in Listing 2.
Listing 2—web.xml—Defining Error Pages
<web-app> <display-name>Orange Whip Studios</display-name> <description>JRun Web Application Construction Kit Demo</description> <context-param> <param-name>CompanyName</param-name> <param-value>Orange Whip Studios</param-value> </context-param> <context-param> <param-name>Datasource</param-name> <param-value>ows</param-value> </context-param> <error-page> <error-code>404</error-code> <location>/19/404.html</location> </error-page> <error-page> <exception>java.sql.Exception</exception> <location>/19/sqlException.jsp</location> </error-page> </web-app>
Most of this file is similar to the web.xml template. However, there are a few new tags to look at. The main tags used in defining error pages are the <error-page> tags. Between <error-page> tags, you can have one of two sets of subtags. The first combination defines error pages based on Hypertext Transfer Protocol (HTTP) error types:
<error-page> <error-code>404</error-code> <location>/19/404.html</location> </error-page>
The first subtag is <error-code>. This is where you place the number of the code your error page will respond to. We are all familiar with the 404 Not Found error from trying to find Web pages that no longer exist. So, simply enter 404 between this set of tags. Next, you supply the location of the error page to use by using the <location> subtag. The path entered should be an absolute path that starts in the application root. Here, we entered //19/404.html. When the server receives a 404 error, it looks for this page instead of giving the usual JRun exception error.
TIP
Compilation errors and Java exceptions are always 500 Internal Server errors. By defining an error page for this error type on your production server (that is, the real live version of your site), you should be able to effectively hide just about any JRun exception thrown to your users. This is obviously not a good excuse for poor debugging, but it can keep you from looking bad. Make sure you are logging or e-mailing the relevant people when these errors occur from within your error page.
The other subtags used allow us to specifically define error pages for specific types of errors. This can be a valuable technique for giving the users intelligent error messages that might help them to solve problems on their own:
<error-page> <exception>java.sql.Exception</exception> <location>/19/sqlException.jsp</location> </error-page>
This works almost exactly like the <error-code> approach, except that we are referencing the exception type (within the <exception> tags) instead of the HTTP error code. The error page's location is still placed between the <location> tags. Here, any SQL problems will be thrown to a specific page.
TIP
Error pages can be invaluable debugging tools. On your error pages, you can output information that is specific to the type of exception that occurred, including request or other parameters, path information, and any other type of data that can help you pinpoint the problem.
It might be helpful to create a few debugging templates and XML definitions to use in new applications when you begin building them. This can make the process smoother, and setting the 500 errors to a page that gives more information than the Java error message and stack trace can greatly improve the speed and quality of your development.