Author: julien(a)jboss.com Date: 2007-06-17 19:25:32 -0400 (Sun, 17 Jun 2007) New Revision: 7454 Added: docs/trunk/referenceGuide/en/modules/errorhandling.xml Log: forgot to add error handling docs Added: docs/trunk/referenceGuide/en/modules/errorhandling.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/errorhandling.xml (rev 0) +++ docs/trunk/referenceGuide/en/modules/errorhandling.xml 2007-06-17 23:25:32 UTC (rev 7454) @@ -0,0 +1,303 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="errorhandling"> + <chapterinfo> + <author> + <firstname>Julien</firstname> + <surname>Viet</surname> + <email&gt;julien.viet(a)jboss.com&lt;/email&gt; + </author> + </chapterinfo> + <title>Error handling configuration</title> + <para>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.</para> + <sect1> + <title>Error types</title> + <para>There are several kind of errors that can be happen during a request.</para> + <itemizedlist> + <listitem>Access denied: the user does not have the security rights to access a resource</listitem> + <listitem>Error: an expected error, like a portlet threw an exception</listitem> + <listitem>Internal error: an unexpected error</listitem> + <listitem>Resource not found: a resource is not found</listitem> + <listitem>Resource not available: a resource is found but is not serviceable</listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Control policies</title> + <para>When an error occurs, the request control flow changes according to the configuration. The configuration + is also called <emphasis>control policy</emphasis>.</para> + <sect2> + <title>Policy delegation and cascading</title> + <para>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:</para> + <itemizedlist> + <listitem>The error is displayed in the window</listitem> + <listitem>The window is removed from the aggregation</listitem> + <listitem>An portal error page is displayed</listitem> + <listitem>An HTTP 500 error response is sent to the browser</listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Default policy</title> + <para>The default policy applies when error are not handled at other level. By default errors are translated + into the most appropriate HTTP response: + </para> + <itemizedlist> + <listitem>Access denied: HTTP 403 Forbidden response</listitem> + <listitem>Error: HTTP 500 Internal Server Error response</listitem> + <listitem>Internal error: HTTP 500 Internal Server Error response</listitem> + <listitem>Resource not found: HTTP 404 Not Found response</listitem> + <listitem>Resource not available: HTTP 404 Not Found response</listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Portal policy</title> + <para>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.</para> + </sect2> + <sect2> + <title>Page policy</title> + <para>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:</para> + <itemizedlist> + <listitem>Remove the window from the aggregation</listitem> + <listitem>Replace the markup of the window by a redirection to a JSP page</listitem> + </itemizedlist> + </sect2> + </sect1> + <sect1> + <title>Configuration using the XML descriptors</title> + <para>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.</para> + <sect2> + <title>Portal policy properties</title> + <para>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.</para> + <para> + <table frame="all"> + <title>Portal policy properties</title> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Property name</entry> + <entry align="center">Description</entry> + <entry align="center">Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry align="center">control.portal.access_denied</entry> + <entry align="center">On access denied</entry> + <entry align="center"><emphasis>ignore</emphasis> and <emphasis>jsp</emphasis></entry> + </row> + <row> + <entry align="center">control.portal.unavailable</entry> + <entry align="center">On resource not available</entry> + <entry align="center"><emphasis>ignore</emphasis> and <emphasis>jsp</emphasis></entry> + </row> + <row> + <entry align="center">control.portal.error</entry> + <entry align="center">On an expected error</entry> + <entry align="center"><emphasis>ignore</emphasis> and <emphasis>jsp</emphasis></entry> + </row> + <row> + <entry align="center">control.portal.internal_error</entry> + <entry align="center">On an unexpected error</entry> + <entry align="center"><emphasis>ignore</emphasis> and <emphasis>jsp</emphasis></entry> + </row> + <row> + <entry align="center">control.portal.not_found</entry> + <entry align="center">On resource not found</entry> + <entry align="center"><emphasis>ignore</emphasis> and <emphasis>jsp</emphasis></entry> + </row> + <row> + <entry align="center">control.portal.resource_uri</entry> + <entry align="center">The path of the JSP used for redirections</entry> + <entry align="center">A valid path to a JSP located in the portal-core.war file</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para>An example of portal configuration: + <programlisting><![CDATA[ +<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> +]]></programlisting> + </para> + </sect2> + <sect2> + <title>Page policy properties</title> + <para>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.</para> + <para> + <table frame="all"> + <title>Page policy properties</title> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Property name</entry> + <entry align="center">Description</entry> + <entry align="center">Possible values</entry> + </row> + </thead> + <tbody> + <row> + <entry align="center">control.page.access_denied</entry> + <entry align="center">On access denied</entry> + <entry align="center"><emphasis>ignore</emphasis>, <emphasis>jsp</emphasis> and <emphasis>hide</emphasis></entry> + </row> + <row> + <entry align="center">control.page.unavailable</entry> + <entry align="center">On resource not available</entry> + <entry align="center"><emphasis>ignore</emphasis>, <emphasis>jsp</emphasis> and <emphasis>hide</emphasis></entry> + </row> + <row> + <entry align="center">control.page.error</entry> + <entry align="center">On an expected error</entry> + <entry align="center"><emphasis>ignore</emphasis>, <emphasis>jsp</emphasis> and <emphasis>hide</emphasis></entry> + </row> + <row> + <entry align="center">control.page.internal_error</entry> + <entry align="center">On an unexpected error</entry> + <entry align="center"><emphasis>ignore</emphasis>, <emphasis>jsp</emphasis> and <emphasis>hide</emphasis></entry> + </row> + <row> + <entry align="center">control.page.not_found</entry> + <entry align="center">On resource not found</entry> + <entry align="center"><emphasis>ignore</emphasis>, <emphasis>jsp</emphasis> and <emphasis>hide</emphasis></entry> + </row> + <row> + <entry align="center">control.page.resource_uri</entry> + <entry align="center">The path of the JSP used for redirections</entry> + <entry align="center"><emphasis>ignore</emphasis>, <emphasis>jsp</emphasis> and <emphasis>hide</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para>An example of page configuration: + <programlisting><![CDATA[ +<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> +]]></programlisting> + </para> + <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.</note> + </sect2> + </sect1> + <sect1> + <title>Handling errors with JSP</title> + <para>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.</para> + <para> + <table frame="all"> + <title>Request attributes</title> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Attribute name</entry> + <entry align="center">Attribute Description</entry> + <entry align="center">Attribute value</entry> + </row> + </thead> + <tbody> + <row> + <entry align="center">org.jboss.portal.control.ERROR_TYPE</entry> + <entry align="center">The error type</entry> + <entry align="center">The possible values are <emphasis>ACCESS_DENIED</emphasis>, <emphasis>UNAVAILABLE</emphasis>, <emphasis>ERROR</emphasis>, <emphasis>INTERNAL_ERROR</emphasis>, <emphasis>NOT_FOUND</emphasis></entry> + </row> + <row> + <entry align="center">org.jboss.portal.control.CAUSE</entry> + <entry align="center">The throwable cause that can be null</entry> + <entry align="center">The object is a subclass of java.lang.Throwable</entry> + </row> + <row> + <entry align="center">org.jboss.portal.control.MESSAGE</entry> + <entry align="center">An error message that can be null</entry> + <entry align="center">Text</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <note>The JavaServer Pages have to be located in the jboss-portal.sar/portal-core.war Web Application.</note> + </sect1> +</chapter> \ No newline at end of file