Simple Exception Handling

This page describes basic strategies for handling exceptions in Bloomreach Content components. For advanced or fine-grained exception handling, see Advanced Exception Handling.

When you implement an HstComponent, exceptions can occur. These may include java.lang.RuntimeException, java.lang.Throwable, or domain-specific exceptions. For example, you might expect to retrieve a content bean for a detail page, but the corresponding HippoBean is null. Or, you might expect a document of type NewsItem, but receive an AgendaItem instead.

You must decide how to handle unexpected errors based on your use case. For example, if a component responsible for displaying related documents fails, you may choose to log a warning rather than return a 404 error for the entire page. However, if the main document for the page is missing, returning a 404 may be appropriate. In this case, you can either display an empty section where the document would appear or forward the request to a dedicated 404 error page.

This page provides examples of simple exception handling approaches. For more advanced scenarios, refer to Advanced Exception Handling.

Info:
Use Case 1: Log a warning or info message for non-critical unexpected behavior.

Suppose you retrieve a document and attempt to look up a child bean containing related documents. If the child bean is missing, you may not want to return a 404 error, especially if the main document is present. In this case, log a warning and continue processing.

Example:

public class Home extends BaseHstComponent {
    public static final Logger log = LoggerFactory.getLogger(Home.class);
    @Override
    public void doBeforeRender(HstRequest request, HstResponse response)
                                            throws HstComponentException {
        HippoBean myDocument = this.getContentBean(request);
        MyRelatedBean myRelatedBean = myDocument.getBean("related",
                                                      MyRelatedBean.class);
        if(myRelatedBean) {
            log.warn("No related bean found where we expected one");
            // continue
   }
}

Info:
Use Case 2: Handle a critical error or exception.

If you cannot find the main document to display, you may need to return a 404 error. There are several ways to do this:

hstResponse.sendError(int sc);
hstResponse.setStatus(int sc);
hstResponse.forward(path);
HstResponseUtils.sendRedirect(hstRequest, hstResponse, path);

The following sections describe each option.

1. `response.sendError(int sc);`

This method sends an error code to the servlet container but does not stop the HstRequestProcessing. All other HstComponents will continue to execute. You can only handle the error code in your web.xml. For details, see Handling error codes and exceptions by the web.xml.

Example:

HippoBean myDocument = this.getContentBean(request);
if(myDocument == null) {
   try {
      hstResponse.sendError(404);
      return;
   } catch (IOException e) {
      // do your thing
   }
}

Info:
2. hstResponse.setStatus(int sc)
Sets the status code on the response. HstRequestProcessing continues. If multiple HstComponents set the status, the last value is used.

Because multiple components can set the status code, this method is generally not recommended. Use it only if your use case requires it.

Example:

HippoBean myDocument = this.getContentBean(request);
if(myDocument == null) {
   response.setStatus(404);
   myDocument = this.getSiteContentBaseBean(request).getBean(
                                       "common/errorPage");
}

Info:
3. hstResponse.forward(path);
Performs an internal forward to path, which must start with a /. This method short-circuits HstRequestProcessing: components that have not yet executed will not run.

This approach keeps the URL unchanged but forwards the request internally. You can forward to a sitemap item such as /error, which renders an error page.

Example:

try {
    HippoBean myDocument = this.getContentBean(request);
    if(myDocument == null) {
       response.forward("/error/404");
       return;
    }
    // do custom logic
} catch(MyUnauthorizedException e) {
    log.warn(e.getMessage());
    response.forward("/error/401");
} catch (IOException e) {
    throw new HstComponentException("forward failed", e);
}

You must configure a sitemap matcher for /error/xxx, for example:

+ error
    + *

The sitemap item can use a parameter name error-code with a value of ${1}, where ${1} matches the wildcard *. The HstComponent for the error sitemap item can set the error code as follows:

response.setStatus(Integer.parseInt(this.getParameter("error-code", request)));

Info:
4. HstResponseUtils.sendRedirect(hstRequest, hstResponse, path);
Performs an external (browser) redirect to path. The path must start with /. This method short-circuits HstRequestProcessing: components that have not yet executed will not run.

Example:

HippoBean myDocument = this.getContentBean(request);
if(myDocument == null) {
   HstResponseUtils.sendRedirect(hstRequest, hstResponse, "/error/404");
   return;
}

Note:
HstResponseUtils.sendRedirect automatically handles the context path based on your virtual hosts configuration.