Optaplanner: trying to understand unwanted pattern rule in nurse rostering example

Question

I'm new to drools and java and I'm trying to understand how this rule from the nurse rostering example works, especially the first part about $pattern.

rule "unwantedPatternShiftType3DaysPattern"
    when
        $pattern : ShiftType3DaysPattern(
            $dayIndex0ShiftType : dayIndex0ShiftType,
            $dayIndex1ShiftType : dayIndex1ShiftType,
            $dayIndex2ShiftType : dayIndex2ShiftType
        )
        PatternContractLine(
            pattern == $pattern, $contract : contract
        )

        ShiftAssignment(
            shiftType == $dayIndex0ShiftType,
            contract == $contract,
            $employee : employee, $firstDayIndex : shiftDateDayIndex
        )
        ShiftAssignment(
            shiftType == $dayIndex1ShiftType,
            employee == $employee,
            shiftDateDayIndex == ($firstDayIndex + 1)
        )
        ShiftAssignment(
            shiftType == $dayIndex2ShiftType,
            employee == $employee,
            shiftDateDayIndex == ($firstDayIndex + 2)
        )
    then
        scoreHolder.addSoftConstraintMatch(kcontext, - $pattern.getWeight());
end

Specifically, how does drools know what value is in: dayIndex0ShiftType, dayIndex1ShiftType, dayIndex2ShiftType? It calls the ShiftType3DaysPattern class with these values, but how are these values determined?

In addition, when it makes this call:

ShiftType3DaysPattern (dayIndex0ShiftType, dayIndex1ShiftType, dayIndex2ShiftType)

which refers to the following:

@XStreamAlias("ShiftType3DaysPattern")
public class ShiftType3DaysPattern extends Pattern {

    private ShiftType dayIndex0ShiftType;
    private ShiftType dayIndex1ShiftType;
    private ShiftType dayIndex2ShiftType;

    public ShiftType getDayIndex0ShiftType() {
        return dayIndex0ShiftType;
    }

    public void setDayIndex0ShiftType(ShiftType dayIndex0ShiftType) {
        this.dayIndex0ShiftType = dayIndex0ShiftType;
    }

    public ShiftType getDayIndex1ShiftType() {
        return dayIndex1ShiftType;
    }

    public void setDayIndex1ShiftType(ShiftType dayIndex1ShiftType) {
        this.dayIndex1ShiftType = dayIndex1ShiftType;
    }

    public ShiftType getDayIndex2ShiftType() {
        return dayIndex2ShiftType;
    }

    public void setDayIndex2ShiftType(ShiftType dayIndex2ShiftType) {
        this.dayIndex2ShiftType = dayIndex2ShiftType;
    }

    @Override
    public String toString() {
        return "Work pattern: " + dayIndex0ShiftType + ", " + dayIndex1ShiftType + ", " + dayIndex2ShiftType;
    }

}

Is this shorthand for ShiftType3DaysPattern.getDayIndex0ShiftType, ShiftType3DaysPattern.getDayIndex1ShiftType, and ShiftType3DaysPattern.getDayIndex2ShiftType?

And if this is the case, how does ShiftType3DaysPattern know which pattern to return if there are more than one "3 day patterns" in the xml source files? What am I missing?

Furthermore, if there are more than one "3 day pattern" then, how does drool automatically apply this rule to all of these "3 day patterns"?

Answer 1

Specifically, how does drools know what value is in: dayIndex0ShiftType, dayIndex1ShiftType, dayIndex2ShiftType? It calls the ShiftType3DaysPattern class with these values, but how are these values determined?

Every ShiftType3DaysPattern in your problem fact collection will be evaluated against this rule in combination with the other conditions in the when clause. So every combination of a ShiftType3DaysPattern, PatternContractLine, and three ShiftAssignments available as problem fact in the Kie session will be evaluated. If all the conditions match (so the PatternContractLine matches the ShiftType3DayPattern and all three ShiftAssignment types are assigned in the order of the unwanted ShiftType3DayPattern, the rule will be fired and the score will be impacted negatively. So the value of dayIndex0ShiftType, dayIndex1ShiftType and dayIndex2ShiftType will be whatever is set in the ShiftType3DaysPattern in the problem fact collection.

Is this shorthand for ShiftType3DaysPattern.getDayIndex0ShiftType, ShiftType3DaysPattern.getDayIndex1ShiftType, and ShiftType3DaysPattern.getDayIndex2ShiftType?

I'm not sure what you are referring to exactly, but if you are referring to this:

$pattern : ShiftType3DaysPattern(
    $dayIndex0ShiftType : dayIndex0ShiftType,
    $dayIndex1ShiftType : dayIndex1ShiftType,
    $dayIndex2ShiftType : dayIndex2ShiftType
)

This is just syntax for assigning dayIndex0ShiftType to the variable $dayIndex0ShiftType so it can be referred to in the rule later. The pattern itself is also assigned to a variable $pattern. The dollar sign itself is just a convention.

And if this is the case, how does ShiftType3DaysPattern know which pattern to return if there are more than one "3 day patterns" in the xml source files? What am I missing?

Furthermore, if there are more than one "3 day pattern" then, how does drool automatically apply this rule to all of these "3 day patterns"?

As I said before, the rule will be evaluated for every problem fact combination available, so every ShiftType3DaysPattern will be evaluated against the other facts stated in the when clause of the rule.

I recommend you to read the Drools documentation, it will help you to improve your basic understanding of Drools. It is a long read, but will be worth it. At least read the User guide chapter.