From seam-commits at lists.jboss.org Fri Jan 25 08:45:17 2008
Content-Type: multipart/mixed; boundary="===============1943437028761389298=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN:  r7233 - trunk/doc/reference/en/modules.
Date: Fri, 25 Jan 2008 08:45:17 -0500
Message-ID: <E1JIOrt-0005U9-7k@committer01.frg.pub.inap.atl.jboss.com>

--===============1943437028761389298==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: pete.muir(a)jboss.org
Date: 2008-01-25 08:45:17 -0500 (Fri, 25 Jan 2008)
New Revision: 7233

Modified:
   trunk/doc/reference/en/modules/conversations.xml
Log:
Remove explicit conversation id docs, merge in blog article to natural conv=
ersation docs

Modified: trunk/doc/reference/en/modules/conversations.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/doc/reference/en/modules/conversations.xml	2008-01-25 12:56:35 UT=
C (rev 7232)
+++ trunk/doc/reference/en/modules/conversations.xml	2008-01-25 13:45:17 UT=
C (rev 7233)
@@ -559,61 +559,71 @@
     </section>
     =

     <section>
-        <title>Using an "explicit" conversation id</title>
-        <para>
-            Ordinarily, Seam generates a meaningless unique id for each co=
nversation
-            in each session. You can customize the id value when you begin=
 the =

-            conversation.
-        </para>
-        =

-        <para>
-            This feature can be used to customize the conversation id gene=
ration
-            algorithm like so:
-        </para>
-
-        <programlisting><![CDATA[@Begin(id=3D"#{myConversationIdGenerator.=
nextId}") =

-public void editHotel() { ... }]]></programlisting>
-
-        <para>
-            Or it can be used to assign a meaningful conversation id:
-        </para>
-        =

-        <programlisting><![CDATA[@Begin(id=3D"hotel#{hotel.id}") =

-public String editHotel() { ... }]]></programlisting>
-
-        <programlisting><![CDATA[@Begin(id=3D"hotel#{hotelsDataModel.rowDa=
ta.id}") =

-public String selectHotel() { ... }]]></programlisting>
-
-        <programlisting><![CDATA[@Begin(id=3D"entry#{params['blogId']}")
-public String viewBlogEntry() { ... }]]></programlisting>
-
-        <programlisting><![CDATA[@BeginTask(id=3D"task#{taskInstance.id}") =

-public String approveDocument() { ... }]]></programlisting>
-        =

-        <para>
-            Clearly, these example result in the same conversation id ever=
y time
-            a particular hotel, blog or task is selected. So what happens =
if a conversation
-            with the same conversation id already exists when the new conv=
ersation
-            begins? Well, Seam detects the existing conversation and redir=
ects
-            to that conversation without running the <literal>@Begin</lite=
ral> =

-            method again. This feature helps control the number of workspa=
ces
-            that are created when using workspace management.
-        </para>
-
-    </section>
-    =

-    <section>
         <title>Natural conversation ids</title>
         <para>
             When working with conversations that deal with persistent obje=
cts, it may be =

             desirable to use the natural business key of the object instea=
d of the standard,
-            "surrogate" conversation id.
+            "surrogate" conversation id:
         </para>
         =

+        <itemizedlist>
+            <listitem>
+               <para>
+                  <emphasis>Easy redirect to existing conversation</emphas=
is>
+               </para>
+               <para>
+                  It can be useful to redirect to an existing conversation=
 if =

+                  the user requests the same operation twice. Take this ex=
ample:
+               </para>
+               <quote>
+                  You are on ebay, half way through paying for an item you=
 just =

+                  won as a Christmas present for your parents. Lets say yo=
u're
+                  sending it straight to them - you enter your payment det=
ails =

+                  but you can't remember their address. You accidentally r=
euse =

+                  the same browser window finding out their address. Now y=
ou =

+                  need to return to the payment for the item.
+               </quote>
+               <para>
+                  With a natural conversation its really easy to have the =
user
+                  rejoin the existing conversation, and pick up where they=
 left =

+                  off - just have them to rejoin the payForItem conversati=
on =

+                  with the itemId as the conversation id.
+               </para>
+            </listitem>
+            <listitem>
+               <para>
+                  <emphasis>User friendly URLs</emphasis>
+               </para>
+               =

