JBoss Portal's request pipeline allows for fine-grained, dynamic configuration of how Portal will behave when an error occurs at runtime.
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
When an error occurs, the request control flow changes according to the configuration. The configuration is also called control policy.
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
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
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.
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
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).
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>
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.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.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:
