Generated code - Unit of work and field data versioning, Adapter

Preface

Sometimes actions on entities span a longer timeframe and / or multiple screens. It's then often impossible to start a database transaction as user-interaction during a transaction should be avoided. To track all the changes made and to persist them in one transaction can then be a tedious task. With the UnitOfWork2 class this can be solved. The UnitOfWork2 class lets you collect actions on entities or collections of entities and can perform these actions in one go. The UnitOfWork2 class is serializable which means it can travel accross remoting boundaries. Entities and entity collections added to the UnitOfWork2 class are not aware that they're added to that class, so if you decide not to continue with a given UnitOfWork2 instance you can simply let it get out of scope. UnitOfWork2 objects figure out the order in which actions have to be performed automatically: first Inserts, then Updates and then Deletes. This is controllable, see the section below about Specifying the order in which the actions are executed.

LLBLGen Pro also supports versioning of entity fields. This can be handy in multi-page wizards which edit portions of an entity. By utilizing the versioning capability you can rollback to a previous set of field values for a particular entity.

UnitOfWork usage: single entities

Actions collected by the UnitOfWork2 class are not yet performed, but are performed when the UnitOfWork2's Commit() method is called. A UnitOfWork2 class can work with single entities or collections of entities. This paragraph discusses the UnitOfWork2 class with single entities. A UnitOfWork2 class acts like a container for UnitOfWorkElement2 objects which can contain an entity and are defined for a given action: save or delete (update / delete directly are also supported). You can't use the UnitOfWork2 to store select actions.

The UnitOfWork2 class works with Add methods for an entity and a given action: AddForSave() or AddForDelete(). You can specify additional parameters for the action: recursive saves and save / delete restriction filters. A delete action for a new entity is ignored. The following example illustrates both methods. First a recursive save is added and after that a delete action. The actions are not executed until Commit() is called. Commit() always expects a DataAccessAdapter object which is used to run the persistent actions. You don't have to start a transaction yourself, if the passed in DataAccessAdapter is not controlling a transaction yet, a new one is started. You can commit more than one UnitOfWork2 object in one transaction, simply pass the same DataAccessAdapter object to all Commit() calls, passing false for autoCommit. Commit() can also autocommit the transaction, if all the actions succeed, you then have to use the overload of Commit() which expects a boolean, autoCommit.

After the Commit() action, the database has two new entities, the customer and the address, and the product entity is deleted. These actions are taken place inside a new transaction and when Commit() was called, which autocommits the transaction at the end of the actions.

UnitOfWork usage: entity collections

Sometimes a complete collection of entities has to be saved, or deleted. Instead of adding all entities individually (you could of course opt for that), you can add a collection in one go for a given action: save or delete. The following example loads an Order and its OrderDetail entities and deletes the OrderDetail entities while updating the Order entity. The entities in the collection are examined when Commit() is called. This means that an entity which is in the collection when the collection is added to the UnitOfWork2 object and is removed from that collection after that action but before Commit() is called, is not processed by the UnitOfWork2, as the entity is no longer part of the collection being processed.


When Commit() is called, first all entities in the collection added are added as entities for the Delete action. After that, all actions are executed, first the save action, then the deletes.

UnitOfWork usage: stored procedures

The UnitOfWork2 class is able to collect calls to stored procedures as well, and lets you schedule these calls with the work already added to the UnitOfWork2 class, using four slots. The support for stored procedure calls is done through delegates. This means that you can use this feature also for your own methods, as long as there is a delegate defined for that method. If you want to accept the actual DataAccessAdapter object, you have to make sure the method accepts a DataAccessAdapter object as the last parameter.

Adding a stored procedure call can only be done for Action procedure calls. To add a stored procedure call, you'll use the AddCallBack method, which accepts a System.Delegate object, a slot enum value which schedules the call, and zero or more parameters. Below are the slot definitions listed on which you can schedule a stored procedure call.

Enum Value	Description
PreEntityInsert	Execute the callback before the first entity is inserted.
PreEntityUpdate	Execute the callback after the last entity has been inserted but before the first entity will be updated.
PreEntityDelete	Execute the callback after the last entity has been updated but before the first entity will be deleted.
PostEntityDelete	Execute the callback after the last entity has been deleted.