+               <para>
+                  For me this consists of a navigable =

+                  hierarchy (I can navigate by editing the url) and a mean=
ingful
+                  URL (like this Wiki uses - so don't identify things by r=
andom =

+                  ids). For some applications user friendly URLs are less =

+                  important, of course.
+               </para>
+
+               <para>
+                  With a natural conversations, when you are building your=
 hotel =

+                  booking system (or, of course, whatever your app is) you=
 can =

+                  generate a URL like =

+                  <literal>http://seam-hotels/book.seam?hotel=3DBestWester=
nAntwerpen</literal> =

+                  (of course, whatever parameter <literal>hotel</literal> =
maps =

+                  to on your domain model must be unique) and with URLRewr=
ite =

+                  easily transform this to =

+                  http://seam-hotels/book/BestWesternAntwerpen.
+               </para>
+               =

+               <para>
+                  Much better!
+               </para> =

+            </listitem>
+        </itemizedlist>
+        =

         <section>
-            <title>Configuration</title>        =

+            <title>Creating a natural conversation</title>        =

             <para>
-                Natural conversations are configured in <literal>pages.xml=
</literal>: =

+                Natural conversations are defined in <literal>pages.xml</l=
iteral>: =

             </para>
             =

             <programlisting><![CDATA[  <conversation name=3D"PlaceBid"
@@ -621,7 +631,7 @@
                   parameter-value=3D"#{auction.auctionId}"/>]]></programli=
sting>
                   =

             <para>
-                The first thing to note from the above configuration is th=
at the conversation
+                The first thing to note from the above definition is that =
the conversation
                 has a name, in this case <literal>PlaceBid</literal>.  Thi=
s name uniquely
                 identifies this particular named conversation, and is used=
 by the =

                 <literal>page</literal> definition to identify a named con=
versation to participate
@@ -631,8 +641,7 @@
             <para>
                 The next attribute, <literal>parameter-name</literal> defi=
nes the request parameter =

                 that will contain the natural conversation id, in place of=
 the default conversation =

-                id parameter (which is typically either <literal>cid</lite=
ral> or <literal>conversationId</literal>).  =

-                In this example, the <literal>parameter-name</literal> is =
<literal>auctionId</literal>.  =

+                id parameter. In this example, the <literal>parameter-name=
</literal> is <literal>auctionId</literal>.  =

                 This means that instead of a conversation parameter like <=
literal>cid=3D123</literal> =

                 appearing in the URL for your page, it will contain <liter=
al>auctionId=3D765432</literal> =

                 instead.
@@ -646,7 +655,7 @@
             </para>
             =

             <para>
-                The next step is to configure which pages will participate=
 in the named conversation.
+                Next, we define which pages will participate in the named =
conversation.
                 This is done by specifying the <literal>conversation</lite=
ral> attribute for a
                 <literal>page</literal> definition:
             </para>
@@ -669,7 +678,7 @@
             <para>
                 When starting, or redirecting to, a natural conversation t=
here are a number
                 of options for specifying the natural conversation name.  =
Let's start by looking at
-                the following page configuration:
+                the following page definition:
             </para>
             =

             <programlisting><![CDATA[  <page view-id=3D"/auction.xhtml">
@@ -683,7 +692,7 @@
             <para>
                 From here, we can see that invoking the action <literal>#{=
bidAction.placeBid}</literal>
                 from our auction view (by the way, all these examples are =
taken from the seamBay example in Seam),
-                that we will be redirected to <literal>/bid.xhtml</literal=
>, which as we saw previously
+                that we will be redirected to <literal>/bid.xhtml</literal=
>, which, as we saw previously,
                 is configured with the natural conversation <literal>Place=
Bid</literal>.  The declaration for
                 our action method looks like this:                =

             </para>
@@ -696,7 +705,7 @@
                 redirection to the named conversation occurs as part of na=
vigation rules, after the =

                 action method has already been invoked.  This is a problem=
 when redirecting to an
                 existing conversation, as redirection needs to be occur be=
fore the action method is =

-                invoked.  To cater for this, it is necessary to specify th=
e conversation name when
+                invoked.  Therefore it is necessary to specify the convers=
ation name when
                 the action is invoked.  One way of doing this is by using =
the <literal>s:conversationName</literal>
                 tag:
             </para>


--===============1943437028761389298==--