Package org.optaplanner.core.impl.score.director

## Interface InnerScoreDirector<Solution_,​Score_ extends Score<Score_>>

- Type Parameters:
    `Solution_` - the solution type, the class with the `PlanningSolution` annotation
    `Score_` - the score type to go with the solution
  All Superinterfaces:
    `AutoCloseable`, `ScoreDirector<Solution_>`
  All Known Implementing Classes:
    `AbstractScoreDirector`, `ConstraintStreamScoreDirector`, `DroolsScoreDirector`, `EasyScoreDirector`, `IncrementalScoreDirector`, `TestGenDroolsScoreDirector`

      public interface InnerScoreDirector<Solution_,​Score_ extends Score<Score_>>
      extends ScoreDirector<Solution_>, AutoCloseable

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `afterVariableChanged​(VariableDescriptor<Solution_> variableDescriptor, Object entity)` |
    `void` | `assertExpectedUndoMoveScore​(Move<Solution_> move, Score_ beforeMoveScore)` | Asserts that if the `Score` is calculated for the current `working solution` in the current `ScoreDirector` (with incremental calculation residue), it is equal to the parameter `beforeMoveScore`.
    `void` | `assertExpectedWorkingScore​(Score_ expectedWorkingScore, Object completedAction)` | Asserts that if the `Score` is calculated for the current `working solution` in the current `ScoreDirector` (with possibly incremental calculation residue), it is equal to the parameter `expectedWorkingScore`.
    `void` | `assertNonNullPlanningIds()` | Asserts that none of the planning facts from `SolutionDescriptor.getAllFacts(Object)` for `ScoreDirector.getWorkingSolution()` have `PlanningId`s with a null value.
    `void` | `assertPredictedScoreFromScratch​(Score_ predictedScore, Object completedAction)` | Asserts that if the `Score` is calculated for the current `working solution` in a fresh `ScoreDirector` (with no incremental calculation residue), it is equal to the parameter `predictedScore`.
    `void` | `assertShadowVariablesAreNotStale​(Score_ expectedWorkingScore, Object completedAction)` | Asserts that if all `VariableListener`s are forcibly triggered, and therefore all shadow variables are updated if needed, that none of the shadow variables of the `working solution` change, Then also asserts that the `Score` calculated for the `working solution` afterwards is equal to the parameter `expectedWorkingScore`.
    `void` | `assertWorkingScoreFromScratch​(Score_ workingScore, Object completedAction)` | Asserts that if the `Score` is calculated for the current `working solution` in a fresh `ScoreDirector` (with no incremental calculation residue), it is equal to the parameter `workingScore`.
    `void` | `beforeVariableChanged​(VariableDescriptor<Solution_> variableDescriptor, Object entity)` |
    `Score_` | `calculateScore()` | Calculates the `Score` and updates the `working solution` accordingly.
    `void` | `changeVariableFacade​(VariableDescriptor<Solution_> variableDescriptor, Object entity, Object newValue)` |
    `InnerScoreDirector<Solution_,​Score_>` | `clone()` | Clones this `ScoreDirector` and its `working solution`.
    `Solution_` | `cloneSolution​(Solution_ originalSolution)` | Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.
    `Solution_` | `cloneWorkingSolution()` | Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.
    `void` | `close()` | Needs to be called after use because some implementations need to clean up their resources.
    `InnerScoreDirector<Solution_,​Score_>` | `createChildThreadScoreDirector​(ChildThreadType childThreadType)` |
    `Score_` | `doAndProcessMove​(Move<Solution_> move, boolean assertMoveScoreFromScratch)` |
    `void` | `doAndProcessMove​(Move<Solution_> move, boolean assertMoveScoreFromScratch, Consumer<Score_> moveProcessor)` |
    `long` | `getCalculationCount()` |
    `Map<String,​ConstraintMatchTotal<Score_>>` | `getConstraintMatchTotalMap()` | Explains the `Score` of `calculateScore()` by splitting it up per `Constraint`.
    `Map<Object,​Indictment<Score_>>` | `getIndictmentMap()` | Explains the impact of each planning entity or problem fact on the `Score`.
    `ScoreDefinition<Score_>` | `getScoreDefinition()` |
    `InnerScoreDirectorFactory<Solution_,​Score_>` | `getScoreDirectorFactory()` |
    `SolutionDescriptor<Solution_>` | `getSolutionDescriptor()` |
    `SupplyManager<Solution_>` | `getSupplyManager()` |
    `int` | `getWorkingEntityCount()` |
    `List<Object>` | `getWorkingEntityList()` |
    `long` | `getWorkingEntityListRevision()` |
    `int` | `getWorkingValueCount()` |
    `boolean` | `isConstraintMatchEnabled()` |
    `boolean` | `isWorkingEntityListDirty​(long expectedWorkingEntityListRevision)` |
    `void` | `overwriteConstraintMatchEnabledPreference​(boolean constraintMatchEnabledPreference)` |
    `void` | `resetCalculationCount()` |
    `void` | `setAllChangesWillBeUndoneBeforeStepEnds​(boolean allChangesWillBeUndoneBeforeStepEnds)` | Do not waste performance by propagating changes to step (or higher) mechanisms.
    `void` | `setWorkingSolution​(Solution_ workingSolution)` | The `working solution` must never be the same instance as the `best solution`, it should be a (un)changed clone.

    - ### Methods inherited from interface org.optaplanner.core.api.score.director.ScoreDirector

      `afterEntityAdded, afterEntityRemoved, afterProblemFactAdded, afterProblemFactRemoved, afterProblemPropertyChanged, afterVariableChanged, beforeEntityAdded, beforeEntityRemoved, beforeProblemFactAdded, beforeProblemFactRemoved, beforeProblemPropertyChanged, beforeVariableChanged, getWorkingSolution, lookUpWorkingObject, lookUpWorkingObjectOrReturnNull, triggerVariableListeners`

