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