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