The JBoss Portal request pipeline allows fine-grained, dynamic configuration of how JBoss Portal behaves when errors occur during runtime.
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.
If an error occurs, the request control-flow changes according to the configuration. This configuration is known as the control policy.
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.
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 ForbiddenError:
HTTP 500 Internal Server ErrorInternal error:
HTTP 500 Internal Server ErrorResource not found:
HTTP 404 Not FoundResource unavailable:
HTTP 404 Not Found
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.
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.
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.
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>
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.
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 thejboss-portal.sar/portal-core.war/ web application.
The error handling policy can be configured via the portal management application. To access the portal management application:
Use a Web browser to navigate to http://localhost:8080/portal.
Click the Login button on the top right-hand of the welcome page, and log in as the
adminuser.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.
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.