Conversation Explained

kailuowang — Fri, 19 Sep 2008 13:13:20 GMT

Current revision posted to Burrow by kailuowang on 19/09/2008 10:13:20 a.m.

Conversation Explained

Filed under: Conversation

Burrow Conversation is the core concept of NHibernate.Burrow. It was inspired by the Conversation concept in JBoss Seam .
The concept Conversation is to represent a stateful business transaction between end-user and system. Burrow manages NH session and transaction(optional) around conversation - it opens a session at the beginning of each conversation, and then close the session at the end of it (note: transaction strategy will be discussed later).
Burrow Conversation can be a long conversation between user and system - it can span over multiple http requests. In another sentence, Burrow Conversation allows end user to have a stateful business transaction with the system that spans over multiple http requests and responses. A common example of such long conversation is a checkout process - user enters shipping information, billing information and confirm the order information in multiple steps.
More importantly, like in Seam, one user can have multiple Burrow Conversations with the system simultaneously. For example, user can use one browser window/tab to checkout his shopping cart and another browser window/tab to process an order return and another browser window/tab to modify his/her account information. This feature is not only beneficial but also required because it's very hard for the web application to stop user from opening multiple browser window/tabs interacting with the system, which could cause serious concurrency problem if multi-conversation is not supported (This could happen if you simple store NHibernate Session in HttpSession to support long Session).

Short Burrow Conversation

By default, Burrow framework starts a conversation at the beginning of a request and commit/close it at the end of the request - we call it a short conversation. In terms of NH session management, it can be deemed as an implementation of the OpenSessionInView pattern, that is, one NHibernate session and one transaction per http request. This takes care of most business transactions that require only one http request, for example, modifying the customer information. Burrow takes care of this type of short conversation transparently - your code does not even need to be aware of Burrow Conversation.

Long Burrow Conversation

If you need to have a long conversation, you need to know a little about the NHibernate.Burrow.IConversation interface. We are going to explain it here.
In the request that you are going to start a long conversation - for example when you start a checkout process - you need to ask the current Burrow Conversation to span. Here is how:

//Get a facade instance of burrow, it's free
BurrowFramework bf = new BurrowFramework();
 
//ask the current IConversation to span with PostBacks
bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);

bf.CurrentConversation.FinishSpan(); // note: bf is the BurrowFramework instance. you can create it anywhere.

Burrow will commit the conversation at the end of this request - it will close the conversation. The next request will be assigned with a new conversation.
Also, you can cancel the conversation in the middle of it - for example user clicks the cancel button or something goes wrong. Here is how:

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.
bf.CloseWorkSpace();
 

After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.

Transaction Strategy in Conversation

I know you must have noticed the TransactionStrategy parameter we passed to SpanWithPostBacks() method, this parameter tells Burrow how to manage transactions for this long conversation. There are three of them for you to choose.

By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
TransactionStrategy.LongDBTransaction - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
TransactionStrategy.BusinessTransaction - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation.

<NHibernate.Burrow  manualTransactionManagement="true" >
    ...
</NHibernate.Burrow>

That is the handling for most long conversation scenarios. The following are a couple of special cases:
Span by URL
If you need the long conversation to span to another page, you still call SpanWithPostBack() method, but then you'll need to wrap the url of that page with conversation information so that Burrow will pick up the conversation for it. Here is how:

WebUtil wu = new WebUtil();
//use the following url instead of "~/anotherPage.aspx"
string urlToAnotherPage = wu.WrapUrlWithConversationInfo("~/anotherPage.aspx");

[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo("WorkSpace1")] //Define the page's workspace using Attribute
public partial class SharingConversations_Step06b : System.Web.UI.Page
{}

Start spanning in another page:

bf.CurrentConversation.SpanWithCookie("WorkSpace1");

Now if user opens APageInWorkSpaceA.aspx in the same browser session, the request will be using the same conversation. As for Finish or GiveUp, there is no difference from long conversation spanning with postbacks.
If attribute is not enough for defining page's workSpaceName, as it's static, you can create your own Handler-WorkSpace management mechanism and implement the IWorkSpaceNameSniffer interface in Web.Util, that interface is in charge of getting the WorkSpaceName of an IHttpHandler. You can set in the Burrow Configuration the type of implementation of that interface the system should use ( Please look at NHibernate.Burrow.IBurrowConfig ).

Conversation Explained

kailuowang — Sun, 07 Sep 2008 19:57:24 GMT

Revision 6 posted to Burrow by kailuowang on 07/09/2008 04:57:24 p.m.

Conversation Explained

Short Burrow Conversation

Long Burrow Conversation

//Get a facade instance of burrow, it's free
BurrowFramework bf = new BurrowFramework();
 
//ask the current IConversation to span with PostBacks
bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);

bf.CurrentConversation.FinishSpan(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.
bf.CloseWorkSpace();
 

After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.

Transaction Strategy in Conversation

By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
TransactionStrategy.LongDBTransaction - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
TransactionStrategy.BusinessTransaction - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation.

<NHibernate.Burrow  manualTransactionManagement="true" >
    ...
</NHibernate.Burrow>

WebUtil wu = new WebUtil();
//use the following url instead of "~/anotherPage.aspx"
string urlToAnotherPage = wu.WrapUrlWithConversationInfo("~/anotherPage.aspx");

[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo("WorkSpace1")] //Define the page's workspace using Attribute
public partial class SharingConversations_Step06b : System.Web.UI.Page
{}

Start spanning in another page:

bf.CurrentConversation.SpanWithCookie("WorkSpace1");

Conversation Explained

kailuowang — Sun, 07 Sep 2008 19:54:46 GMT

Revision 5 posted to Burrow by kailuowang on 07/09/2008 04:54:46 p.m.

Conversation Explained

Short Burrow Conversation

Long Burrow Conversation

//Get a facade instance of burrow, it's free
BurrowFramework bf = new BurrowFramework();
 
//ask the current IConversation to span with PostBacks
bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);

bf.CurrentConversation.FinishSpan(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.
bf.CloseWorkSpace();
 

After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.

Transaction Strategy in Conversation

By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
TransactionStrategy.LongDBTransaction - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
TransactionStrategy.BusinessTransaction - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation.

<NHibernate.Burrow  manualTransactionManagement="true" >
    ...
</NHibernate.Burrow>

WebUtil wu = new WebUtil();
//use the following url instead of "~/anotherPage.aspx"
string urlToAnotherPage = wu.WrapUrlWithConversationInfo("~/anotherPage.aspx");

[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo("WorkSpace1")] //Define the page's workspace using Attribute
public partial class SharingConversations_Step06b : System.Web.UI.Page
{}

Start spanning in another page:

bf.CurrentConversation.SpanWithCookie("WorkSpace1");

Conversation Explained

kailuowang — Sun, 07 Sep 2008 19:43:18 GMT

Revision 4 posted to Burrow by kailuowang on 07/09/2008 04:43:18 p.m.

BurrowConversationExplainedConversation Explained

Short Burrow Conversation

Long Burrow Conversation

//Get a facade instance of burrow, it's free
BurrowFramework bf = new BurrowFramework();
 
//ask the current IConversation to span with PostBacks
bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);

bf.CurrentConversation.FinishSpan(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.
bf.CloseWorkSpace();
 

After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.

Transaction Strategy in Conversation

By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
TransactionStrategy.LongDBTransaction - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
TransactionStrategy.BusinessTransaction - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation.

<NHibernate.Burrow  manualTransactionManagement="true" >
    ...
</NHibernate.Burrow>

WebUtil wu = new WebUtil();
//use the following url instead of "~/anotherPage.aspx"
string urlToAnotherPage = wu.WrapUrlWithConversationInfo("~/anotherPage.aspx");

[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo("WorkSpace1")] //Define the page's workspace using Attribute
public partial class SharingConversations_Step06b : System.Web.UI.Page
{}

Start spanning in another page:

bf.CurrentConversation.SpanWithCookie("WorkSpace1");

BurrowConversationExplained

kailuowang — Sun, 07 Sep 2008 18:12:01 GMT

Revision 3 posted to Burrow by kailuowang on 07/09/2008 03:12:01 p.m.

BurrowConversationExplained

Short Burrow Conversation

Long Burrow Conversation

//Get a facade instance of burrow, it's free
BurrowFramework bf = new BurrowFramework();
 
//ask the current IConversation to span with PostBacks
bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);

bf.CurrentConversation.FinishSpan(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.

bf.CurrentConversation.GiveUp(); // note: bf is the BurrowFramework instance. you can create it anywhere.
bf.CloseWorkSpace();
 

After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.

Transaction Strategy in Conversation

By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
TransactionStrategy.LongDBTransaction - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
TransactionStrategy.BusinessTransaction - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation.

<NHibernate.Burrow  manualTransactionManagement="true" >
    ...
</NHibernate.Burrow>

WebUtil wu = new WebUtil();
//use the following url instead of "~/anotherPage.aspx"
string urlToAnotherPage = wu.WrapUrlWithConversationInfo("~/anotherPage.aspx");

[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo("WorkSpace1")] //Define the page's workspace using Attribute
public partial class SharingConversations_Step06b : System.Web.UI.Page
{}

Start spanning in another page:

bf.CurrentConversation.SpanWithCookie("WorkSpace1");

BurrowConversationExplained

kailuowang — Sun, 07 Sep 2008 18:12:01 GMT

Revision 2 posted to Burrow by kailuowang on 07/09/2008 03:12:01 p.m.

BurrowConversationExplained

<p></p>
<p><strong>Burrow

Burrow Conversation</strong> is the core concept of NHibernate.Burrow. It was inspired by the Conversation concept in <a href="http://www.jboss.com/products/seam">JBoss JBoss Seam </a>.<br>The .
The concept Conversation is to represent a stateful business transaction between end-user and system. Burrow manages NH session and transaction(optional) around conversation - it opens a session at the beginning of each conversation, and then close the session at the end of it (note: transaction strategy will be discussed later).<br>Burrow
Burrow Conversation can be a long conversation between user and system - it can span over multiple http requests. In another sentence, Burrow Conversation allows end user to have a stateful business transaction with the system that spans over multiple http requests and responses. A common example of such long conversation is a checkout process - user enters shipping information, billing information and confirm the order information in multiple steps.<br>More
More importantly, like in Seam, one user can have multiple Burrow Conversations with the system simultaneously. For example, user can use one browser window/tab to checkout his shopping cart and another browser window/tab to process an order return and another browser window/tab to modify his/her account information. This feature is not only beneficial but also required because it's very hard for the web application to stop user from opening multiple browser window/tabs interacting with the system, which could cause serious concurrency problem if multi-conversation is not supported (This could happen if you simple store NHibernate Session in HttpSession to support long Session).
<h4><strong>Short

Short Burrow Conversation</strong></h4>By

Long Burrow Conversation</strong></h4>If

If you need to have a long conversation, you need to know a little about the NHibernate.Burrow.IConversation interface. We are going to explain it here.<br>In
In the request that you are going to start a long conversation - for example when you start a checkout process - you need to ask the current Burrow Conversation to span. Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #606060">

</span> <span style="color: #008000">//Get  //Get a facade instance of burrow, it's free</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #606060">   
</span>  BurrowFramework bf = <span style="color: #0000ff">new</span> new BurrowFramework();</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none;background-color: white; border-bottom-style: none"><span style="color: #606060">   
</span>  </pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family:consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #606060">     
</span> <span style="color: #008000">//ask  //ask the current IConversation to span with PostBacks</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #606060">   
</span>  bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);</pre></div></div>bf.CurrentConversation 

