PmMda.Net.Dog.Updates namespace

Introduction

The Updates framework is used to opitimize the transfer of data objects from the client to the server.
Instead of transferring the whole data object graph from the client to the server only the modifications on the data objects are transferred.

The Update framework is used by the paging implementation
On the client side, the data object graph (DOG) is not fully available. Paging implies that only a part of the DOG is loaded. This means that the old update mechanism which compares the modified DOG with the original DOG to identify the deleted objects would not work. That's because the DOG, which was modified on the client, contains just a subset of the original DOG. It would not be possible to recognize if the data object was removed from the DOG or if the data object was just not loaded.

Design decisions

Load data (Transfer data object from the server to the client)

The data objects on the server are loaded completely using the persistence handler (PmMda.Net.Dog.Persistence.PersistenceHandler). The DOG on the server is fully available and therefore contains no paged collection. The data objects are transferred to the client using .NET remoting. .NET remoting serializes the data objects (i.e. to soap-xml) to send them over the network. It is possible to adjust this serialization. pmMDA uses this feature to omit the paged collection when data objects are transferred to the client.
When unloaded items of a paged collection are requested, the client loads these items as if they were root objects.

Store data (Transfer data objects from the client to the server)

The storange of items is done in three steps.

Transerring data object updates from the client to the server

When the data objects would be transferred from the client to the server using the same serialization as desribed above, the paged items would be omitted too. But it is not possible for the server to request the missing data objects from the client. This means that it is not possible to send the data objects from the client to the server the same way as pmMDA transfers them to the client.
The DOG on the client is just a subset of the original DOG because it may contain paged indexed properties. So it must be possible to update (store) a partial DOG. But if pmMDA transfers the partial graph to the server it is impossible to find the removed data objects. Therefore, the updates framework remembers the modification on each data object. These modifications are stored in the IDataObject.Update property. This property is of type DataObjectUpdate. The DataObjectUpdate contains the identifier and type of the data object and all modifications that have been made on the data object. These modifications are represented through the IUpdate interface.
Instead of transferring the root data object of the partial DOG to the server, pmMDA sends a data object update tree. This tree is represented through the DogUpdate class.

Executing the updates on the server

The server first loads all persistent data objects, that are represented through the retrieved data object updates, from the database and recreates the new objects. Thereby the data objects gets assigned to the corresponding data object update. It is importent that data objects which are referenced more than once in the partial DOG are not created or loaded twice. Therefore each data object is just represented through one data object update, even if it referenced more than once.
After the creation and loading of the objects, the server executes every data object update that is part of the dog update using the IUpdate.Execute method.

Storing the data objects

As last step the data objects that have been modified by the data object updates are stored using the default data object handler.

Updates

An update (IUpdate interface) represents one modification made on a data object. An update can be the changing of a single property value or the adding or removing of items to or from an indexed property.

Each update implements an Exceute method to redo the update on a specified data object which is passed as parameter.

There are several types of updates, which implement this iterface:

Class Description
ItemAdditionUpdate Represents an item which has been added to an indexed property.
ItemInsertionUpdate Represents an item which has been inserted into an indexed property.
ItemRemovalUpdate Represents an item which has been removed from an indexed property.
ItemRemovalAtUpdate Represents a removal of an item at a specified index.
ItemReplacementUpdate Represents a replacement of an item at a specified index with another item.
ListClearingUpdate Represents the clearing of all items from an indexed property.
PrimitiveFieldUpdate Represents an update of the value of a single property which stores primitive values.
SingleFieldUpdate Represents an update of the value of a single property which is of type data object
ItemUpdate Base class for all data object updates where the value represents a data object. The value may be the property value of single properties or the added, removed, inserted or replacing item of an indexed property.

The DataObjectUpdate represents all updates made on one data object. The sequence of the updates in the DataObjectUpdate must be ordered because it does matter whether the addition is done before or after the clearing of an indexed property. The oldest update is the first update in the DataObjectUpdate.Updates property.
A data object update contains just one PrimitiveFieldUpdate or SingleFieldUpdate per property. This update represent the value of the last assignment.

The DogUpdate class represents the root data object of a data object graph which should be stored.

Design diagram

Namespace diagram PmMda.Net.Dog.Updates

Descriptions for the classes, interfaces and types can be found in the API.

Typical use case

The following diagrams show a typical use case that demonstrates the useage of the updates framework.
The developer, who work on a client, loads a domain from the server. Then he modifies that domain and stores it.

Sequence diagram
Updates: Typical.use.case


Data object handler overview
Data object handlers overview