Package ai.timefold.solver.core.api.domain.variable

Interface ListVariableListener<Solution_,Entity_,Element_>

Type Parameters:
Solution_ - the solution type, the class with the PlanningSolution annotation
Entity_ - PlanningEntity on which the source variable is declared
Element_ - the type of elements of the source list variable
All Superinterfaces:
AbstractVariableListener<Solution_,Entity_>, AutoCloseable, Closeable
All Known Subinterfaces:
ListVariableStateSupply<Solution_>
All Known Implementing Classes:
ListVariableTracker
public interface ListVariableListener<Solution_,Entity_,Element_> extends AbstractVariableListener<Solution_,Entity_>
A listener sourced on a PlanningListVariable.

Changes shadow variables when a genuine source list variable changes.

Important: it must only change the shadow variable(s) for which it's configured! It should never change a genuine variable or a problem fact. It can change its shadow variable(s) on multiple entity instances (for example: an arrivalTime change affects all trailing entities too).

It is recommended to keep implementations stateless. If state must be implemented, implementations may need to override the default methods (AbstractVariableListener.resetWorkingSolution(ScoreDirector), AbstractVariableListener.close()).

  • Method Details

    • afterListVariableElementUnassigned

      void afterListVariableElementUnassigned(@NonNull ScoreDirector<Solution_> scoreDirector, @NonNull Element_ element)
      The listener must unset all shadow variables it is responsible for when an element is unassigned from the source list variable. For example, a Task's startTime shadow variable must be reset to null after a task is unassigned from Employee.tasks when the move that assigned it there is undone during Construction Heuristic phase.
      Parameters:
      scoreDirector - score director
      element - the unassigned element

    • beforeListVariableChanged

      void beforeListVariableChanged(@NonNull ScoreDirector<Solution_> scoreDirector, @NonNull Entity_ entity, int fromIndex, int toIndex)
      Tells the listener that some elements within the range starting at fromIndex (inclusive) and ending at toIndex (exclusive) will change. Be aware that the afterListVariableChanged(ai.timefold.solver.core.api.score.director.ScoreDirector<Solution_>, Entity_, int, int) call after the change is done often has a different fromIndex and toIndex because the number of elements in the list variable can change.

      The list variable change includes:

      • Changing position (index) of one or more elements.
      • Removing one or more elements from the list variable.
      • Adding one or more elements to the list variable.
      • Any mix of the above.

      The range has the following properties:

      1. fromIndex is greater than or equal to 0; toIndex is less than or equal to the list variable size.
      2. toIndex is greater than or equal to fromIndex.
      3. The range contains all elements that are going to be changed.
      4. The range may contain elements that are not going to be changed.
      5. The range may be empty (fromIndex equals toIndex) if none of the existing list variable elements are going to be changed.
      Parameters:
      scoreDirector - score director
      entity - entity with the changed list variable
      fromIndex - low endpoint (inclusive) of the changed range
      toIndex - high endpoint (exclusive) of the changed range

    • afterListVariableChanged

      void afterListVariableChanged(@NonNull ScoreDirector<Solution_> scoreDirector, @NonNull Entity_ entity, int fromIndex, int toIndex)
      Tells the listener that some elements within the range starting at fromIndex (inclusive) and ending at toIndex (exclusive) changed.

      The list variable change includes:

      • Changing position (index) of one or more elements.
      • Removing one or more elements from the list variable.
      • Adding one or more elements to the list variable.
      • Any mix of the above.

      The range has the following properties:

      1. fromIndex is greater than or equal to 0; toIndex is less than or equal to the list variable size.
      2. toIndex is greater than or equal to fromIndex.
      3. The range contains all elements that have changed.
      4. The range may contain elements that have not changed.
      5. The range may be empty (fromIndex equals toIndex) if none of the existing list variable elements have changed.
      Parameters:
      scoreDirector - score director
      entity - entity with the changed list variable
      fromIndex - low endpoint (inclusive) of the changed range
      toIndex - high endpoint (exclusive) of the changed range