Burrow is a light weight middleware developed to support .Net applications using NHibernate (maybe also referred as NH in this article) as ORM framework.
Using Asp.net with NHibernate could be a challenge because of the fact that NHibernate is a stateful environment while Asp.net is a stateless framework. Burrow can help solve this conflict by providing advanced and smart session/transaction management and other facilitates.
The core concept of Burrow is Burrow Conversation, which was inspired by the Conversation concept in JBoss Seam . Conversation is designed to represent a stateful business conversation between end-user and system. Burrow manages NH session around conversation - it opens a session at the beginning of each conversation, and then close the session at the end of the conversation.
For business transactions that can be taken care of in one http request response round trip, for example, modifying the customer information, Burrow takes care of the conversation transparently, which means that your code does not need to be aware of 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. 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.
OpenSessionInView pattern isn't hard to implement, but the real power Burrow provides is that Burrow conversation can span over multiple http requests, in another sentence, Burrow Conversation allows end user to have a stateful business conversation with the system that spans over multiple http request and response. For example the checkout process is a typical business transaction that can span over multiple request/response dialogues - user needs to enter shipping information, billing information and confirm the order information. Through conversation, Burrow can also make sure that such long business transaction is atomic and isolated by applying atomic transaction strategy. More importantly, like in Seam, one user can have multiple Burrow conversations with the system simultaneously.
For more information about Burrow Conversation, click here.
To demonstrate Burrow, we used the basic example from the well-known article "NHibernate Best Practices with ASP.NET" from CodeProject.com. We have two versions of modifications of it:
Most of the code in BasicCore example is the same as the original basic sample to demonstrate that Burrow can be used with any design and architecture. We added a PlaceOrder.aspx to demonstrate what Burrow can enable - business transaction that spans over multiple requests. This page is like a checkout page, but tweaked for demo purpose. The steps are simple as the point here is to demonstrate the multiple steps.
In step 1, "bf.CurrentConversation.SpanWithPostBacks();" is the line to let the system know that the current conversation needs to span after the end of the current request. Without this line, the current conversation will closed at the end of the request (as in OpenSessionPerView mode). Then the code created an order entity and store it into the bf.CurrentConversation.Items["placingOrder"]. IConversation.Items is a data container through which you can store the data into the current conversation so that the data will have the same life cycle as the conversation. Step2 simple modifies the shipToName property of the placingOrder. The finish step finally persists the order and calls bf.CurrentConversation.FinishSpan(); then Burrow will commit and close this multi-request conversation at the end of this request.
For more information about NHibernate.Burrow, here is a guide to the pages of this wiki site:
Get Started - tells how to setup the Burrow framework.
Burrow Conversation Explained - gives more detail in long conversation.
StatefulField Attributes - explains how Burrow.WebUtil attributes can simplify states maintenance for ASP.NET controls and pages
FAQ - you know what it is.