1. Handling error codes and exceptions by the web.xml - Enterprise Java Content management system - Hippo CMS

1. Handling error codes and exceptions by the web.xml

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

<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

This is the way we do not advice to handle all your error pages or exceptions. E.g. 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, when for example the HST sends a HttpServletResponse.SC_SERVICE_UNAVAILABLE, or 503 as error-code. With this solution you cannot have 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-cde>404</error-code>. We however advice 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 might be meant. Look Add a catch-all sitemap item that creates a dynamic 404 page how this can be done

Now, the jsp pages cannot access HST logic. So, something like the <hst:link> tag cannot be used. You can thus 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, when exceptions do not set a correct status code by default. You must in your jsp thus add 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>

1. Handling error codes and exceptions by the web.xml

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

<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

This is the way we do not advice to handle all your error pages or exceptions. E.g. 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, when for example the HST sends a HttpServletResponse.SC_SERVICE_UNAVAILABLE, or 503 as error-code. With this solution you cannot have 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-cde>404</error-code>. We however advice 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 might be meant. Look Add a catch-all sitemap item that creates a dynamic 404 page how this can be done

Now, the jsp pages cannot access HST logic. So, something like the <hst:link> tag cannot be used. You can thus 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, when exceptions do not set a correct status code by default. You must in your jsp thus add 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>