Must an InverseRelationShadowVariable necessarily belong to a planningEntity?

Question

I have been trying to implement a shadow variable so that one of my problem facts can keep track of which planning entity is relevant to it, the end goal being to simplify/speed up my rules.

I am looking at the optaplanner doc about shadow variables, particularly the cloudBalancing example. In the "normal" cloudBalancing, the class CloudComputer is not a planningEntity. But in the example below, it is annotated as a planningEntity.

Are we to understand that the class "hosting" the shadow variable should be a planning entity? I thought a planningEntity had to have a planningVariable, but CloudComputer does not. If the answer is yes, I suggest being more explicit about it in the documentation. If the answer is no, then there is a mistake in this example (the @PlanningEntity annotation should be removed from CloudComputer).

The following example is from the doc:

For a non-chained planning variable, the bi-directional relationship must be a many to one relationship. To map a bi-directional relationship between two planning variables, annotate the master side (which is the genuine side) as a normal planning variable:

@PlanningEntity
public class CloudProcess {

    @PlanningVariable(...)
    public CloudComputer getComputer() {
        return computer;
    }
    public void setComputer(CloudComputer computer) {...}

}

And:

@PlanningEntity
public class CloudComputer {

    @InverseRelationShadowVariable(sourceVariableName = "computer")
    public List<CloudProcess> getProcessList() {
        return processList;
    }

}

Also, is this really all that is needed so that processList is kept up to date even when CloudProcess is cloned during solving?

Answer 1

There are 2 kinds of planning variables: genuine (@PlanningVariable) and shadow variables. Any class that has either or combination thereof needs to be annotated as a @PlanningEntity (and added to the solver config unless you're using scanAnnotatedClasses).

Yes, this is because of the planning cloning. With the shadow variable, CloudComputer doesn't change during the planning so it doesn't need to be planning cloned. With the shadow variable, it changes during planning, so it needs to be cloned. If it wouldn't be planning cloned, the best solution would get corrupted when the internal working solution changes. That in turn would affect score calculation (if it uses the inverse list) and any consumer of best solution events or the best solution result returned by solve().