Prev |  | Next

## Chapter 9. Error Handling Configuration

### Julien Viet

The JBoss Portal request pipeline allows fine-grained, dynamic configuration of how JBoss Portal behaves when errors occur during runtime.

## 9.1. Error Types

There are several types of errors that can occur during a request:

- Access denied: the user does not have the required permissions to access the resource.

- Error: an anticipated error, such as when a portlet throws an exception.

- Internal error: an unexpected error.

- Resource not found: the resource was not found.

- Resource unavailable: the resource was found, but was not serviceable.

## 9.2. Control Policies

If an error occurs, the request control-flow changes according to the configuration. This configuration is known as the control policy.

### 9.2.1. Policy Delegation and Cascading

When a control policy is invoked, the response sent by the control flow can be changed. If the control policy ignores the error, the error is handled by the next policy. If the control policy provides a new response, the next policy is not invoked, since the new response is not an error.

If a portlet in a page produces an exception, the following reactions are possible:

- the error is displayed in the window.

- the window is removed from the aggregation.

- a portal error page is displayed.

- a HTTP 500 error response is sent to the Web browser.

### 9.2.2. Default Policy

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

- Access denied: `HTTP 403 Forbidden`

- Error: `HTTP 500 Internal Server Error`

- Internal error: `HTTP 500 Internal Server Error`

- Resource not found: `HTTP 404 Not Found`

- Resource unavailable: `HTTP 404 Not Found`

### 9.2.3. Portal Policy

The portal error-policy controls the response sent to the Web browser when an error occurs. A default error policy exists, which can be configured per portal. If an error occurs, the policy can either handle a redirect to a JSP page, or ignore it. If the error is ignored, it is handled by the default policy, otherwise a JSP page is invoked with the appropriate request attributes, allowing page customization.

### 9.2.4. Page Policy

The window error-policy controls how pages react to aggregation errors. Most of the time pages are an aggregation of several portlet windows, and the action to take when an error occurs differs from other policies. When an error occurs, the policy can either handle it, or ignore it. If the error is ignored, it is handled by the portal policy. Possible actions taken after such errors are:

- remove the window from the aggregation.

- replace the markup of the window using a redirect to a JSP page.

## 9.3. Configuration using XML Descriptors

Different policies are configured using portal object properties, allowing the error-handling policy for objects to be configured in XML descriptors -- the `*-object.xml` files -- for a portal deployment.

### 9.3.1. Portal Policy Properties

A set of properties configure the the behavior of the portal policy. These properties are only taken into account for objects that use the portal type. The following table represents possible portal-policy properties:

Table 9.1.

Property Name | Description | Possible Values
--- | --- | ---
`control.portal.access_denied` | when access is denied | `ignore` and `jsp`
`control.portal.unavailable` | when a resource is unavailable | `ignore` and `jsp`
`control.portal.not_found` | when a resource is not found | `ignore` and `jsp`
`control.portal.internal_error` | when an unexpected error occurs | `ignore` and `jsp`
`control.portal.error` | when an expected error occurs | `ignore` and `jsp`
`control.portal.resource_uri` | the path to the JSP used for redirections | a valid path to a JSP located in the `portal-core.war/` directory

The following portal configuration demonstrates the use of portal-policy properties:

    <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>

### 9.3.2. Page Policy Properties

A set of properties configure the behavior of the page policy. These properties are only taken into account for objects that use the portal type. The following table represents possible page-policy properties:

Table 9.2.

Property name | Description | Possible values
--- | --- | ---
`control.page.access_denied` | when access is denied | `ignore`, `jsp` and `hide`
`control.page.unavailable` | when a resource is unavailable | `ignore`, `jsp` and `hide`
`control.page.not_found` | when a resource is not found | `ignore`, `jsp` and `hide`
`control.page.internal_error` | when an unexpected error occurs | `ignore`, `jsp` and `hide`
`control.page.error` | when an expected error occurs | `ignore`, `jsp` and `hide`
`control.page.resource_uri` | the path to the JSP used for redirections | `ignore`, `jsp` and `hide`

The following page configuration demonstrates the use of page-policy properties:

    <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>

## Page Property Inheritance for Objects

When page properties are configured for objects that use the portal type, the properties are inherited by pages in that portal.

## 9.4. Using JSP™ to Handle Errors

As described in previous sections, error handling can be redirected to a JSP™ page. Two pages can be created to handle errors: one for the portal level, and the other for the page level. Portal level error-handling requires a page that produces a full page, and page-level handling requires a page that produces markup, but only for a window. When the page is invoked, a set of request attributes are passed. The following table represents possible request attributes:

Table 9.3.

Attribute Name | Attribute Description | Attribute Value
--- | --- | ---
`org.jboss.portal.control.ERROR_TYPE` | the error type | possible values are `ACCESS_DENIED`, `UNAVAILABLE`, `ERROR`, `INTERNAL_ERROR`, and `NOT_FOUND`
`org.jboss.portal.control.CAUSE` | a cause which is thrown, 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

## JSP™ Location

The JavaServer Pages must be located in the `jboss-portal.sar/portal-core.war/` web application.

## 9.5. Configuration using the Portal Management Application

The error handling policy can be configured via the portal management application. To access the portal management application:

1. Use a Web browser to navigate to http://localhost:8080/portal.

2. Click the Login button on the top right-hand of the welcome page, and log in as the `admin` user.

3. Click the Admin tab on the top right-hand of the welcome page. Four tabs will appear on the left-hand side of the page.

4. Click the Admin tab to open the portal management application, and then click the Portal Objects tab to display available portals.

Configuration options are available as part of the properties for each configuration level. You can specify the default error handling policy (at the root of the portal object hierarchy) for each portal, or each page, by clicking on the Properties button for each page or portal:

As well, you can specify how dashboards should behave with respect to error handling, by clicking on the Dashboards tab in the portal management application:

The page specified with `On error redirect to this resource` is used when the `Redirect to the specified resource` action is selected for an error type, such as `When access to the page is denied`. After making changes, click the Update button for settings to take effect.

Prev |  | Front page | Next