Introduction to Deltas
Deltas are data structures that describe relative change. Deltas describe how a thing should be modified. It does rely on how the thing looked before the change or how it will look after the change. Delta describes only what was changed. See the Deltas page for more information about the generic concept.
Prism has classes to represent the deltas in a very convenient way. These classes represent the change to prism objects instead of the absolute value of the objects. But otherwise the deltas are similar to objects when it comes to the way how they are created and used: the deltas have reference to the prism context, deltas are serializable (and must be adopted after deserialization), deltas contain item definitions, etc.
There are two broad categories of prism deltas:
- Item delta describes change to prism items (properties, containers, references).
- Object delta describes how the entire object changed. It has OID. Depending on the delta type it may contain complete new prism object or collection of item deltas (see below).
Item delta contains change of a single item. The delta is described path of the item, modification types and the values. The following examples provide a symbolic description of several item deltas.
Following delta will replace all the values of property
fullName with a new value
Following delta will add new value
Pirate to property
Item deltas can add and delete values at the same time. Following delta will modify property
employeeType by adding new value
Captain and remove existing value
Deltas that go deeper into the object structure must have a
parentPath set appropriately. Follwing delta will change the value of property
administrativeStatus which resides in container
Item deltas can also modify references and even entire containers. (TODO: examples, better description).
There are several subclasses of ItemDelta class (which itself is abstract):
All the delta classes behave in very similar way. They all have factory methods for more convenient work with the deltas.
All the deltas contain definition of the item that they relate to. All the deltas also do not contain the real values directly. The real values are wrapped in prism values (subclasses of
Creating Property Delta
Following code creates a property delta of user property
fullName which will replace all existing values with a value
In this case the
createReplaceDelta factory method locates a definition of
fullName attribute in definition of
UserType object, it will create an empty delta initialized with property name, definition and empty
parentPath. It will also wrap provided PolyString value into a new PrismPropertyValue wrapper and place it into the new delta.
Object delta describes a change of entire object. It is represented by
ObjectDelta class. But even though there is just one class the internal content differs quite a lot depending on the change type. Following sections describe individual cases.
Object Delta: ADD
Add object delta creates a new object. The new object is specified inside the delta:
Add delta can be conveniently created by invokinf
createAddDelta factory method:
Object Delta: MODIFY
Modify object deltas modifies existing object. It contains a collection of item deltas:
Modify delta needs to explicitly specify object type (class, e.g.
UserType) and OID as these two parameters are used to locate existing object. Modify delta can also be conveniently created using a factory method such as
createModificationAddProperty. It can be later extended using mutator methods such as
Object Delta: DELETE
Delete object delta deletes existing object. It just needs OID and object type (class):
Factory method can also be used to construct this delta: