Item delta
Last modified 27 Oct 2021 12:21 +02:00

Item delta specifies how a given item - property, reference, container - is (to be) modified.[1]

For an overview, please see the Deltas page.

Item delta content

Just to summarize, an item delta consists of three sets of values:

  1. values/yields to add (add set),

  2. values/yields to delete (delete set),

  3. values to replace (replace set).[2]

Any given item delta is either of "add/delete" type or of "replace" type. It is not possible to specify add and/or delete and replace sets at the same time.

Item delta application

Let us describe the application of an item delta on given prism item. There are two cases:

  1. Application of "add/delete" deltas.

  2. Application of "replace" deltas.

For the specification below, let:

  • D = ( Da, Dd, Dr ) be the delta,

    • Da, Dd, Dr being add, delete, and replace sets, respectively,

  • I be the set of item values before D application,

  • I' be the set of values after D application.

(And if needed, please see also the notation.)

Application of "replace" deltas

A "replace" delta is applied by clearing item values and replacing them with the values in delta replace set.

I' = Dr

Application of "add/delete" deltas

The application is a two-step process:

  1. Existing item values or yields matching the delta delete set are deleted.

  2. Values or yields from add set are added.

Mathematical description is divided into two parts:

  1. Model without metadata

  2. Model with metadata

Model without metadata

In fact, Dd does not contain values to be deleted but "deletion patterns" instead. Each value in I is compared with Dd and deleted if it matches any value there. This can be written as I -del/RVDI Dd.

Also, when adding values that have equivalents already present in I, we first remove those equivalents. (Effectively, it is a kind of "add-or-update" operation.) Let’s denote equivalents existing in I as Ir = I ∩RVDI Da.

So:

  • I' = (I -del/RVDI Dd - Ir) ∪ Da

  • i.e. I' = (I -del/RVDI Dd - (I ∩RVDI Da)) ∪ Da

Note that this is a slight difference introduced in midPoint 4.2. Before 4.2 we simply ignored values from Da that were present in I (under RVDI), i.e. the old behavior was:

I' = (I -del/RVDI Dd) ∪ (Da -RVDI I)

Finally, as a special rule: If we are adding a single value va to a single-valued item I = {vi}, and va is different from vi (va ≁RVDI vi) then we consider I to be ∅ i.e. we "clear" the item before applying the delta. Then:

I' = Da

Model with metadata

Short description of Dd treatment:

  1. If vd∈Dd has no metadata, simply remove vd from I. This is to ensure backward compatibility.

  2. If vd∈Dd has metadata, find an equivalent value vi∼vd and remove these metadata from vi. (And remove vi if no metadata values remain.)

Short description of Da treatment:

  1. If va ∉RVDI I, add va to I.

  2. If va ∈RVDI I, find an equivalent value vi∼vd, and add yields from va to vi.

Exact description:

It is not feasible to provide a specification of delta application using set operations. Let us resort to a pseudocode instead.

Let:

  • I be the item before application of specific va ∈ Da or vd ∈ Dd.

  • I' be the result of the application.

  • M(v) be the set of metadata values for prism value v.

  • m1 ∼P m2 mean that metadata value m1 and m2 have equivalent provenance.

Then:

For each vd ∈ Dd:

  1. If M(vd)=∅: The standard deletion is performed: I' = I -del/RVDI {vd}.

  2. If M(vd)={ md1, …​, mdnd } (nd>0), we try to find vi∈I: vi ∼RVDI vd and then:

    1. if vi does not exist, ignore vd (phantom delete)

    2. if vi exists and M(vi)={ mi1, mi2, …​, mini }, then:

      1. ∀mdx∈M(vd): delete all mik ∼P mdx from M(vi),

      2. if M(vi)=∅ after this operation, delete vi from I, i.e. I' = I - {vi}.

    3. any other vj ∼RVDI vd are ignored (we assume that they do not exist).

(See Item.removeRespectingMetadata method.)

For each va ∈ Da:

  1. If M(va)=∅: The standard addition is performed: I' = (I - Ir) ∪ {va} where

    1. Ir = { vi ∈ I | vi ∼RVDI va)

  2. If M(va)={ ma1, …​, mana} (na>0), we try to find vi∈I: vi ∼RVDI va and then:

    1. if vi does not exist, add va to I: i.e. I' = I ∪ {va} (standard addition),

    2. if vi exists and M(vi)={ mi1, mi2, …​, mini }, then:

      1. delete all conflicting-provenance metadata from vi, i.e. ∀max∈M(va) delete all mik ∼P max from M(vi),

      2. add all M(va) to M(vi).

    3. any other vj ∼RVDI va are ignored (we assume that they do not exist).

(See Item.addRespectingMetadataAndCloning method.)

1. A prism object, as it is an item as well, could be also described by item delta. But it makes little sense because objects are inherently single-valued items.
2. In theory, add and delete sets are sufficient to describe an item change. The replace set is a convenient way how to tell "clear everything and replace by me", without having to deal with existing values. This also means that it is a big difference between null replace set (meaning replace is not being applied) and empty replace set (meaning "delete everything").
Was this page helpful?
YES NO
Thanks for your feedback