Page tree
Skip to end of metadata
Go to start of metadata

For advanced users only. Information on this page are relevant mainly if you write your own scripting hook or otherwise modify behavior of midPoint at quite a low level of abstraction.

Fragile. This is not yet official / stable API. Please use with care.

MidPoint 4.2 and later

Primary, synchronization, and secondary deltas

With a little bit of simplification, we can say that any model operation starts with the intention either to execute a client-specified change (called primary delta) or to accommodate a change on resource (called sync delta).  During the operation, a component called Clockwork is run. It orchestrates a process of computing changes of focus and projections and executing them afterwards. Computation of changes is done by component called the Projector. This page describes basic ideas of representing these changes (called secondary deltas) during the computation.

Representation of the deltas

Deltas are stored in a structure that is central to the model operation: the Model Context.

The model context contains information on the focal object and its projections, along with the deltas. Specifically, ModelContext object wraps both focusContext and a collection of projectionContexts. Each of these contains the following features (see ModelElementContext and ModelProjectionContext interfaces):

FeatureMeaning
objectOld

"Old" state of the object i.e. the one that was present when the clockwork started. It can be present on the beginning or filled-in during projector execution by the context loaded.

objectCurrent

"Current" state of the object i.e. the one that was present when the current clockwork click started. It is typically filled-in by the context loader. For projections, it is usually the same as the "old" state, as they are not updated iteratively but only once per clockwork run.

objectNew

Expected state of the object after application of currentDelta i.e. item deltas computed during current projection: objectCurrentcurrentDelta = objectNew.

primaryDeltaPrimary delta i.e. one that the caller specified that has to be executed.
syncDelta

Synchronization delta i.e. changes that have recently happened. MidPoint reacts to these changes by "pulling them in" (e.g. using them in inbound mappings).

secondaryDeltaSecondary delta i.e. deltas computed for execution relevant for the current clockwork click (Projector run).
currentDelta

Object delta valid for the current clockwork click. It is either primary delta merged with the current secondary delta (if primary delta was not applied yet), or simply current secondary delta.

summaryDeltaObject delta comprising both primary delta and (all) secondary deltas, merged together. For projections, it is the same as currentDelta.
summarySecondaryDelta Summarization of all secondary deltas. For projections, it is the same as secondaryDelta. This is useful e.g. for "preview changes" functionality.
objectDeltaObjectAbsolute Only for focus context: the object-delta-object structure comprising all the computation, i.e. objectOld + summaryDelta = objectNew.
objectDeltaObjectRelative Only for focus context: the object-delta-object structure relative to the current wave, i.e. objectCurrent + currentDelta = objectNew.
objectDeltaObjectOnly for projection contexts: returns object-delta-object structure comprised of objectCurrent + currentDelta = objectNew. But because projection is computed only in a single wave, it is basically the same as "objectOld + summaryDelta = objectNew". That's why we do not distinguish between "absolute" and "relative" object-delta-object for projections.

Differences from midPoint 4.1 and before

The original features of ModelElementContext  and ModelProjectionContext interfaces were like this. Only changed items are shown.

FeatureMeaningMigration to 4.2
secondaryDeltaFor focus, this was a union of all secondary deltas computed. For projection, it was the secondary delta for the current clockwork click. (Each projection is dealt with in only a single click.)Replaced by summarySecondaryDelta.
deltaUnion of primaryDelta and secondaryDelta (i.e. all the secondary deltas).Replaced by summaryDelta.
secondaryDelta (int wave) / waveSecondaryDelta (int wave)Only for focus context: the secondary delta for a specific projection wave (approximately meaning clockwork click).Not directly available any more. Can be obtained by browsing through secondaryDeltas structure - see ObjectDeltaWaves class description below.
secondaryDeltas Only for focus context: secondary deltas indexed by projection wave.Available but with changed semantics, see below.
allDeltas Only for focus context: a list of all deltas (primary, secondary).Not directly available any more.
projectionWaveSecondaryDelta Only for focus context: secondary delta for the current projection wave.Replaced by secondaryDelta.
objectDeltaObjectFor focus context: objectOld + delta = objectNew. For projection context: objectCurrent + delta = objectNew.Replaced by objectDeltaObjectAbsolute for focus and kept unchanged for projections.

ObjectDeltaWaves class

Originally this class contained all secondary deltas, indexed by projection wave number. Starting from 4.2 this structure contains only archived secondary deltas, i.e. those that were already applied. And it is no longer indexed by wave number, but contains wave number information inside. It is because a repeated (restarted) projection wave can produce more secondary deltas.

Modifying the deltas

If you need to modify the deltas (e.g. from scripting hook) there are the following methods available:

MethodDescription
swallowToSecondaryDeltaAdds the specified item delta or item deltas into current secondary delta.
swallowToPrimaryDelta Adds the specified item delta into the primary delta. This may look strange but there are situations when you want to manipulate the primary delta in a hook (e.g. by adding or removing an assignment), so that the change is correctly reflected in secondary deltas.

Differences from midPoint 4.1 and before

Before 4.2, there were more methods to modify the deltas. (Now showing all the methods, not only changed ones.)

MethodDescriptionMigration to 4.2
swallowToProjectionWaveSecondaryDeltaOnly for focus context: adds item delta to the current secondary delta.Replaced by swallowToSecondaryDelta.
swallowToSecondaryDeltaFor focus context: the same as swallowToProjectionWaveSecondaryDelta. For projection context: adds item delta to the current secondary delta.Stays the same.
swallowToPrimaryDelta The same as in 4.2Stays the same.
swallowToWave0SecondaryDeltaOnly for focus context: adds delta to the wave 0 secondary delta. Not entirely clean solution, as it can create inconsistencies when executing in waves greater than 0.Replaced by swallowToSecondaryDelta for compatibility reasons, with a little bit different semantics.
  • No labels