[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> &mdash; specifies the JSF view id to redirect to. </para>
  -                        </listitem>
  -                        <listitem>
  -                            <para>
  -                                <literal>message</literal> &mdash; a message to be displayed, default to the
  -                                exception message. </para>
  -                        </listitem>
  -                        <listitem>
  -                            <para>
  -                                <literal>end</literal> &mdash; 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.&lt;name&gt; </literal>&mdash; called when the component &lt;name&gt; is destroyed</para></listitem>
               <listitem><para><literal>org.jboss.seam.beforePhase </literal>&mdash; called before the start of a JSF phase</para></listitem>
               <listitem><para><literal>org.jboss.seam.afterPhase </literal>&mdash; called after the end of a JSF phase</para></listitem>
  +            <listitem><para><literal>org.jboss.seam.postAuthenticate.&lt;name&gt; </literal>&mdash; called after a user is authenticated</para></listitem>
  +            <listitem><para><literal>org.jboss.seam.preAuthenticate.&lt;name&gt; </literal>&mdash; 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>&lt;exception&gt;</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 &mdash; <literal>http://jboss.com/products/seam/components</literal></para>
  @@ -520,7 +523,11 @@
               <listitem>
                   <para>theme &mdash; <literal>http://jboss.com/products/seam/theme</literal></para>
               </listitem>
  +                <listitem>
  +                    <para>security &mdash; <literal>http://jboss.com/products/seam/security</literal></para>
  +                </listitem>
           </itemizedlist>
  +            
           </sect1>
   
   
  
  
  



More information about the jboss-cvs-commits mailing list