bf.CurrentConversation gives you the current IConversation (the interface represents Burrow Conversation) you are in. It was a short conversation before. IConversation.SpanWithPostBacks() tells the conversation to span with the post backs of a form. Now it becomes a long conversation. In pages that have only one form, this means that the conversation will be spanning as long as the user stays in the same page - the following postback requests will be using the same IConversation as this one. If the user goes to another page or close the current browser window/tab, the conversation will be discarded (If you need the conversation to span to another page, <a href="http://nhcontrib.wiki.sourceforge.net/BurrowConversationExplained#SpanByUrl">click click here</a>).<br>After ).
After the long business transaction is done - for example, the user finally confirmed the placement of the order in the checkout - you need to tell the Long Conversation to stop spanning (BTW, it's not needed for short conversation). Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white

bf.CurrentConversation.FinishSpan(); border-bottom-style: none">bf.CurrentConversation.FinishSpan(); // note: bf <span style="color: #0000ff">is</span> is the BurrowFramework instance. you can create it anywhere.</pre></div></div>Burrow 

Burrow will commit the conversation at the end of this request - it will close the conversation. The next request will be assigned with a new conversation.<br>Also,
Also, you can cancel the conversation in the middle of it - for example user clicks the cancel button or something goes wrong. Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white

bf.CurrentConversation.GiveUp(); border-bottom-style: none">bf.CurrentConversation.GiveUp(); // note: bf <span style="color: #0000ff">is</span> is the BurrowFramework instance. you can create it anywhere.</pre></div></div>
<p>The 

The conversation won't be discarded immediately, but Burrow will rollback the transaction and close the conversation at the end of this request. This way all the data changes in this conversation won't be committed to database, but you can still read data from Database in this request - for example to display some user friendly error message. If something quite fatal happens and you really want to immediately cancel the current conversation, you can either throw an exception or do the following:</p>
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color:white

bf.CurrentConversation.GiveUp(); border-bottom-style: none">bf.CurrentConversation.GiveUp(); <span style="color: #008000">// // note: bf is the BurrowFramework instance. you can create it anywhere.</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none">bf.CloseWorkSpace();</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white
bf.CloseWorkSpace();border-bottom-style: none"> </pre></div></div>
<p>After 
 

After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.</p>
<h4>Transaction

Transaction Strategy in Conversation</h4><br>I

By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
<li><strong>TransactionStrategy.LongDBTransaction</strong>
TransactionStrategy.LongDBTransaction - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
<li><strong>TransactionStrategy.BusinessTransaction</strong>
TransactionStrategy.BusinessTransaction - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation. </li></ul>Other

Other than these three transaction strategies, you can set Burrow to leave the transaction to your own management, that is Burrow will no longer manage the transaction, you can and need to use BurrowFramework.CurrentConversation.TransactionManager to manage it. To use manual transaction management, set manualTransactionManagement="true" in the NHibernate.Burrow Section
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #0000ff"><</span><span style="color: #800000">NHibernate.Burrow</span>

<NHibernate.Burrow  manualTransactionManagement="true" <span style="color: #0000ff">&gt;</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none">    >
    ...</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #0000ff">&lt;/</span><span style="color: #800000">NHibernate.Burrow</span><span style="color: #0000ff">&gt;</span></pre></div></div><br>That 
</NHibernate.Burrow>

That is the handling for most long conversation scenarios. The following are a couple of special cases:<br><a name="SpanByUrl"></a><strong>Span
Span by URL</strong><br>If
If you need the long conversation to span to another page, you still call SpanWithPostBack() method, but then you'll need to wrap the url of that page with conversation information so that Burrow will pick up the conversation for it. Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">WebUtil

WebUtil wu = <span style="color: #0000ff">new</span> new WebUtil();</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px;font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #008000">//use 
//use the following url instead of "~/anotherPage.aspx"</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #0000ff">string</span> "~/anotherPage.aspx"
string urlToAnotherPage = wu.WrapUrlWithConversationInfo(<span style="color: #006080">"~/anotherPage.aspx"</span>);</pre></div></div>If "~/anotherPage.aspx");

If you need a link on your page, you can either use this API to wrap the link, or you can use the NHibernate.Burrow.WebUtil.Controls.BurrowLink control. It inherits from HyperLink so you can use it exactly the same as HyperLink but it will automatically wrap the conversation information for you.<br><a name="SpanByCookie"></a><strong>Span
Span by Cookie</strong><br>Another
Another way to span a conversation is IConverastion.SpanWithCookie(string workSpaceName); This will store the conversation information into browser cookies. However not all pages that picks up that cookie will pick up that conversation, which is unmanageable and dangerous. The concept WorkSpaceName is introduced to help here. You can group your HttpHandlers using this WorkSpaceName - HttpHandlers defined with the same WorkSpaceName can be deemed as being in the same WorkSpace. When you call CurrentConversation.SpanWithCookie(string workSpaceName) only the HttpHandlers defined with the same workSpaceName will be sharing that conversation. Here is an example of how it works:<br>Define
Define the WorkSpaceName for APageInWorkSpaceA.aspx:<pre> </pre>
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size:8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo(<span style="color: #006080">"WorkSpace1"</span>)] <span style="color: #008000">//Define

