[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Peter Muir
peter at bleepbleep.org.uk
Tue Sep 4 13:00:42 EDT 2007
User: pmuir
Date: 07/09/04 13:00:42
Modified: doc/reference/en/modules conversations.xml concepts.xml
Log:
Some initial docs on ajax apps with conversations and concurrent requests
Revision Changes Path
1.35 +149 -1 jboss-seam/doc/reference/en/modules/conversations.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: conversations.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/conversations.xml,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -b -r1.34 -r1.35
--- conversations.xml 21 Aug 2007 13:13:43 -0000 1.34
+++ conversations.xml 4 Sep 2007 17:00:40 -0000 1.35
@@ -869,4 +869,152 @@
</section>
+ <section>
+ <title>Concurrent calls to conversational components</title>
+
+ <para>
+ A general discussion of concurrent calls to Seam components can be
+ found in <xref linkend="concurrency" />. Here we will discuss
+ the most common situation in which you will encounter concurrency
+ — accessing conversational components from AJAX requests.
+ We're going to discuss the options that a Ajax client library should
+ provide to control events originating at the client — and we'll
+ look at the options RichFaces Ajax gives you.
+ </para>
+
+ <para>
+ Conversational components don't allow real concurrent access therefore
+ Seam queues each request to process them serially. This allows each
+ request to be executed in a deterministic fashion and the result
+ returned to the client. However, a simple queue isn't that great —
+ firstly, if a method is, for some reason, taking a very long time to
+ complete, running over and over again whenever the client generates a
+ request is bad (potential for Denial of Service attacks), and secondly,
+ AJAX is often to used to provide a quick status update to the user, so
+ continuing to run the action after a long time isn't useful.
+ </para>
+
+ <para>
+ Therefore 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
+ flood the server with AJAX events!
+ </para>
+
+ <para>
+ We can set a sensible default for the concurrent request timeout (in
+ ms) in components.xml:
+ </para>
+
+ <programlisting><![CDATA[<core:manager concurrent-request-timeout="500" />]]></programlisting>
+
+ <para>
+ We can also fine tune the concurrent request timeout for a request:
+ </para>
+
+ <programlisting><![CDATA[public void getTotal() {
+ Manager.instance().setConcurrentRequestTimeout(1000);
+ return someReallyComplicatedCalculation();
+}]]></programlisting>
+
+ <para>
+ So far we've discussed synchronous AJAX requests - the client tells the
+ server that an event has occur, and then rerenders part of the page based
+ on the result. But we could also use asynchronous (poll based) requests
+ — the client sends an AJAX request to the server, which causes an
+ 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).
+ </para>
+
+ <para>
+ <emphasis>But how should we design our conversational AJAX application?</emphasis>
+ </para>
+
+ <para>
+ Well first, you need to decide whether you want to use the simpler push-
+ style or whether you want to add using a poll-style approach.
+ </para>
+
+ <para>
+ If you go for a synchronous request 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>
+ 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>
+ 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><![CDATA[int total;
+
+// This method is called when an event occurs on the client
+// It takes a really long time to execute
+ at Asynchronous
+public void calculateTotal() {
+ total = someReallyComplicatedCalculation();
+}
+
+// This method is called as the result of the poll
+// It's very quick to execute
+public int getTotal() {
+ return total;
+}]]></programlisting>
+
+ <section>
+ <title>RichFaces Ajax</title>
+
+ <para>
+ RichFaces Ajax is the most common Ajax library 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ignoreDupRequests</literal> — if a duplicate request
+ occurs, the unfinished event will be aborted
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>requestDelay</literal> — Delays the sending of the
+ request to the server
+ </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>
</chapter>
\ No newline at end of file
1.66 +1 -1 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.65
retrieving revision 1.66
diff -u -b -r1.65 -r1.66
--- concepts.xml 21 Jul 2007 21:45:12 -0000 1.65
+++ concepts.xml 4 Sep 2007 17:00:41 -0000 1.66
@@ -241,7 +241,7 @@
</sect2>
- <sect2>
+ <sect2 id="concurrency">
<title>Concurrency model</title>
<para>
Neither the servlet nor EJB specifications define any facilities for managing concurrent requests
More information about the jboss-cvs-commits
mailing list