Chapter 8. Error handling configuration
Prev |  | Next

## Chapter 8. Error handling configuration

### Julien Viet

`<julien.viet@jboss.com>`

JBoss Portal's request pipeline allows for fine-grained, dynamic configuration of how Portal will behave when an error occurs at runtime.

## 8.1. Error types

There are several kind of errors that can happen during a request:

- Access denied: the user does not have the security rights to access a resource
- Error: an anticipated error as when a portlet throws an exception
- Internal error: an unexpected error
- Resource not found: a resource is not found
- Resource not available: a resource is found but is not serviceable

## 8.2. Control policies

When an error occurs, the request control flow changes according to the configuration. The configuration is also called control policy.

### 8.2.1. Policy delegation and cascading

Whenever a control policy is invoked it is possible to change the response sent by the control flow. If the control policy ignores the error then the next policy will handle the error at this turn. However if the control policy decides to provide a new response then the next policy will not be invoked since the new response will not be of type error. For instance, if a portlet part of a page produces an exception, the following reactions are possible:

- The error is displayed in the window
- The window is removed from the aggregation
- An portal error page is displayed
- An HTTP 500 error response is sent to the browser

### 8.2.2. Default policy

The default policy applies when errors are not handled at other level. By default errors are translated into the most appropriate HTTP response:

- Access denied: HTTP 403 Forbidden response
- Error: HTTP 500 Internal Server Error response
- Internal error: HTTP 500 Internal Server Error response
- Resource not found: HTTP 404 Not Found response
- Resource not available: HTTP 404 Not Found response

### 8.2.3. Portal policy

The portal error policy controls the response that will be sent to the browser when an error occurs. There is a default configuration and it is reconfigurable per portal. Whenever an error occurs, the policy can either handle a redirect to a JSP page or ignore the error. If the error is ignored it will be handled by the default policy, otherwise a JSP page will be invoked with appropriate request attributes to allow page customization.

### 8.2.4. Page policy

The window error policy controls how the page reacts to aggregation errors. Indeed the page is most of the time an aggregation of several portlet windows and the action to take when an error occurs is different than the other policies. Whenever an error occurs, the policy can either handle it or ignore it. If the error is ignored then it will be treated by the portal policy. The different actions that are possible upon an error are:

- Remove the window from the aggregation
- Replace the markup of the window by a redirection to a JSP page

## 8.3. Configuration using the XML descriptors

Since the different policies are configured using portal object properties it is possible to configure the error handling policy in the XML descriptors of those objects (the `*-object.xml` files for your Portal deployment).

### 8.3.1. Portal policy properties

A set of properties configure the the behavior of the portal policy. Those properties will only be taken in account for objects of type portal.

Table 8.1. Portal policy properties

Property name | Description | Possible values
--- | --- | ---
control.portal.access_denied | On access denied | ignore and jsp
control.portal.unavailable | On resource not available | ignore and jsp
control.portal.error | On an expected error | ignore and jsp
control.portal.internal_error | On an unexpected error | ignore and jsp
control.portal.not_found | On resource not found | ignore and jsp
control.portal.resource_uri | The path of the JSP used for redirections | A valid path to a JSP located in the portal-core.war file

An example of portal configuration:

    <portal>
       <portal-name>MyPortal</portal-name>
       ...
       <properties>
          <property>
             <name>control.portal.access_denied</name>
             <value>ignore</value>
          </property>
          <property>
             <name>control.portal.unavailable</name>
             <value>ignore</value>
          </property>
          <property>
             <name>control.portal.not_found</name>
             <value>ignore</value>
          </property>
          <property>
             <name>control.portal.internal_error</name>
             <value>jsp</value>
          </property>
          <property>
             <name>control.portal.error</name>
             <value>jsp</value>
          </property>
          <property>
             <name>control.portal.resource_uri</name>
             <value>/WEB-INF/jsp/error/portal.jsp</value>
          </property>
          ...
       </properties>
       ...
    </portal>

### 8.3.2. Page policy properties

A set of properties configure the the behavior of the page policy. Those properties will only be taken in account for objects of type portal and page.

Table 8.2. Page policy properties

Property name | Description | Possible values
--- | --- | ---
control.page.access_denied | On access denied | ignore, jsp and hide
control.page.unavailable | On resource not available | ignore, jsp and hide
control.page.error | On an expected error | ignore, jsp and hide
control.page.internal_error | On an unexpected error | ignore, jsp and hide
control.page.not_found | On resource not found | ignore, jsp and hide
control.page.resource_uri | The path of the JSP used for redirections | ignore, jsp and hide

An example of page configuration:

    <page>
       <page-name>MyPortal</page-name>
       ...
       <properties>
          <property>
             <name>control.page.access_denied</name>
             <value>hide</value>
          </property>
          <property>
             <name>control.page.unavailable</name>
             <value>hide</value>
          </property>
          <property>
             <name>control.page.not_found</name>
             <value>hide</value>
          </property>
          <property>
             <name>control.page.internal_error</name>
             <value>jsp</value>
          </property>
          <property>
             <name>control.page.error</name>
             <value>jsp</value>
          </property>
          <property>
             <name>control.page.resource_uri</name>
             <value>/WEB-INF/jsp/error/page.jsp</value>
          </property>
          ...
       </properties>
       ...
    </page>

### Note

You can configure the page properties also on objects of type portal, in that case they will be inherited by the pages which are located in the portal.

## 8.4. Handling errors with JSP

As described above it is possible to redirect error handling to a JavaServer Page. Two pages can be created to handle errors at portal and page level. Portal level error handling requires a page that will produce a full page and the page level error handling requires a page that will produce markup for a window only. When the page is invoked a set of request attributes will be passed.

Table 8.3. Request attributes

Attribute name | Attribute Description | Attribute value
--- | --- | ---
org.jboss.portal.control.ERROR_TYPE | The error type | The possible values are ACCESS_DENIED, UNAVAILABLE, ERROR, INTERNAL_ERROR, NOT_FOUND
org.jboss.portal.control.CAUSE | The throwable cause that can be null | The object is a subclass of java.lang.Throwable
org.jboss.portal.control.MESSAGE | An error message that can be null | Text

### Note

The JavaServer Pages have to be located in the jboss-portal.sar/portal-core.war Web Application.

## 8.5. Configuration using the Portal Management Application

The Error handling policy can also be configured via the portal management application. The functionality is available as part of the properties for each configuration level where it makes sense: you can specify the default error handling policy (at the root of the portal object hierachy), for each portal or each page by clicking on the Properties link on each of these pages. You can also specify how dashboards should behave with respect to error handling by clicking on the Dashboards tab of the Portal management application.

Screenshot:

Prev | Up | Next
Chapter 7. Portal urls | Home | Chapter 9. Content Integration