[seam-commits] Seam SVN: r8882 - in trunk: seam-gen/resources/WEB-INF and 1 other directories.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Wed Sep 3 08:49:13 EDT 2008
Author: pete.muir at jboss.org
Date: 2008-09-03 08:49:13 -0400 (Wed, 03 Sep 2008)
New Revision: 8882
Modified:
trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml
trunk/seam-gen/resources/WEB-INF/pages.xml
trunk/seam-gen/view/layout/template.xhtml
Log:
JBSEAM-1832 part 2, docs and seam-gen for sending a 503
Modified: trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml 2008-09-03 11:45:02 UTC (rev 8881)
+++ trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml 2008-09-03 12:49:13 UTC (rev 8882)
@@ -1064,59 +1064,56 @@
concurrent-request-timeout="2000" />]]></programlisting>
<para>
- 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
- column of numbers). But what if we need to do a complex computation?
+ So far we've discussed AJAX requests which appear serial to the user -
+ 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 column of numbers). But what if we need to do
+ a complex computation thats going to take a minute?
</para>
+
<para>
- For heavy computation we should use a truly asynchronous (poll based)
- approach — the client sends an AJAX request to the server, which
- causes action to be executed asynchronously on the server (so the the
- response to the client is immediate); the client then polls the server
- for updates. This is useful when you have a long-running action for
- which it is important that every action executes (you don't want some to
- be dropped as duplicates, or to timeout).
+ For heavy computation we should use a poll based approach — the
+ client sends an AJAX request to the server, which causes action to be
+ executed asynchronously on the server (the response to the client is
+ immediate) and the client then polls the server for updates. This is
+ good approach when you have a long-running action for which it is
+ important that every action executes (you don't want some to timeout).
</para>
- <para>
- <emphasis>How should we design our conversational AJAX application?</emphasis>
- </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
- approach.
- </para>
+ <para>
+ Well first, you need to decide whether you want to use the simpler
+ "serial" request or whether you want to use a polling approach.
+ </para>
- <para>
- If you go for a "synchronous" approach, then you need to make an
- estimate of how long your AJAX request will take to complete - is it
- much shorter than the concurrent request timeout? If not, you probably
- want to alter the concurrent request timeout for this method (as
- discussed above). Next you probably want a queue on the client side to
- prevent flooding the server with requests. If the event occurs often
- (e.g. a keypress, onblur of input fields) and immediate update of the
- client is not a priority you should set a request delay on the client
- side. When working out your request delay, factor in that the event may
- also be queued on the server side.
- </para>
+ <para>
+ If you go for a "serial" requests, then you need to estimate how long
+ your request will take to complete - is it much shorter than the
+ concurrent request timeout? If not, you probably want to alter the
+ concurrent request timeout for this page (as discussed above). You
+ probably want a queue on the client side to prevent flooding the
+ server with requests. If the event occurs often (e.g. a keypress,
+ onblur of input fields) and immediate update of the client is not a
+ priority you should set a request delay on the client side. When
+ working out your request delay, factor in that the event may also be
+ queued on the server side.
+ </para>
- <para>
- Finally, the client library may provide an option to abort unfinished
- duplicate requests in favor of the most recent. You need to be careful
- with this option as it can lead to flooding of the server with requests
- if the server is not able to abort the unfinished request.
- </para>
+ <para>
+ Finally, the client library may provide an option to abort unfinished
+ duplicate requests in favor of the most recent.
+ </para>
- <para>
- Using a poll-style design requires less fine-tuning. You just mark your
- action method <literal>@Asynchronous</literal> and decide on a polling
- interval:
- </para>
+ <para>
+ Using a poll-style design requires less fine-tuning. You just mark your
+ action method <literal>@Asynchronous</literal> and decide on a polling
+ interval:
+ </para>
- <programlisting role="JAVA"><![CDATA[int total;
+ <programlisting role="JAVA"><![CDATA[int total;
// This method is called when an event occurs on the client
// It takes a really long time to execute
@@ -1130,61 +1127,119 @@
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 an
+ 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>
+ <section>
+ <title>RichFaces Ajax</title>
- <para>
- RichFaces Ajax is the AJAX library most commonly used with Seam, and
- provides all the controls discussed above:
- </para>
+ <para>
+ RichFaces Ajax is the AJAX library most commonly used with Seam, and
+ provides all the controls discussed above:
+ </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>eventsQueue</literal> — provide a queue in which
- events are placed. All events are queued and requests are sent to
- the server serially. This is useful if the request can to the
- server can take some time to execute (e.g. heavy computation,
- retrieving information from a slow source) as the server isn't
- flooded.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>ignoreDupResponses</literal> — ignore the response
- produced by the request if a more recent 'similar' request is
- already in the queue. ignoreDupResponses="true" does <emphasis>not
- cancel</emphasis> the the processing of the request on the server
- side — just prevents unnecessary updates on the client side.
- </para>
- <para>
- This option should be used with care with Seam's conversations as
- it allows multiple concurrent requests to be made.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>requestDelay</literal> — defines the time (in ms.)
- that the request will be remain on the queue. If the request has
- not been processed by after this time the request will be sent
- (regardless of whether a response has been received) or discarded
- (if there is a more recent similar event on the queue).
- </para>
- <para>
- This option should be used with care with Seam's conversations as
- it allows multiple concurrent requests to be made. You need to be
- sure that the delay you set (in combination with the concurrent
- request timeout) is longer than the action will take to execute.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><a:poll reRender="total" interval="1000" /></literal> —
- Polls the server, and rerenders an area as needed
- </para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>eventsQueue</literal> — provide a queue in which
+ events are placed. All events are queued and requests are sent to
+ the server serially. This is useful if the request can to the
+ server can take some time to execute (e.g. heavy computation,
+ retrieving information from a slow source) as the server isn't
+ flooded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ignoreDupResponses</literal> — ignore the response
+ produced by the request if a more recent 'similar' request is
+ already in the queue. ignoreDupResponses="true" does <emphasis>not
+ cancel</emphasis> the the processing of the request on the server
+ side — just prevents unnecessary updates on the client side.
+ </para>
+ <para>
+ This option should be used with care with Seam's conversations as
+ it allows multiple concurrent requests to be made.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>requestDelay</literal> — defines the time (in ms.)
+ that the request will be remain on the queue. If the request has
+ not been processed by after this time the request will be sent
+ (regardless of whether a response has been received) or discarded
+ (if there is a more recent similar event on the queue).
+ </para>
+ <para>
+ This option should be used with care with Seam's conversations as
+ it allows multiple concurrent requests to be made. You need to be
+ sure that the delay you set (in combination with the concurrent
+ request timeout) is longer than the action will take to execute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><a:poll reRender="total" interval="1000" /></literal> —
+ Polls the server, and rerenders an area as needed
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
- </section>
</chapter>
\ No newline at end of file
Modified: trunk/seam-gen/resources/WEB-INF/pages.xml
===================================================================
--- trunk/seam-gen/resources/WEB-INF/pages.xml 2008-09-03 11:45:02 UTC (rev 8881)
+++ trunk/seam-gen/resources/WEB-INF/pages.xml 2008-09-03 12:49:13 UTC (rev 8882)
@@ -50,6 +50,10 @@
<message>Your session has timed out, please try again</message>
</redirect>
</exception>
+
+ <exception class="org.jboss.seam.ConcurrentRequestTimeoutException" logLevel="trace">
+ <http-error error-code="503" />
+ </exception>
<exception>
<redirect view-id="/error.xhtml">
Modified: trunk/seam-gen/view/layout/template.xhtml
===================================================================
--- trunk/seam-gen/view/layout/template.xhtml 2008-09-03 11:45:02 UTC (rev 8881)
+++ trunk/seam-gen/view/layout/template.xhtml 2008-09-03 12:49:13 UTC (rev 8882)
@@ -11,6 +11,13 @@
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>@projectName@</title>
<link href="stylesheet/theme.css" rel="stylesheet" type="text/css" />
+ <script type="text/javascript">
+ A4J.AJAX.onError = function(req,status,message) {
+
+ alert(message);
+
+ };
+ </script>
</head>
<body>
More information about the seam-commits
mailing list