[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo("WorkSpace1")] //Define the page's workspace using Attribute</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #0000ff">public</span> <span style="color: #0000ff">partial</span> <span style="color: #0000ff">class</span> 
public partial class SharingConversations_Step06b : System.Web.UI.Page</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">{}</pre></div></div>Start 
{}

Start spanning in another page:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white

bf.CurrentConversation.SpanWithCookie("WorkSpace1");border-bottom-style: none">bf.CurrentConversation.SpanWithCookie(<span style="color: #006080">"WorkSpace1"</span>);</pre></div></div>Now 

Now if user opens APageInWorkSpaceA.aspx in the same browser session, the request will be using the same conversation. As for Finish or GiveUp, there is no difference from long conversation spanning with postbacks.<br>If
If attribute is not enough for defining page's workSpaceName, as it's static, you can create your own Handler-WorkSpace management mechanism and implement the IWorkSpaceNameSniffer interface in Web.Util, that interface is in charge of getting the WorkSpaceName of an IHttpHandler. You can set in the Burrow Configuration the type of implementation of that interface the system should use ( Please look at NHibernate.Burrow.IBurrowConfig ).

BurrowConversationExplained

kailuowang — Sun, 07 Sep 2008 18:11:25 GMT

Revision 1 posted to Burrow by kailuowang on 07/09/2008 03:11:25 p.m.

