Custom Error Pages 

Use

You can control error handling in your Web applications by customizing the response that is returned to the user if an error occurred. You do this by declaring custom error pages to respond to certain errors in the web.xml deployment descriptor of your application.

Features

There are two cases in which the client gets an error response indicating an error condition:

·        If the application or the Web Container return an error response (indicated by an HTTP response status code) using the request.sendError() method.

·        If the application or the Web Container throw a Java exception.

You can specify that a particular error page is returned to the client if a certain error condition occurs. Configuration of custom error pages is enclosed within the <error-page> tags. Using the <location> sub-tag, you give the path (relative to the application root) to the error page itself (if the error page is a servlet, then the URL mapping for it is used). The error page can be either a static HTML file, or a JSP or servlet.

Error Pages Mapped to Error Codes

To map the error page to an HTTP error response status code, you use the <error-code> tag within the <error-page> tag to specify the error code to respond to. Such an error page is returned to the client only if the sendError method of the ServletResponse is invoked. Using this function, for example, you can provide friendly messages to end users in the case of 404 “File Not Found” or 500 “Internal Server Error” error responses.

Here is an excerpt of a web.xml descriptor that maps the custom error page MyCustomErrorPage.jsp to the 404 error response code:

<error-page>  <error-code>404</error-code>  <location>/errorPages/MyCustomErrorPage.jsp</location> </error-page>

 

You can also map a custom error page to respond to any custom error response code you have defined and use on your system. For more information about defining custom error response codes, see Defining Custom HTTP Response Status Codes.

Error Pages Mapped to Java Exceptions

Mapping error pages to Java exceptions is similar to the method used for error codes. This time you use the <exception> tag to specify the fully-qualified class name of the exception that this error page (identified by the path you provide in the <location> tag) maps to.

Here is an excerpt of a web.xml descriptor that maps the NotFoundServlet servlet as an error page that is returned if the java.io.FileNotFoundException occurs:

<error-page>  <exception>java.io.FileNotFoundException</exception>  <location>/servlet/NotFoundServlet</location> </error-page>

Note that the general servlet mapping /servlet/* is used in the example above to specify that the NotFoundServlet must be returned in the case of FileNotFoundException error condition.

If an exception is thrown and there is no explicit mapping for this exception, the Web Container searches all the exception types that appear in the error pages declarations to find the closest match within the class hierarchy of the exception that is thrown. The error page mapped to a super-class of the original exception is returned to the client.

Assume you have the following error page definitions in your web.xml:

<error-page>     <exception-type>java.lang.Exception</exception-type>     <location>/customerrors/SomeProblem.jsp</location> </error-page> <error-page>     <exception-type> java.io.FileNotFoundException</exception-type>     <location>/customerrors/NotFoundProblem.jsp</location> </error-page>

 

Bear in mind that the class hierarchy is the following:

java.lang.Throwable → java.lang.Exception → java.io.IOException → java.io.FileNotFoundException and java.lang.Throwable → java.lang.Exception → java.io.IOException → java.net.UnknownHostException

then if:

·         java.io.FileNotFoundException (or a sub-class thereof) is thrown, the NotFoundProblem.jsp is returned;

·         java.net.UnknownHostException is thrown, the SomeProblem.jsp is returned as java.lang.Exception is the closest match in the class hierarchy that has an error page mapped to it.

It is recommended that you use a separate error page for each error condition that you need to handle in your application. Mapping error pages to general exceptions such as java.lang.Throwable, or java.lang.Exception without mapping error pages to their subclasses is not good practice. Note also that in case you have mapped an error page to java.lang.Throwable, this page is not invoked in the case of java.lang.OutOfMemoryError and java.lang.ThreadDeath errors.

Accessing Request Attributes in Error Pages

If the error handling page is either a JSP or a servlet, then you can use several error-related request attributes in it to provide detailed information about the error condition. This can be very useful for debugging purposes, or in cases where the supportability of your applications is of top priority. The following table lists the attributes that are available along with their types:

Attribute	Type
javax.servlet.error.status_code	java.lang.Integer
javax.servlet.error.exception_type	java.lang.Class
javax.servlet.error.message	java.lang.String
javax.servlet.error.exception	java.lang.Throwable
javax.servlet.error.request_uri	java.lang.String
javax.servlet.error.servlet_name	java.lang.String

This is an example of an error JSP page that uses request attributes to print the status code and error message returned to the client:

<%@ page language="java" %> <html>    <head>       <title>          This is a test error JSP       </title>    </head>    <body>       <h1>An Application Error has occurred</h1>   <p>     <b>The status code is:</b> <%= request.getAttribute("javax.servlet.error.status_code") %><br>     <b>The error message again is:</b> <%= request.getAttribute("javax.servlet.error.message") %><br> </p>    </body> </html>

 

The following is an example of an error JSP page that prints the class name of the exception it responded to:

<%@ page language="java" %> <html>    <head>       <title>          Error page       </title>    </head>    <body>       <h1>          An exception has occurred in your application       </h1>   <p> The exception class is: <%= request.getAttribute("javax.servlet.error.exception") %><br> </p>        </body> </html>

 

 

Configuring Error Pages for Specific Error Conditions

The following table lists two J2EE Engine-specific error conditions and the properties that you can use to customize the error pages that are returned to the client:

Default Error Message	Error Condition	Property
Application stopped!	The application that you have requested is stopped at the moment.	Use the ApplicationStoppedFile property of the Web Container Service to specify the path to your error page.
Dispatcher running but no server connected.	The dispatcher is started and able to receive client requests but there is no server attached to it to process the requests.	Use the ServiceUnavailableResponse property of the HTTP Provider Service on the dispatcher to specify the path to your error page.