Chapter 8. Error handling configuration
Prev |  | Next

## Chapter 8. Error handling configuration

### Julien Viet

`<julien.viet@jboss.com>`

JBoss Portal request pipeline provides configuring of the error handling policy. At runtime when an error occurs it is possible to configure how the portal behaves in a fine grained and dynamic manner.

## 8.1. Error types

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

- Access denied: the user does not have the security rights to access a resource
- Error: an expected error, like a portlet threw 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 given the opportunity 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 error 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

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

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.

### 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 producer markup for a window only. When the page is invoked it will be passed a set of request attributes.

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 through the "Dashboards" tab in the application

Screenshot:

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