You can find the full source code for this website in the Seam package in the directory /examples/wiki. It is licensed under the LGPL.
In Seam, there are four different ways to start a conversation (or more precisely, to promote a temporary conversation to a long-running conversation, or LRC). Remember that there may be at most one active LRC per tab or window in a session (browser instance).
1) using annotations: @Begin
2) using XML: <begin-conversation/>
3) using Seam tags: <s:link propagation="begin"> or <s:button propagation="begin">
4) using code: Conversation.begin()
So this discussion focuses on why and how to do 1-4 above.
In most situations, the easiest way to start a conversation in Seam is declaratively using something like the following:
@Begin(join=true) public void doSomething() { ... }
When the method has completed processing (i.e. no RuntimeExceptions or ApplicationExceptions are thrown), then the current temporary conversation for the current thread/request is promoted to a LRC and assigned a conversationId.
From SiA book:
For many of Seam’s annotations that designate an action to be performed, such as @Begin and @End, Seam only performs the action if the method completes successfully according to Seam’s definition of success. For Seam to consider a method call successful, it must return without throwing an exception and it must return a non-null value unless it's a void method.
Sometimes you need a conversation to start a conversation prior to rendering a page:
<page view-id="/Process.xhtml"> <navigation from-action="#{foo.addCustomer}"> <begin-conversation/> <redirect view-id="/addCustomers.xhtml"/> </navigation> </page>
From SiA book:
The benefit of using a page action is that it can start a long-running conversation from a bookmarked page or direct link, rather than waiting for a JSF postback.
There may be times when you need to start a conversation from a GET request, in which case either the <begin-conversation> page descriptor tag or a UI component tag is a more appropriate choice.
Example:
<s:link id="register" view="/register.xhtml" value="Register New User" propagation="begin"/>
<s:button id="register" view="/register.xhtml" value="Register New User" propagation="begin"/>
And sometimes you need fine-grained control of when the LRC begins. In these cases, you should use the Conversation API.
Example:
public void myAction(){ if(doSomething()) { Conversation.instance().begin(); } else{ ... } }