Customizing Default Error Pages

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 either within the web.xml and the web-j2ee-engine.xml deployment descriptors, or by setting the Servlet and JSP-specific properties in the Config Tool. The error page can be either a static HTML file, or a JSP, or servlet.

Procedure

Mapping Error Pages to Error Codes

To map the error page to an HTTP error response status code at design time, you use the <error-code> tag within the <error-page> tag in the web.xml deployment descriptor 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.

Open the web.xml file in the Developer Studio using the XML Editor and proceed as follows:

Select the Design tab. In the context menu of the web-app node, choose Add Child context-param-login-config error-page .
Expand the error-page node and fill in the error-code and location fields.
In the error-code field, enter the number of an existing error code.
In the location field, enter the location of the static HTML file, or the JSP, or the servlet you want to map the error code to.

Note Note

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

End of the note.

Syntax Syntax

<error-page>

 <error-code>404</error-code>

 <location>/errorPages/MyCustomErrorPage.jsp</location>

</error-page>

End of the code.

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, refer to: Defining Custom HTTP Response Status Codes.

Mapping Error Pages to Java Exceptions

Mapping error pages to Java exceptions is similar to the method used for error codes. This time you use the <exception-type> 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.

Example Example

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:

End of the example.

Syntax Syntax

<error-page>

 <exception-type>java.io.FileNotFoundException</exception-type>

 <location>/servlet/NotFoundServlet</location>

</error-page>

End of the code.

Note Note

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.

End of the note.

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 superclass of the original exception is returned to the client.

Example Example

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

End of the example.

Syntax Syntax

<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>

End of the code.

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 subclass 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.

Recommendation

We recommend 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 if 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.

End of the recommendation.

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 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

Example Example

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:

End of the example.

Syntax Syntax

<%@ 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>

End of the code.

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

Syntax Syntax

<%@ 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>

End of the code.

Configuring Error Pages for Specific Error Conditions

The following table lists two AS Java-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.

More information: Java System Properties