OUTDATED
This page is out of data.
Please see https://docs.evolveum.com/midpoint/prism/deltas/ for current information.
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
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 Jack Sparrow
.
PropertyDelta: parentPath: name: fullName valuesToReplace: "Jack Sparrow" (as PolyString)
Following delta will add new value Pirate
to property employeeType
.
PropertyDelta: parentPath: name: employeeType valuesToAdd: "Pirate"
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 Landluber
.
PropertyDelta: parentPath: name: employeeType valuesToAdd: "Captain" valuesToDelete: "Landluber"
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 activation
.
PropertyDelta: parentPath: activation name: administrativeStatus valuesToReplace: DISABLED
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):
- PropertyDelta
- ReferenceDelta
- ContainerDelta
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 PrismValue
class).
Creating Property Delta
Following code creates a property delta of user property fullName
which will replace all existing values with a value Jack Sparrow
.
PrismObjectDefinition<UserType> userDefinition = prismContext.getSchemaRegistry().findObjectDefinitionByCompileTimeClass(UserType.class); PropertyDelta<PolyString> fullNameDelta = PropertyDelta.createReplaceDelta(userDefinition, UserType.F_FULL_NAME, new PolyString("Jack Sparrow"));
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.
TODO: more
Object 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:
ObjectDelta: changeType: ADD objectTypeClass: UserType objectToAdd: name: jack givenName: Jack familyName: Sparrow fullName: Jack Sparrow
Add delta can be conveniently created by invokinf createAddDelta
factory method:
PrismObject<UserType> newUser = .... // Construct or parse the object ObjectDelta<UserType> userDelta = ObjectDelta.createAddDelta(newUser);
Object Delta: MODIFY
Modify object deltas modifies existing object. It contains a collection of item deltas:
ObjectDelta: changeType: MODIFY oid: 2cd99790-47be-11e3-a71a-3c970e467874 objectTypeClass: UserType modifications: PropertyDelta: parentPath: name: employeeType valuesToAdd: "Pirate" PropertyDelta: parentPath: name: title valuesToReplace: "Bloody"
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 addModificationReplaceProperty
.
String oid = "2cd99790-47be-11e3-a71a-3c970e467874"; ObjectDelta<UserType> userDelta = ObjectDelta.createModificationAddProperty(UserType.class, oid, UserType.F_EMPLOYEE_TYPE, "Pirate"); userDelta.addModificationReplaceProperty(UserType.F_TITLE, "Bloody");
Object Delta: DELETE
Delete object delta deletes existing object. It just needs OID and object type (class):
ObjectDelta: changeType: DELETE oid: 2cd99790-47be-11e3-a71a-3c970e467874 objectTypeClass: UserType
Factory method can also be used to construct this delta:
String oid = "2cd99790-47be-11e3-a71a-3c970e467874"; ObjectDelta<UserType> userDelta = ObjectDelta.createDeleteDelta(UserType.class, oid, prismContext);
TODO
- diff