- - ### Method Detail

    - #### setWorkingSolution

          void setWorkingSolution​(Solution_ workingSolution)

      The `working solution` must never be the same instance as the `best solution`, it should be a (un)changed clone.
      Parameters:
        `workingSolution` - never null

    - #### calculateScore

          Score_ calculateScore()

      Calculates the `Score` and updates the `working solution` accordingly.
      Returns:
        never null, the `Score` of the `working solution`

    - #### isConstraintMatchEnabled

          boolean isConstraintMatchEnabled()

      Returns:
        true if `getConstraintMatchTotalMap()` and `getIndictmentMap()` can be called

    - #### getConstraintMatchTotalMap

          Map<String,​ConstraintMatchTotal<Score_>> getConstraintMatchTotalMap()

      Explains the `Score` of `calculateScore()` by splitting it up per `Constraint`.

      The sum of `ConstraintMatchTotal.getScore()` equals `calculateScore()`.

      Call `calculateScore()` before calling this method, unless that method has already been called since the last `PlanningVariable` changes.

      Returns:
        never null, the key is the `constraintId` (to create one, use `ConstraintMatchTotal.composeConstraintId(String, String)`).
      Throws:
        `IllegalStateException` - if `isConstraintMatchEnabled()` returns false
      See Also:
        `getIndictmentMap()`

    - #### getIndictmentMap

          Map<Object,​Indictment<Score_>> getIndictmentMap()

      Explains the impact of each planning entity or problem fact on the `Score`. An `Indictment` is basically the inverse of a `ConstraintMatchTotal`: it is a `Score` total for each justification `Object` in `ConstraintMatch.getJustificationList()`.

      The sum of `ConstraintMatchTotal.getScore()` differs from `calculateScore()` because each `ConstraintMatch.getScore()` is counted for each justification in `ConstraintMatch.getJustificationList()`.

      Call `calculateScore()` before calling this method, unless that method has already been called since the last `PlanningVariable` changes.

      Returns:
        never null, the key is a `problem fact` or a `planning entity`
      Throws:
        `IllegalStateException` - if `isConstraintMatchEnabled()` returns false
      See Also:
        `getConstraintMatchTotalMap()`

    - #### overwriteConstraintMatchEnabledPreference

          void overwriteConstraintMatchEnabledPreference​(boolean constraintMatchEnabledPreference)

      Parameters:
        `constraintMatchEnabledPreference` - false if a `ScoreDirector` implementation should not do `ConstraintMatch` tracking even if it supports it.

    - #### getWorkingEntityListRevision

          long getWorkingEntityListRevision()

      Returns:
        used to check `isWorkingEntityListDirty(long)` later on

    - #### doAndProcessMove

          Score_ doAndProcessMove​(Move<Solution_> move,
                                  boolean assertMoveScoreFromScratch)

      Parameters:
        `move` - never null
        `assertMoveScoreFromScratch` - true will hurt performance
      Returns:
        never null

    - #### doAndProcessMove

          void doAndProcessMove​(Move<Solution_> move,
                                boolean assertMoveScoreFromScratch,
                                Consumer<Score_> moveProcessor)

      Parameters:
        `move` - never null
        `assertMoveScoreFromScratch` - true will hurt performance
        `moveProcessor` - never null, use this to store the score as well as call the acceptor and forager

    - #### isWorkingEntityListDirty

          boolean isWorkingEntityListDirty​(long expectedWorkingEntityListRevision)

      Parameters:
        `expectedWorkingEntityListRevision` - an
      Returns:
        true if the entityList might have a different set of instances now

    - #### getScoreDirectorFactory

          InnerScoreDirectorFactory<Solution_,​Score_> getScoreDirectorFactory()

      Returns:
        never null

    - #### getSolutionDescriptor

          SolutionDescriptor<Solution_> getSolutionDescriptor()

      Returns:
        never null

    - #### getScoreDefinition

          ScoreDefinition<Score_> getScoreDefinition()

      Returns:
        never null

    - #### cloneWorkingSolution

          Solution_ cloneWorkingSolution()

      Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.
      Returns:
        never null, planning clone

    - #### cloneSolution

          Solution_ cloneSolution​(Solution_ originalSolution)

      Returns a planning clone of the solution, which is not a shallow clone nor a deep clone nor a partition clone.
      Parameters:
        `originalSolution` - never null
      Returns:
        never null, planning clone

    - #### getWorkingEntityCount

          int getWorkingEntityCount()

      Returns:
        `>= 0`

    - #### getWorkingEntityList

          List<Object> getWorkingEntityList()

      Returns:
        never null: an empty list if there are none

    - #### getWorkingValueCount

          int getWorkingValueCount()

      Returns:
        `>= 0`

    - #### getCalculationCount

          long getCalculationCount()

      Returns:
        at least 0L

    - #### resetCalculationCount

          void resetCalculationCount()

    - #### getSupplyManager

          SupplyManager<Solution_> getSupplyManager()

      Returns:
        never null

    - #### clone

          InnerScoreDirector<Solution_,​Score_> clone()

      Clones this `ScoreDirector` and its `working solution`. Use `ScoreDirector.getWorkingSolution()` to retrieve the `working solution` of that clone.

      This is heavy method, because it usually breaks incremental score calculation. Use it sparingly. Therefore it's best to clone lazily by delaying the clone call as long as possible.

      Returns:
        never null

    - #### createChildThreadScoreDirector

          InnerScoreDirector<Solution_,​Score_> createChildThreadScoreDirector​(ChildThreadType childThreadType)

    - #### setAllChangesWillBeUndoneBeforeStepEnds

          void setAllChangesWillBeUndoneBeforeStepEnds​(boolean allChangesWillBeUndoneBeforeStepEnds)

      Do not waste performance by propagating changes to step (or higher) mechanisms.
      Parameters:
        `allChangesWillBeUndoneBeforeStepEnds` - true if all changes will be undone

    - #### assertExpectedWorkingScore

          void assertExpectedWorkingScore​(Score_ expectedWorkingScore,
                                          Object completedAction)

      Asserts that if the `Score` is calculated for the current `working solution` in the current `ScoreDirector` (with possibly incremental calculation residue), it is equal to the parameter `expectedWorkingScore`.

      Used to assert that skipping `calculateScore()` (when the score is otherwise determined) is correct.

      Parameters:
        `expectedWorkingScore` - never null
        `completedAction` - sometimes null, when assertion fails then the completedAction's `Object.toString()` is included in the exception message

    - #### assertShadowVariablesAreNotStale

          void assertShadowVariablesAreNotStale​(Score_ expectedWorkingScore,
                                                Object completedAction)

      Asserts that if all `VariableListener`s are forcibly triggered, and therefore all shadow variables are updated if needed, that none of the shadow variables of the `working solution` change, Then also asserts that the `Score` calculated for the `working solution` afterwards is equal to the parameter `expectedWorkingScore`.

      Used to assert that the shadow variables' state is consistent with the genuine variables' state.

      Parameters:
        `expectedWorkingScore` - never null
        `completedAction` - sometimes null, when assertion fails then the completedAction's `Object.toString()` is included in the exception message

    - #### assertWorkingScoreFromScratch

          void assertWorkingScoreFromScratch​(Score_ workingScore,
                                             Object completedAction)

      Asserts that if the `Score` is calculated for the current `working solution` in a fresh `ScoreDirector` (with no incremental calculation residue), it is equal to the parameter `workingScore`.

      Furthermore, if the assert fails, a score corruption analysis might be included in the exception message.

      Parameters:
        `workingScore` - never null
        `completedAction` - sometimes null, when assertion fails then the completedAction's `Object.toString()` is included in the exception message
      See Also:
        `InnerScoreDirectorFactory.assertScoreFromScratch(Solution_)`

    - #### assertPredictedScoreFromScratch

          void assertPredictedScoreFromScratch​(Score_ predictedScore,
                                               Object completedAction)

      Asserts that if the `Score` is calculated for the current `working solution` in a fresh `ScoreDirector` (with no incremental calculation residue), it is equal to the parameter `predictedScore`.

      Furthermore, if the assert fails, a score corruption analysis might be included in the exception message.

      Parameters:
        `predictedScore` - never null
        `completedAction` - sometimes null, when assertion fails then the completedAction's `Object.toString()` is included in the exception message
      See Also:
        `InnerScoreDirectorFactory.assertScoreFromScratch(Solution_)`

    - #### assertExpectedUndoMoveScore

          void assertExpectedUndoMoveScore​(Move<Solution_> move,
                                           Score_ beforeMoveScore)

      Asserts that if the `Score` is calculated for the current `working solution` in the current `ScoreDirector` (with incremental calculation residue), it is equal to the parameter `beforeMoveScore`.

      Furthermore, if the assert fails, a score corruption analysis might be included in the exception message.

      Parameters:
        `move` - never null
        `beforeMoveScore` - never null

    - #### assertNonNullPlanningIds

          void assertNonNullPlanningIds()

      Asserts that none of the planning facts from `SolutionDescriptor.getAllFacts(Object)` for `ScoreDirector.getWorkingSolution()` have `PlanningId`s with a null value.

    - #### close

          void close()

      Needs to be called after use because some implementations need to clean up their resources.
      Specified by:
        `close` in interface `AutoCloseable`

    - #### beforeVariableChanged

          void beforeVariableChanged​(VariableDescriptor<Solution_> variableDescriptor,
                                     Object entity)

    - #### afterVariableChanged

          void afterVariableChanged​(VariableDescriptor<Solution_> variableDescriptor,
                                    Object entity)

    - #### changeVariableFacade

          void changeVariableFacade​(VariableDescriptor<Solution_> variableDescriptor,
                                    Object entity,
                                    Object newValue)