LLBLGen Pro generates for each Action procedure call a Delegate definition. Using such a generated delegate definition, you could add a call to a stored procedure using the following code. It adds a call to the ClearTestRunData stored procedure. It specifies that the DataAccessAdapter has to be passed into the procedure so the call will run in the same transaction as the rest of the calls the UnitOfWork object will make. If that's not done, the action procedure will create it's own DataAccessAdapter object. The call is scheduled right before the Delete calls are made on entities.

UnitOfWork usage: DeleteEntitiesDirectly and UpdateEntitiesDirectly

Besides adding calls to stored procedures, the UnitOfWork2 object can also accept calls to DeleteEntitiesDirectly and UpdateEntitiesDirectly. You add calls to one of these methods by using one of the overloads of AddDeleteEntitiesDirectlyCall or AddUpdateEntitiesDirectlyCall, by specifying the required parameters for these calls as if you'd make them directly. The calls will be executed on the DataAccessAdapter object used by Commit. The DeleteEntitiesDirectly call will be executed after the entity delete actions but before the PostEntityDelete callbacks. The UpdateEntitiesDirectly call will be executed after the last entity has been updated but before the PreEntityUpdate callbacks.

UnitOfWork usage: Monitoring

In some cases you want to know what a UnitOfWork2 object contains, and what for example the order is in which actions will take place, for example what the real amount of entities is which will be inserted or are inserted. LLBLGen Pro's UnitOfWork2 offers various ways to retrieve this data. For example, the UnitOfWork2 classes offer you to pre-calculate the save queue, by the method ConstructSaveProcessQueues. This method constructs the save queues for insert and update, and is also used by Commit(). After this method call, you can call GetInsertQueue and GetUpdateQueue, to retrieve the exact queue of entities which will be processed during Commit for a save action. Otherwise it would be hard to figure out the exact amount, because an entity which is added using AddForSave() and specified to be saved recursively, could save more entities than itself, due to the recursive save.

These save queues are kept after Commit(). So you can also call GetInsertQueue and GetUpdateQueue after Commit() to see what happened during Commit. For deletes, you can use GetEntityElementsToDelete because Deletes are never recursive. UnitOfWork2 also offers methods to retrieve the elements added for insert and update, as well as other elements being added. You can then use the returned collections to for example remove an element from the UnitOfWork2 object. The LLBLGen Pro reference manual will show you all methods and properties available to you for information retrieval.

LLBLGen Pro uses ConstructSaveProcessQueues before a UnitOfWork2 object is serialized into a remoting stream, to be sure all elements to send over the wire are indeed elements which participate in a save action. You can switch this off, by setting unitOfWork2.OptimizedSerialization to false.

Specifying the order in which the actions are executed

The UnitOfWork2 class typically executes the actions added to it in the following order: CallBacks for the PreEntityInsert slot, Inserts, CallBacks for the PreEntityUpdate slot, Updates, UpdateEntitiesDirectly calls, CallBacks for the PreEntityDelete slot, Deletes, CallBacks for the PostEntityDelete slot, DeleteEntitiesDirectly calls. This order can be too limited, for example if you first have to delete an entity before a new insert can take place because the entity to insert has the same value for a field with a unique constraint. LLBLGen Pro lets you define entity oriented actions to be ordered in a different order, so the UnitOfWork2 class will for example first execute the deletes and then the updates. This is done by specifying a list of UnitOfWorkBlockType values for the property unitOfWork2.CommitOrder. By default you don't have to specify any commit order, the UnitOfWork2 class will follow the sequence as specified above. However as soon as you specify a list of UnitOfWorkBlockType values for CommitOrder, it will use that list instead. This means that if you omit a block type, these actions aren't executed at all. Duplicates are filtered out so specifying a blocktype twice has no effect, the second one is ignored.

CallBacks with the name Preaction or Postaction belong to the blocktype of action and will be executed in that block, in the same order as described above, so for example PreUpdateEntity callbacks are executed before the updates, when the blocktype for updates is specified to be executed.

Field data versioning

One innovative feature of LLBLGen Pro is its field data versioning. The fields of an entity, say a CustomerEntity, can be versioned and saved under a name inside the entity object itself. Later, you can decide to rollback the entity's field values at a later time. The versioned field data is contained inside the entity and can pass with the entity remoting borders and is saved inside the XML produced by WriteXml(). All fields are versioned at once, you can't version a field's values individually.

The following example loads an entity, saves its field values, alters them and then rolls them back, when an exception occurs.