[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Sun Feb 4 12:42:27 EST 2007
User: gavin
Date: 07/02/04 12:42:27
Modified: doc/reference/en/modules annotations.xml
components.xml configuration.xml events.xml
persistence.xml security.xml xml.xml
Log:
update docs for exceptions,events
Revision Changes Path
1.51 +1 -26 jboss-seam/doc/reference/en/modules/annotations.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: annotations.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/annotations.xml,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -b -r1.50 -r1.51
--- annotations.xml 27 Nov 2006 06:10:22 -0000 1.50
+++ annotations.xml 4 Feb 2007 17:42:27 -0000 1.51
@@ -752,6 +752,7 @@
<section>
<title>Annotations for exceptions</title>
+
<para> These annotations let you specify how Seam should handle an exception that propagates out of a Seam
component. </para>
@@ -781,32 +782,6 @@
</itemizedlist>
</listitem>
</varlistentry>
- <varlistentry id="render-annotation">
- <term>
- <literal>@Render</literal>
- </term>
- <listitem>
- <programlisting><![CDATA[@Render(viewId="error.jsp")]]></programlisting>
- <para> Specifies that the annotated exception causes immediate rendering of the view. This
- annotation is ignored unless the exception is thrown during the JSF INVOKE_APPLICATION phase. </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>viewId</literal> — specifies the JSF view id to redirect to. </para>
- </listitem>
- <listitem>
- <para>
- <literal>message</literal> — a message to be displayed, default to the
- exception message. </para>
- </listitem>
- <listitem>
- <para>
- <literal>end</literal> — specifies that the long-running conversation should
- end, default to <literal>false</literal>. </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
<varlistentry id="httperror-annotation">
<term>
<literal>@HttpError</literal>
1.55 +1 -1 jboss-seam/doc/reference/en/modules/components.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: components.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/components.xml,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -b -r1.54 -r1.55
--- components.xml 29 Jan 2007 12:43:00 -0000 1.54
+++ components.xml 4 Feb 2007 17:42:27 -0000 1.55
@@ -213,7 +213,7 @@
<para>
An API for raising events that can be observed via
<literal>@Observer</literal> methods, or method
- bindings in <literal>WEB-INF/events.xml</literal>.
+ bindings in <literal>components.xml</literal>.
</para>
<itemizedlist>
<listitem>
1.34 +30 -0 jboss-seam/doc/reference/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/configuration.xml,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- configuration.xml 28 Jan 2007 05:49:56 -0000 1.33
+++ configuration.xml 4 Feb 2007 17:42:27 -0000 1.34
@@ -130,6 +130,36 @@
</sect2>
<sect2>
+ <title>Enabling Seam exception handling</title>
+
+ <para>
+ If you want to use Seam's exception mapping functionality
+ in <literal>pages.xml</literal> (almost all applications
+ will need this), you need to add a servlet filter to
+ <literal>web.xml</literal>:
+ </para>
+
+ <programlisting><![CDATA[<filter>
+ <filter-name>Seam Exception Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamExceptionFilter</filter-class>
+</filter>
+
+<filter-mapping>
+ <filter-name>Seam Exception Filter</filter-name>
+ <url-pattern>*.seam</url-pattern>
+</filter-mapping>]]></programlisting>
+
+ <para>
+ This servlet filter also takes care of rolling back uncommitted transactions
+ when uncaught exceptions occur. (According to the Java EE specification, the
+ web container should do this automatically, but we've found that this behavior
+ cannot be relied upon in all application servers. And it is certainly not
+ required of plain servlet engines like Tomcat.)
+ </para>
+
+ </sect2>
+
+ <sect2>
<title>Enabling conversation propagation with redirects</title>
<para>
1.11 +112 -37 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.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- events.xml 1 Feb 2007 16:58:43 -0000 1.10
+++ events.xml 4 Feb 2007 17:42:27 -0000 1.11
@@ -109,16 +109,19 @@
<sect3>
<title>Page parameters</title>
+
<para>
A JSF faces request (a form submission) encapsulates both an "action"
(a method binding) and "parameters" (input value bindings). A page
action might also needs parameters!
</para>
+
<para>
Since GET requests are bookmarkable, page parameters are passed as
human-readable request parameters. (Unlike JSF form inputs, which are
anything but!)
</para>
+
<para>
Seam lets us provide a value binding that maps a named request parameter
to an attribute of a model object.
@@ -405,14 +408,11 @@
</navigation-rule>]]></programlisting>
-
-
</sect3>
-
-
<sect3>
<title>Fine-grained files for definition of page actions and parameters</title>
+
<para>
If you have a lot of different page actions and page parameters,
you will almost certainly want to split the declarations up over
@@ -445,15 +445,15 @@
</para>
<para>
- We specify event listeners (observers) in <literal>WEB-INF/events.xml</literal>.
+ We specify event listeners (observers) in <literal>components.xml</literal>.
</para>
- <programlisting><![CDATA[<events>
+ <programlisting><![CDATA[<components>
<event type="hello">
<action expression="#{helloListener.sayHelloBack}"/>
<action expression="#{logger.logHello}"/>
</event>
-</events>]]></programlisting>
+</components>]]></programlisting>
<para>
Where the <emphasis>event type</emphasis> is just an arbitrary string.
@@ -461,7 +461,7 @@
<para>
When an event occurs, the actions registered for that event will be called
- in the order they appear in <literal>events.xml</literal>. How does a
+ in the order they appear in <literal>components.xml</literal>. How does a
component raise an event? Seam provides a built-in component for this.
</para>
@@ -474,6 +474,18 @@
}]]></programlisting>
<para>
+ Or you can use an annotation.
+ </para>
+
+ <programlisting><![CDATA[@Name("helloWorld")
+public class HelloWorld {
+ @RaiseEvent("hello")
+ public void sayHello() {
+ FacesMessages.instance().add("Hello World!");
+ }
+}]]></programlisting>
+
+ <para>
Notice that this event producer has no dependency upon event consumers.
The event listener may now be implemented with absolutely no dependency
upon the producer:
@@ -487,8 +499,10 @@
}]]></programlisting>
<para>
- If you don't like the <literal>events.xml</literal> file, we can use an
- annotation instead:
+ The method binding defined in <literal>components.xml</literal> above
+ takes care of mapping the event to the consumer.
+ If you don't like futzing about in the <literal>components.xml</literal>
+ file, you can use an annotation instead:
</para>
<programlisting><![CDATA[@Name("helloListener")
@@ -554,11 +568,13 @@
<listitem><para><literal>org.jboss.seam.preDestroy.<name> </literal>— called when the component <name> is destroyed</para></listitem>
<listitem><para><literal>org.jboss.seam.beforePhase </literal>— called before the start of a JSF phase</para></listitem>
<listitem><para><literal>org.jboss.seam.afterPhase </literal>— called after the end of a JSF phase</para></listitem>
+ <listitem><para><literal>org.jboss.seam.postAuthenticate.<name> </literal>— called after a user is authenticated</para></listitem>
+ <listitem><para><literal>org.jboss.seam.preAuthenticate.<name> </literal>— called before attempting to authenticate a user</para></listitem>
</itemizedlist>
<para>
Seam components may observe any of these events in just the same way they
- observe component-driven events.
+ observe any other component-driven events.
</para>
</sect2>
@@ -566,6 +582,7 @@
<sect1>
<title>Seam interceptors</title>
+
<para>
EJB 3.0 introduced a standard interceptor model for session bean components. To add an
interceptor to a bean, you need to write a class with a method annotated
@@ -680,6 +697,7 @@
<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
@@ -689,11 +707,16 @@
specifies whether the exception should cause a transaction rollback.
</para>
+ <sect2>
+ <title>Exceptions and transactions</title>
+
<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>
+ EJB specifies well-defined rules that let us control whether an exception
+ immediately marks the current transaction for rollback when it is thrown by
+ a business method of the bean: <emphasis>system exceptions</emphasis> always
+ cause a transaction rollback, <emphasis>application exceptions</emphasis> do
+ not cause a rollback by default, but they 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
@@ -701,8 +724,54 @@
</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.
+ Note that there is a difference between marking a transaction for rollback,
+ and actually rolling it back. The exception rules say that the transaction
+ should be marked rollback only, but it may still be active after the
+ exception is thrown.
+ </para>
+
+ <para>
+ Seam applies the EJB 3.0 exception rollback rules also to Seam JavaBean
+ components.
+ </para>
+
+ <para>
+ But these rules only apply in the Seam component layer. What about an exception
+ that is uncaught and propagates out of the Seam component layer, and out of the JSF
+ layer? Well, it is always wrong to leave a dangling transaction open, so Seam
+ rolls back any active transaction when an exception occurs and is uncaught
+ in the Seam component layer.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Enabling Seam exception handling</title>
+
+ <para>
+ To enable Seam's exception handling, we need to add a servlet filter to
+ <literal>web.xml</literal>:
+ </para>
+
+ <programlisting><![CDATA[<filter>
+ <filter-name>Seam Exception Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamExceptionFilter</filter-class>
+</filter>
+
+<filter-mapping>
+ <filter-name>Seam Exception Filter</filter-name>
+ <url-pattern>*.seam</url-pattern>
+</filter-mapping>]]></programlisting>
+
+ </sect2>
+
+ <sect2>
+ <title>Using annotations for exception handling</title>
+
+ <para>
+ The following exception results in a HTTP 404 error whenever it propagates out of the
+ Seam component layer. It does not roll back the current transaction immediately when
+ thrown, but the transaction will be rolled back if it the exception is not caught by
+ another Seam component.
</para>
<programlisting><![CDATA[@HttpError(errorCode=404)
@@ -710,8 +779,8 @@
<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.
+ Seam component layer. It also ends the current conversation. It causes an immediate
+ rollback of the current transaction.
</para>
<programlisting><![CDATA[@Redirect(viewId="/failure.xhtml", end=true)
@@ -724,48 +793,54 @@
</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.
+ This exception results in a redirect, along with a message to the user, when it
+ propagates out of the Seam component layer. It also immediately rolls back the
+ current transaction.
</para>
- <programlisting><![CDATA[@Render(viewId="/error.xhtml", message="Unexpected error")
+ <programlisting><![CDATA[@Redirect(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>
+ </sect2>
+
+ <sect2>
+ <title>Using XML for exception handling</title>
<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>.
+ Seam also lets us specify this functionality in <literal>pages.xml</literal>.
</para>
- <programlisting><![CDATA[<exceptions>
+ <programlisting><![CDATA[<pages>
<exception class="javax.persistence.EntityNotFoundException">
<http-error error-code="404"/>
</exception>
<exception class="javax.persistence.PersistenceException">
- <render>Database access failed</render>
<end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <faces-message>Database access failed</faces-message>
+ </redirect>
</exception>
<exception>
- <redirect view-id="/search.xhtml">Unexpected failure</redirect>
<end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <faces-message>Unexpected failure</faces-message>
+ </redirect>
</exception>
-</exceptions>]]></programlisting>
+</pages>]]></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>.
+ via annotations or in <literal>pages.xml</literal>.
</para>
+ </sect2>
+
</sect1>
</chapter>
1.7 +0 -17 jboss-seam/doc/reference/en/modules/persistence.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: persistence.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/persistence.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- persistence.xml 30 Jan 2007 18:00:55 -0000 1.6
+++ persistence.xml 4 Feb 2007 17:42:27 -0000 1.7
@@ -177,23 +177,6 @@
</lifecycle>]]></programlisting>
<para>
- It's also a good idea to add a servlet filter to rollback uncommitted transactions
- when uncaught exceptions occur. (According to the Java EE specification, the
- web container should do this automatically, but we've found that this behavior
- cannot be relied upon in all application servers.)
- </para>
-
- <programlisting><![CDATA[<filter>
- <filter-name>Seam Exception Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamExceptionFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>Seam Exception Filter</filter-name>
- <url-pattern>*.jsf</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para>
Seam transaction management is useful even if you're using EJB 3.0
container-managed persistence contexts. But it is especially useful
if you use Seam outside a Java EE 5 environment, or in any other
1.21 +10 -6 jboss-seam/doc/reference/en/modules/security.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: security.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/security.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -b -r1.20 -r1.21
--- security.xml 4 Feb 2007 09:44:53 -0000 1.20
+++ security.xml 4 Feb 2007 17:42:27 -0000 1.21
@@ -689,7 +689,7 @@
<para>
To prevent users from receiving the default error page in response to a security error, it's recommended that
- <literal>exceptions.xml</literal> is configured to redirect security errors to a more "pretty" page. The two
+ <literal>pages.xml</literal> is configured to redirect security errors to a more "pretty" page. The two
main types of exceptions thrown by the security API are:
</para>
@@ -710,24 +710,28 @@
</itemizedlist>
<para>
- Here's an example of an <literal>exceptions.xml</literal> file that redirects these security exceptions:
+ Here's an example of a <literal>pages.xml</literal> file that redirects these security exceptions:
</para>
<programlisting>
<![CDATA[
-<exceptions>
+<pages>
<exception class="org.jboss.seam.security.NotLoggedInException">
- <redirect view-id="/login.xhtml">You must be logged in to perform this action</redirect>
<end-conversation/>
+ <redirect view-id="/login.xhtml">
+ <faces-message>You must be logged in to perform this action</faces-message>
+ </redirect>
</exception>
<exception class="org.jboss.seam.security.AuthorizationException">
- <redirect view-id="/security_error.xhtml">You do not have the necessary security privileges to perform this action.</redirect>
<end-conversation/>
+ <redirect view-id="/security_error.xhtml">
+ <faces-message>You do not have the necessary security privileges to perform this action.</faces-message>
+ </redirect>
</exception>
-</exceptions>
+</pages>
]]>
</programlisting>
1.4 +30 -23 jboss-seam/doc/reference/en/modules/xml.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: xml.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/xml.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- xml.xml 28 Jan 2007 03:20:23 -0000 1.3
+++ xml.xml 4 Feb 2007 17:42:27 -0000 1.4
@@ -1,6 +1,7 @@
<chapter id="xml">
<title>Configuring Seam components</title>
+
<para>
The philosophy of minimizing XML-based configuration is extremely strong in Seam. Nevertheless,
there are various reasons why we might want to configure a Seam component using XML: to isolate
@@ -35,6 +36,7 @@
<sect1>
<title>Configuring components via <literal>components.xml</literal></title>
+
<para>
The <literal>components.xml</literal> file is a bit more powerful than property settings. It lets
you:
@@ -498,6 +500,7 @@
</para>
<para>The following are the the namespaces used by Seam:</para>
+
<itemizedlist>
<listitem>
<para>components — <literal>http://jboss.com/products/seam/components</literal></para>
@@ -520,7 +523,11 @@
<listitem>
<para>theme — <literal>http://jboss.com/products/seam/theme</literal></para>
</listitem>
+ <listitem>
+ <para>security — <literal>http://jboss.com/products/seam/security</literal></para>
+ </listitem>
</itemizedlist>
+
</sect1>
More information about the jboss-cvs-commits
mailing list