This article covers a Bloomreach Experience Manager version 13. There's an updated version available that covers our most recent release.

Handle Error Codes and Exceptions in web.xml

In your site application's web.xml, you can configure error-page elements that act upon some error-code or exception-type. Typically, you might configure the following at the end of your web.xml:

<error-page>
  <error-code>400</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage400.jsp</location>
</error-page>
<error-page>
  <error-code>401</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage401.jsp</location>
</error-page>
<error-page>
  <error-code>403</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage403.jsp</location>
</error-page>
<error-page>
  <error-code>404</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage404.jsp</location>
</error-page>
<error-page>
  <error-code>500</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage500.jsp</location>
</error-page>

Be Aware

Not all error codes and exceptions should be handled this way. For example, 404 (Page Not Found) pages can be better handled with a catch-all sitemap item.

The web.xml error pages should be used as a last fallback solution, for example when the HST sends a HttpServletResponse.SC_SERVICE_UNAVAILABLE, or 503 as error-code. With this solution, you cannot use any tooling from the HST, as it is out of the scope of the HST request processing. Also during the rendering of, for example, the above configured errorPage500.jsp, the HstRequestContext is already disposed hence cannot be used properly. The other described error handling pages do get created / handled in the context of HST request processing, during which you thus also have access to a live HstRequestContext object.

When you have a URL that cannot be mapped to any sitemap item, a org.hippoecm.hst.core.container.ContainerNotFoundException is thrown which falls through all the way to the web container to finally match the web.xml configured <error-code>404</error-code>. However, it is recommended to always have a catch-all sitemap item that catches all the URLs that cannot be matched. This sitemap item can in turn create a nice 404 error page, and possibly do something like a search with the current URL to suggest pages that the user might have been looking for.

Now, the JSP pages cannot access HST logic. So, something like the <hst:link> tag cannot be used. You can therefore not have different links to for example css for local development and on production deployment, which you normally want to have as on production you might want to have URLs without context path.

Also, in case exceptions do not set a correct status code by default, you must add in the JSP something like response.setStatus(404):

Example errorPage404.jsp:

<%@ page language="java" contentType="text/html; charset=UTF-8"
    pageEncoding="UTF-8" isErrorPage="true" %>

<% response.setStatus(404); %>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>404 error</title>
  </head>
  <body>
    Page not found!!!
  </body>
</html>
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?