<p></p>
<p><strong>Burrow Conversation</strong> is the core concept of NHibernate.Burrow. It was inspired by the Conversation concept in <a href="http://www.jboss.com/products/seam">JBoss Seam </a>.<br>The concept Conversation is to represent a stateful business transaction between end-user and system. Burrow manages NH session and transaction(optional) around conversation - it opens a session at the beginning of each conversation, and then close the session at the end of it (note: transaction strategy will be discussed later).<br>Burrow Conversation can be a long conversation between user and system - it can span over multiple http requests. In another sentence, Burrow Conversation allows end user to have a stateful business transaction with the system that spans over multiple http requests and responses. A common example of such long conversation is a checkout process - user enters shipping information, billing information and confirm the order information in multiple steps.<br>More importantly, like in Seam, one user can have multiple Burrow Conversations with the system simultaneously. For example, user can use one browser window/tab to checkout his shopping cart and another browser window/tab to process an order return and another browser window/tab to modify his/her account information. This feature is not only beneficial but also required because it's very hard for the web application to stop user from opening multiple browser window/tabs interacting with the system, which could cause serious concurrency problem if multi-conversation is not supported (This could happen if you simple store NHibernate Session in HttpSession to support long Session).
<h4><strong>Short Burrow Conversation</strong></h4>By default, Burrow framework starts a conversation at the beginning of a request and commit/close it at the end of the request - we call it a short conversation. In terms of NH session management, it can be deemed as an implementation of the OpenSessionInView pattern, that is, one NHibernate session and one transaction per http request. This takes care of most business transactions that require only one http request, for example, modifying the customer information. Burrow takes care of this type of short conversation transparently - your code does not even need to be aware of Burrow Conversation.
<h4><strong>Long Burrow Conversation</strong></h4>If you need to have a long conversation, you need to know a little about the NHibernate.Burrow.IConversation interface. We are going to explain it here.<br>In the request that you are going to start a long conversation - for example when you start a checkout process - you need to ask the current Burrow Conversation to span. Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #606060"> 1:</span> <span style="color: #008000">//Get a facade instance of burrow, it's free</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #606060"> 2:</span> BurrowFramework bf = <span style="color: #0000ff">new</span> BurrowFramework();</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #606060"> 3:</span> </pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #606060"> 4:</span> <span style="color: #008000">//ask the current IConversation to span with PostBacks</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #606060"> 5:</span> bf.CurrentConversation.SpanWithPostBacks(TransactionStrategy.BusinessTransaction);</pre></div></div>bf.CurrentConversation gives you the current IConversation (the interface represents Burrow Conversation) you are in. It was a short conversation before. IConversation.SpanWithPostBacks() tells the conversation to span with the post backs of a form. Now it becomes a long conversation. In pages that have only one form, this means that the conversation will be spanning as long as the user stays in the same page - the following postback requests will be using the same IConversation as this one. If the user goes to another page or close the current browser window/tab, the conversation will be discarded (If you need the conversation to span to another page, <a href="http://nhcontrib.wiki.sourceforge.net/BurrowConversationExplained#SpanByUrl">click here</a>).<br>After the long business transaction is done - for example, the user finally confirmed the placement of the order in the checkout - you need to tell the Long Conversation to stop spanning (BTW, it's not needed for short conversation). Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">bf.CurrentConversation.FinishSpan(); // note: bf <span style="color: #0000ff">is</span> the BurrowFramework instance. you can create it anywhere.</pre></div></div>Burrow will commit the conversation at the end of this request - it will close the conversation. The next request will be assigned with a new conversation.<br>Also, you can cancel the conversation in the middle of it - for example user clicks the cancel button or something goes wrong. Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">bf.CurrentConversation.GiveUp(); // note: bf <span style="color: #0000ff">is</span> the BurrowFramework instance. you can create it anywhere.</pre></div></div>
<p>The conversation won't be discarded immediately, but Burrow will rollback the transaction and close the conversation at the end of this request. This way all the data changes in this conversation won't be committed to database, but you can still read data from Database in this request - for example to display some user friendly error message. If something quite fatal happens and you really want to immediately cancel the current conversation, you can either throw an exception or do the following:</p>
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">bf.CurrentConversation.GiveUp(); <span style="color: #008000">// note: bf is the BurrowFramework instance. you can create it anywhere.</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none">bf.CloseWorkSpace();</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"> </pre></div></div>
<p>After you called bf.CloseWorkSpace(), you'll probably need to immediately redirect to another page as Burrow managed services are no longer available for this request.</p>
<h4>Transaction Strategy in Conversation</h4><br>I know you must have noticed the TransactionStrategy parameter we passed to SpanWithPostBacks() method, this parameter tells Burrow how to manage transactions for this long conversation. There are three of them for you to choose.
<ul>
<li>By default, that is, if you don't pass a TransactionStrategy to the method, Burrow will use one transaction per request pattern - it opens the transaction at the beginning of the request and commit it at the end of the request, which means that the long conversation is break into multiple atomic transactions, data change will be updated to DB on every request!
<li><strong>TransactionStrategy.LongDBTransaction</strong> - I know some people will need a long atomic conversation for some business transaction such as the example we just gave. If you pass this strategy to the method, Burrow will open keep the DB transaction alive until the conversation ends. Now the data changes will only get updated to DB after the whole long conversation is successfully finished. The long conversation is atomic now. However, the bad news is that now Burrow has to keep a long DB transaction and connection for this long conversation over multiple requests, even when user is thinking or wonders away. Fortunately we have the last strategy.
<li><strong>TransactionStrategy.BusinessTransaction</strong> - this strategy is the recommended one if you need an atomic but long conversation. This strategy will still use the one db transaction per request pattern - as in the default strategy. But, it will turn the NHibernate .Session.FlushMode to Never, and only flush the session when the conversation ends (or when you specifically command to flush session). This way, data change won't get updated to DB until the end of the long conversation. The conversation is atomic again. There is one issue here though, you lost the auto session flush feature NHibernate provides, one consequence will be that if you make some data change, it may not reflect in the query results later in the same long conversation. </li></ul>Other than these three transaction strategies, you can set Burrow to leave the transaction to your own management, that is Burrow will no longer manage the transaction, you can and need to use BurrowFramework.CurrentConversation.TransactionManager to manage it. To use manual transaction management, set manualTransactionManagement="true" in the NHibernate.Burrow Section
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #0000ff"><</span><span style="color: #800000">NHibernate.Burrow</span> manualTransactionManagement="true" <span style="color: #0000ff">></span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"> ...</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #0000ff"></</span><span style="color: #800000">NHibernate.Burrow</span><span style="color: #0000ff">></span></pre></div></div><br>That is the handling for most long conversation scenarios. The following are a couple of special cases:<br><a name="SpanByUrl"></a><strong>Span by URL</strong><br>If you need the long conversation to span to another page, you still call SpanWithPostBack() method, but then you'll need to wrap the url of that page with conversation information so that Burrow will pick up the conversation for it. Here is how:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">WebUtil wu = <span style="color: #0000ff">new</span> WebUtil();</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #008000">//use the following url instead of "~/anotherPage.aspx"</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none"><span style="color: #0000ff">string</span> urlToAnotherPage = wu.WrapUrlWithConversationInfo(<span style="color: #006080">"~/anotherPage.aspx"</span>);</pre></div></div>If you need a link on your page, you can either use this API to wrap the link, or you can use the NHibernate.Burrow.WebUtil.Controls.BurrowLink control. It inherits from HyperLink so you can use it exactly the same as HyperLink but it will automatically wrap the conversation information for you.<br><a name="SpanByCookie"></a><strong>Span by Cookie</strong><br>Another way to span a conversation is IConverastion.SpanWithCookie(string workSpaceName); This will store the conversation information into browser cookies. However not all pages that picks up that cookie will pick up that conversation, which is unmanageable and dangerous. The concept WorkSpaceName is introduced to help here. You can group your HttpHandlers using this WorkSpaceName - HttpHandlers defined with the same WorkSpaceName can be deemed as being in the same WorkSpace. When you call CurrentConversation.SpanWithCookie(string workSpaceName) only the HttpHandlers defined with the same workSpaceName will be sharing that conversation. Here is an example of how it works:<br>Define the WorkSpaceName for APageInWorkSpaceA.aspx:<pre> </pre>
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">[NHibernate.Burrow.WebUtil.Attributes.WorkSpaceInfo(<span style="color: #006080">"WorkSpace1"</span>)] <span style="color: #008000">//Define the page's workspace using Attribute</span></pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><span style="color: #0000ff">public</span> <span style="color: #0000ff">partial</span> <span style="color: #0000ff">class</span> SharingConversations_Step06b : System.Web.UI.Page</pre><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">{}</pre></div></div>Start spanning in another page:
<div style="border-right: gray 1px solid; padding-right: 4px; border-top: gray 1px solid; padding-left: 4px; font-size: 8pt; padding-bottom: 4px; margin: 20px 0px 10px; overflow: auto; border-left: gray 1px solid; width: 97.5%; cursor: text; line-height: 12pt; padding-top: 4px; border-bottom: gray 1px solid; font-family: consolas, 'Courier New', courier, monospace; background-color: #f4f4f4; max-height: 200px">
<div style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: #f4f4f4; border-bottom-style: none"><pre style="padding-right: 0px; padding-left: 0px; font-size: 8pt; padding-bottom: 0px; margin: 0em; overflow: visible; width: 100%; color: black; border-top-style: none; line-height: 12pt; padding-top: 0px; font-family: consolas, 'Courier New', courier, monospace; border-right-style: none; border-left-style: none; background-color: white; border-bottom-style: none">bf.CurrentConversation.SpanWithCookie(<span style="color: #006080">"WorkSpace1"</span>);</pre></div></div>Now if user opens APageInWorkSpaceA.aspx in the same browser session, the request will be using the same conversation. As for Finish or GiveUp, there is no difference from long conversation spanning with postbacks.<br>If attribute is not enough for defining page's workSpaceName, as it's static, you can create your own Handler-WorkSpace management mechanism and implement the IWorkSpaceNameSniffer interface in Web.Util, that interface is in charge of getting the WorkSpaceName of an IHttpHandler. You can set in the Burrow Configuration the type of implementation of that interface the system should use ( Please look at NHibernate.Burrow.IBurrowConfig ).