Meaning of beforeVariableChanged?

[holgerbrandl]

Dear Timefold Team,

We are working on a chained solver implementation using constraint provider API including multiple shadow variables which we update in one VariableListener. The solver seems to work fine unless FullAssert is being used.

With FullAssert enabled, we encounter errors like the following:

java.lang.IllegalStateException: VariableListener corruption after completedAction (Undo(entityB::NOROOT {null -> entityA::root1})):
The entity (entityA::root1)'s shadow variable (shadow1)'s corrupted value (...) changed to uncorrupted value (...)
after all variable listeners were triggered without changes to the genuine variables.

After researching this issue we think the problem lies in our miconception of the methods beforeVariableChanged and afterVariableChanged in
org.optaplanner.core.api.domain.variable.VariableListener<Solution_, Entity_> and that is why we ask you what is the purpose/intent
of these methods, especially beforeVariableChanged throws us of. Also, after thorough study of the manual, we could not find sufficient information to solve our issue.

Could you provide more information or examples regarding the contract of beforeVariableChanged and afterVariableChanged in the context of chained models?

[triceo]

There is a singular reason for why both of these exist - to properly update the internal state of incremental calculation. For this, we need to:

1. Be able to undo any previously computed incremental calculations using the current state of the variable. We do not, however, cache the state and we rely on the entity to have that state when we read it. That's what beforeVariableChanged(...) is for - to allow us to read the state pre-change.
2. Run those calculations again, using the new state. That's what afterVariableChanged(...) is for - it tells us that the variable now carries the new state and we can read it.

So, the correct order of operations from the user's point of view is:

beforeVariableChanged(entity, "variable");
entity.variable = "new value";
afterVariableChanged(entity, "variable");

If you modify the state of entity.variable anywhere else than between these two calls, corruptions are likely.

Writing complex variable listeners is hard, and it shouldn't be. (We're toying with some ideas to make it easier, but no promises.) Corruptions are not unheard of. I can only recommend minimizing the problem and identifying a singular problematic listener interaction, at which point a solution to the issue usually becomes clear.