[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Mon Oct 23 14:14:48 EDT 2006
User: gavin
Date: 06/10/23 14:14:48
Modified: doc/reference/en/modules concepts.xml events.xml
Log:
doc exceptions.xml
Revision Changes Path
1.36 +0 -34 jboss-seam/doc/reference/en/modules/concepts.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: concepts.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/concepts.xml,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -b -r1.35 -r1.36
--- concepts.xml 16 Oct 2006 11:23:14 -0000 1.35
+++ concepts.xml 23 Oct 2006 18:14:47 -0000 1.36
@@ -1210,40 +1210,6 @@
</sect1>
<sect1>
- <title>Managing exceptions</title>
- <para>
- JSF is surprisingly limited when it comes to exception handling. Seam lets you
- define how a particular class of event is to be treated by annotating the event
- class. This facility is meant to be combined with the EJB 3.0-standard
- <literal>@ApplicationException</literal> annotation which specifies whether
- the exception should cause a transaction rollback.
- </para>
-
- <para>
- This exception results in a HTTP 404 error whenever it propagates out of the
- Seam component layer. It does not roll back the current transaction.
- </para>
-
- <programlisting><![CDATA[@HttpError(errorCode=404)
-public class DocumentNotFoundException extends Exception { ... }]]></programlisting>
-
- <para>
- This exception results in a browser redirect whenever it propagates out of the
- Seam component layer. It also rolls back the current transaction.
- </para>
-
- <programlisting><![CDATA[@Redirect(viewId="/error.xhtml")
- at ApplicationException(rollback=true)
-public class UnrecoverableException extends RuntimeException { ... }]]></programlisting>
-
- <para>
- Note that <literal>@Redirect</literal> does not work for exceptions
- which occur during the render phase of the JSF lifecycle.
- </para>
-
- </sect1>
-
- <sect1>
<title>Factory and manager components</title>
<para>
We often need to work with objects that are not Seam components. But we still want
1.2 +91 -1 jboss-seam/doc/reference/en/modules/events.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: events.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/events.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- events.xml 16 Oct 2006 11:23:14 -0000 1.1
+++ events.xml 23 Oct 2006 18:14:47 -0000 1.2
@@ -1,5 +1,5 @@
<chapter id="events">
- <title>Events and interceptors</title>
+ <title>Events, interceptors and exception handling</title>
<para>
Complementing the contextual component model, there are two further basic concepts
@@ -453,4 +453,94 @@
</sect1>
+ <sect1>
+ <title>Managing exceptions</title>
+ <para>
+ JSF is surprisingly limited when it comes to exception handling. As a partial
+ workaround for this problem, Seam lets you define how a particular class of
+ exception is to be treated by annotating the exception class, or declaring
+ the exception class in an XML file. This facility is meant to be combined with
+ the EJB 3.0-standard <literal>@ApplicationException</literal> annotation which
+ specifies whether the exception should cause a transaction rollback.
+ </para>
+
+ <para>
+ Note that Seam applies the EJB 3.0 exception rollback rules also to Seam JavaBean
+ components: <emphasis>system exceptions</emphasis> always cause a transaction
+ rollback, <emphasis>application exceptions</emphasis> do not cause a rollback
+ by default, but do if <literal>@ApplicationException(rollback=true)</literal>
+ is specified. (An application exception is any checked exception, or any
+ unchecked exception annotated <literal>@ApplicationException</literal>.
+ A system exception is any unchecked exception without an
+ <literal>@ApplicationException</literal> annotation.)
+ </para>
+
+ <para>
+ This exception results in a HTTP 404 error whenever it propagates out of the
+ Seam component layer. It does not roll back the current transaction.
+ </para>
+
+ <programlisting><![CDATA[@HttpError(errorCode=404)
+public class ApplicationException extends Exception { ... }]]></programlisting>
+
+ <para>
+ This exception results in a browser redirect whenever it propagates out of the
+ Seam component layer. It also ends the current conversation. It also rolls back
+ the current transaction.
+ </para>
+
+ <programlisting><![CDATA[@Redirect(viewId="/failure.xhtml", end=true)
+ at ApplicationException(rollback=true)
+public class UnrecoverableApplicationException extends RuntimeException { ... }]]></programlisting>
+
+ <para>
+ Note that <literal>@Redirect</literal> does not work for exceptions
+ which occur during the render phase of the JSF lifecycle.
+ </para>
+
+ <para>
+ This exception results in immediate rendering of the view, along with a
+ message to the user, when it propagates out of the
+ Seam component layer. It also rolls back the current transaction.
+ </para>
+
+ <programlisting><![CDATA[@Render(viewId="/error.xhtml", message="Unexpected error")
+public class SystemException extends RuntimeException { ... }]]></programlisting>
+
+ <para>
+ Note that <literal>@Render</literal> only works when the exception occurs during the
+ <literal>INVOKE_APPLICATION</literal> phase.
+ </para>
+
+ <para>
+ Since we can't add annotations to all the exception classes we are interested in,
+ Seam also lets us specify this functionality in <literal>WEB-INF/exceptions.xml</literal>.
+ </para>
+
+ <programlisting><![CDATA[<exceptions>
+
+ <exception class="javax.persistence.EntityNotFoundException">
+ <http-error errorCode="404"/>
+ </exception>
+
+ <exception class="javax.persistence.PersistenceException">
+ <render>Database access failed</render>
+ <end-conversation/>
+ </exception>
+
+ <exception>
+ <redirect view-id="/search.xhtml">Unexpected failure</redirect>
+ <end-conversation/>
+ </exception>
+
+</exceptions>]]></programlisting>
+
+ <para>
+ The last <literal><exception></literal> declaration does not specify a class,
+ and is a catch-all for any exception for which handling is not otherwise specified
+ via annotations or in <literal>exceptions.xml</literal>.
+ </para>
+
+ </sect1>
+
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list