Package org.optaplanner.core.api.domain.variable

## Interface VariableListener<Solution_,​Entity_>

- Type Parameters:
    `Solution_` - the solution type, the class with the `PlanningSolution` annotation
    `Entity_` -
  All Superinterfaces:
    `AutoCloseable`, `Closeable`
  All Known Subinterfaces:
    `CustomShadowVariable.NullVariableListener`, `SourcedVariableListener<Solution_,​Entity_>`
  All Known Implementing Classes:
    `AnchorVariableListener`, `CollectionInverseVariableListener`, `ExternalizedAnchorVariableSupply`, `ExternalizedCollectionInverseVariableSupply`, `ExternalizedSingletonInverseVariableSupply`, `SingletonInverseVariableListener`

      public interface VariableListener<Solution_,​Entity_>
      extends Closeable

  Changes shadow variables when a genuine planning 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 that implementations be kept stateless. If state must be implemented, implementations may need to override the default methods (`resetWorkingSolution(ScoreDirector)`, `close()`).

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `afterEntityAdded​(ScoreDirector<Solution_> scoreDirector, Entity_ entity)` |
    `void` | `afterEntityRemoved​(ScoreDirector<Solution_> scoreDirector, Entity_ entity)` |
    `void` | `afterVariableChanged​(ScoreDirector<Solution_> scoreDirector, Entity_ entity)` |
    `void` | `beforeEntityAdded​(ScoreDirector<Solution_> scoreDirector, Entity_ entity)` |
    `void` | `beforeEntityRemoved​(ScoreDirector<Solution_> scoreDirector, Entity_ entity)` |
    `void` | `beforeVariableChanged​(ScoreDirector<Solution_> scoreDirector, Entity_ entity)` |
    `default void` | `close()` | Called before this `VariableListener` is thrown away and not used anymore.
    `default boolean` | `requiresUniqueEntityEvents()` | When set to `true`, this has a slight performance loss in Planner.
    `default void` | `resetWorkingSolution​(ScoreDirector<Solution_> scoreDirector)` | Called when the entire working solution changes.

- - ### Method Detail

    - #### requiresUniqueEntityEvents

          default boolean requiresUniqueEntityEvents()

      When set to `true`, this has a slight performance loss in Planner. When set to `false`, it's often easier to make the listener implementation correct and fast.
      Returns:
        true to guarantee that each of the before/after methods will only be called once per entity instance per operation type (add, change or remove).

    - #### beforeEntityAdded

          void beforeEntityAdded​(ScoreDirector<Solution_> scoreDirector,
                                 Entity_ entity)

      Parameters:
        `scoreDirector` - never null
        `entity` - never null

    - #### afterEntityAdded

          void afterEntityAdded​(ScoreDirector<Solution_> scoreDirector,
                                Entity_ entity)

      Parameters:
        `scoreDirector` - never null
        `entity` - never null

    - #### beforeVariableChanged

          void beforeVariableChanged​(ScoreDirector<Solution_> scoreDirector,
                                     Entity_ entity)

      Parameters:
        `scoreDirector` - never null
        `entity` - never null

    - #### afterVariableChanged

          void afterVariableChanged​(ScoreDirector<Solution_> scoreDirector,
                                    Entity_ entity)

      Parameters:
        `scoreDirector` - never null
        `entity` - never null

    - #### beforeEntityRemoved

          void beforeEntityRemoved​(ScoreDirector<Solution_> scoreDirector,
                                   Entity_ entity)

      Parameters:
        `scoreDirector` - never null
        `entity` - never null

    - #### afterEntityRemoved

          void afterEntityRemoved​(ScoreDirector<Solution_> scoreDirector,
                                  Entity_ entity)

      Parameters:
        `scoreDirector` - never null
        `entity` - never null

    - #### resetWorkingSolution

          default void resetWorkingSolution​(ScoreDirector<Solution_> scoreDirector)

      Called when the entire working solution changes. In this event, the other before..()/after...() methods will not be called. At this point, implementations should clear state, if any.
      Parameters:
        `scoreDirector` - never null

    - #### close

          default void close()

      Called before this `VariableListener` is thrown away and not used anymore.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`