[jboss-cvs] JBossAS SVN: r81934 - projects/docs/enterprise/4.3.3.1/Seam/Seam_Reference_Guide/en-US.

[jboss-cvs-commits at lists.jboss.org]

Author: irooskov at redhat.com
Date: 2008-12-01 22:46:21 -0500 (Mon, 01 Dec 2008)
New Revision: 81934

Modified:
   projects/docs/enterprise/4.3.3.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml
Log:
updated with JBPAPP-1444 fix by marek


Modified: projects/docs/enterprise/4.3.3.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- projects/docs/enterprise/4.3.3.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml	2008-12-02 02:03:37 UTC (rev 81933)
+++ projects/docs/enterprise/4.3.3.1/Seam/Seam_Reference_Guide/en-US/Conversations.xml	2008-12-02 03:46:21 UTC (rev 81934)
@@ -1038,7 +1038,7 @@
       </para>
       
       <para>
-        Therefore Seam queues the action event for a period of time (the 
+	      Therefore, when you are working inside a long running conversation, Seam queues the action event for a period of time (the 
         concurrent request timeout); if it can't process the event in time, it 
         creates a temporary conversation and prints out a message to the user to
         let them know what's going on.  It's therefore very important not to
@@ -1051,18 +1051,15 @@
       </para>
       
       <programlisting role="XML"><![CDATA[<core:manager concurrent-request-timeout="500" />]]></programlisting>
-      <!-- TODO -->
-      <!-- <para>
-        We can also fine tune the concurrent request timeout for a request:
+     <para>
+	     We can also fine tune the concurrent request timeout on a page-by-page basis:
       </para>
        
-      <programlisting role="JAVA"><![CDATA[public void getTotal() {
-   Manager.instance().setConcurrentRequestTimeout(1000);
-   return someReallyComplicatedCalculation();
-}]]></programlisting>-->
+<programlisting role="XML"><![CDATA[
+<page view-id="/book.xhtml" conversation-required="true" login-required="true" concurrent-request-timeout="2000" />]]></programlisting>
 
     <para>
-      So far we've discussed "synchronous" AJAX requests - the client tells the
+      So far we've discussed serial AJAX requests - the client tells the
       server that an event has occur, and then rerenders part of the page based
       on the result.  This approach is great when the AJAX request is
       lightweight (the methods called are simple e.g. calculating the sum of a
@@ -1078,10 +1075,11 @@
       be dropped as duplicates, or to timeout).
     </para>
     
-    <para>
+ <!--   <para>
       <emphasis>How should we design our conversational AJAX application?</emphasis>
-    </para>
-    
+    </para> -->
+    <section>
+	    <title>How should we design our conversational AJAX application?</title>
     <para>
       Well first, you need to decide whether you want to use the simpler 
       "synchronous" request or whether you want to add using a poll-style
@@ -1128,6 +1126,46 @@
 public int getTotal() {
    return total;
 }]]></programlisting>
+	</section>
+	<section>
+	<title>Dealing with errors</title>
+	<para>
+		However carefully you design your application to queue concurrent requests to your conversational component, there is a risk that the server will become overloaded and be unable to process all the requests before the request will have to wait longer than the <literal>concurrent-request-timeout</literal>. In this case Seam will throw a <literal>ConcurrentRequestTimeoutException</literal> which can be handled in <literal>pages.xml</literal>. We recommend sending a HTTP 503 error: </para>
+<programlisting role="XML"><![CDATA[   
+<exception class="org.jboss.seam.ConcurrentRequestTimeoutException" logLevel="trace">
+	<http-error error-code="503" />
+</exception>]]>
+</programlisting>
+
+	<note>
+ 	 	<title>503 Service Unavailable (HTTP/1.1 RFC)</title>
+		<para>
+		The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay.
+		</para>
+	</note>
+	<para>
+		Alternatively you could redirect to an error page:</para>
+
+<programlisting role="XML"><![CDATA[
+<exception class="org.jboss.seam.ConcurrentRequestTimeoutException" logLevel="trace">
+	<end-conversation/>
+	<redirect view-id="/error.xhtml">
+		<message>The server is too busy to process your request, please try again later</message>
+	</redirect>
+</exception>]]>
+</programlisting>
+
+	 	<para>
+		ICEfaces, RichFaces Ajax and Seam Remoting can all handle HTTP error codes. Seam Remoting will pop up a dialog box showing the HTTP error and ICEfaces will indicate the error in it's connection status component. RichFaces Ajax provides the most complete support for handling HTTP errors by providing a user definable callback. For example, to show the error message to the user: </para>
+
+<programlisting><![CDATA[
+<script type="text/javascript">
+	A4J.AJAX.onError = function(req,status,message) { 
+		alert("message");    
+	};
+</script>]]>
+</programlisting>
+ 	 </section>
     
     <section>
       <title>RichFaces Ajax</title>