Package ai.timefold.solver.core.impl.score.director

Class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_,Factory_>>

java.lang.Object

ai.timefold.solver.core.impl.score.director.AbstractScoreDirector<Solution_,Score_,Factory_>

All Implemented Interfaces:

ScoreDirector<Solution_>, InnerScoreDirector<Solution_,Score_>, VariableDescriptorAwareScoreDirector<Solution_>, AutoCloseable, Cloneable

Direct Known Subclasses:

BavetConstraintStreamScoreDirector, EasyScoreDirector, IncrementalScoreDirector

public abstract class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_,Factory_>>
extends Object
implements InnerScoreDirector<Solution_,Score_>, Cloneable

Abstract superclass for ScoreDirector.

Implementation note: Extending classes should follow these guidelines:

• InnerScoreDirector.setWorkingSolution(Object) should delegate to setWorkingSolution(Object, Consumer)
• before* method: last statement should be a call to the super method
• after* method: first statement should be a call to the super method

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	AbstractScoreDirector.AbstractScoreDirectorBuilder<Solution_,Score_ extends Score<Score_>,Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_,Factory_>,Builder_ extends AbstractScoreDirector.AbstractScoreDirectorBuilder<Solution_,Score_,Factory_,Builder_>>	An abstract builder for creating instances of InnerScoreDirector.

Field Summary

Fields

Modifier and Type	Field	Description
protected final ConstraintMatchPolicy	constraintMatchPolicy
protected final org.slf4j.Logger	logger
protected final Factory_	scoreDirectorFactory
protected final VariableListenerSupport<Solution_>	variableListenerSupport
protected Solution_	workingSolution

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractScoreDirector(Factory_ scoreDirectorFactory, boolean lookUpEnabled, ConstraintMatchPolicy constraintMatchPolicy, boolean expectShadowVariablesInCorrectState)

Method Summary

Modifier and Type	Method	Description
void	afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	afterListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor, Object entity, int fromIndex, int toIndex)	Notify the score director after a list variable changes.
void	afterListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that was assigned (added to a list variable of one entity without being removed from a list variable of another entity).
void	afterListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that was unassigned (removed from a list variable of one entity without being added to a list variable of another entity).
void	afterProblemFactAdded(Object problemFact)
void	afterProblemFactRemoved(Object problemFact)
void	afterProblemPropertyChanged(Object problemFactOrEntity)
void	afterVariableChanged(VariableDescriptor<Solution_> variableDescriptor, Object entity)
void	assertExpectedUndoMoveScore(Move<Solution_> move, InnerScore<Score_> beforeMoveInnerScore, SolverLifecyclePoint executionPoint)	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(InnerScore<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	assertPredictedScoreFromScratch(InnerScore<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 predictedScore.
void	assertShadowVariablesAreNotStale(InnerScore<Score_> expectedWorkingScore, Object completedAction)	Asserts that if all VariableListeners 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(InnerScore<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	beforeEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	beforeEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	beforeListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor, Object entity, int fromIndex, int toIndex)	Notify the score director before a list variable changes.
void	beforeListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that will be assigned (added to a list variable of one entity without being removed from a list variable of another entity).
void	beforeListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor, Object element)	Call this for each element that will be unassigned (removed from a list variable of one entity without being added to a list variable of another entity).
void	beforeProblemFactAdded(Object problemFact)
void	beforeProblemFactRemoved(Object problemFact)
void	beforeProblemPropertyChanged(Object problemFactOrEntity)
void	beforeVariableChanged(VariableDescriptor<Solution_> variableDescriptor, Object entity)
protected String	buildScoreCorruptionAnalysis(InnerScoreDirector<Solution_,Score_> uncorruptedScoreDirector, boolean predicted)
protected String	buildShadowVariableAnalysis(boolean predicted)
protected void	clearVariableListenerEvents()	This function clears all listener events that have been generated without triggering any of them.
AbstractScoreDirector<Solution_,Score_,Factory_>	clone()	Deprecated, for removal: This API element is subject to removal in a future version. Unused, but kept for backward compatibility.
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.
void	close()	Needs to be called after use because some implementations need to clean up their resources.
InnerScoreDirector<Solution_,Score_>	createChildThreadScoreDirector(ChildThreadType childThreadType)
void	executeMove(Move<Solution_> move)
InnerScore<Score_>	executeTemporaryMove(Move<Solution_> move, boolean assertMoveScoreFromScratch)	Executes a move, finds out its score, and immediately undoes it.
boolean	expectShadowVariablesInCorrectState()	Inverse shadow variables have a fail-fast for cases where the shadow variable doesn't actually point to its correct inverse.
void	forceTriggerVariableListeners()	Unlike ScoreDirector.triggerVariableListeners() which only triggers notifications already in the queue, this triggers every variable listener on every genuine variable.
long	getCalculationCount()
final ConstraintMatchPolicy	getConstraintMatchPolicy()
ListVariableStateSupply<Solution_>	getListVariableStateSupply(ListVariableDescriptor<Solution_> variableDescriptor)
MoveDirector<Solution_,Score_>	getMoveDirector()
ScoreDefinition<Score_>	getScoreDefinition()
Factory_	getScoreDirectorFactory()
SolutionTracker.SolutionCorruptionResult	getSolutionCorruptionAfterUndo(Move<Solution_> move, InnerScore<Score_> undoInnerScore)
SolutionDescriptor<Solution_>	getSolutionDescriptor()
SupplyManager	getSupplyManager()
VariableDescriptorCache<Solution_>	getVariableDescriptorCache()
long	getWorkingEntityListRevision()
int	getWorkingGenuineEntityCount()
int	getWorkingInitScore()
@NonNull Solution_	getWorkingSolution()	The PlanningSolution that is used to calculate the Score.
void	incrementCalculationCount()
protected boolean	isConstraintConfiguration(Object problemFactOrEntity)
boolean	isWorkingEntityListDirty(long expectedWorkingEntityListRevision)
boolean	isWorkingSolutionInitialized()
<E> @Nullable E	lookUpWorkingObject(@Nullable E externalObject)	Translates an entity or fact instance (often from another Thread or JVM) to this ScoreDirector's internal working instance.
<E> @Nullable E	lookUpWorkingObjectOrReturnNull(@Nullable E externalObject)	As defined by ScoreDirector.lookUpWorkingObject(Object), but doesn't fail fast if no workingObject was ever added for the externalObject.
void	resetCalculationCount()
void	setAllChangesWillBeUndoneBeforeStepEnds(boolean allChangesWillBeUndoneBeforeStepEnds)	Do not waste performance by propagating changes to step (or higher) mechanisms.
protected void	setCalculatedScore(Score_ score)
void	setMoveRepository(@Nullable MoveRepository<Solution_> moveRepository)	Different phases may need different move repositories, as they may be based on different sets of moves.
protected void	setWorkingEntityListDirty()
protected void	setWorkingSolution(Solution_ workingSolution, Consumer<Object> entityAndFactVisitor)	Note: resetting the working solution does NOT substitute the calls to before/after methods of the ProblemChangeDirector during problem changes, as these calls are propagated to variable listeners, which update shadow variables in the working solution to keep it consistent.
String	toString()
void	triggerVariableListeners()

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ai.timefold.solver.core.impl.score.director.InnerScoreDirector

afterEntityAdded, afterEntityRemoved, beforeEntityAdded, beforeEntityRemoved, buildScoreAnalysis, calculateScore, cloneWorkingSolution, getConstraintMatchTotalMap, getIndictmentMap, isDerived, requiresFlushing, setWorkingSolution

Methods inherited from interface ai.timefold.solver.core.impl.score.director.VariableDescriptorAwareScoreDirector

afterListVariableChanged, afterListVariableElementAssigned, afterListVariableElementUnassigned, afterVariableChanged, beforeListVariableChanged, beforeListVariableElementAssigned, beforeListVariableElementUnassigned, beforeVariableChanged, changeVariableFacade

Field Details

logger

protected final org.slf4j.Logger logger

constraintMatchPolicy

protected final ConstraintMatchPolicy constraintMatchPolicy

scoreDirectorFactory

protected final Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_,Factory_> scoreDirectorFactory

variableListenerSupport

protected final VariableListenerSupport<Solution_> variableListenerSupport

workingSolution

protected Solution_ workingSolution

Constructor Details

AbstractScoreDirector

protected AbstractScoreDirector(Factory_ scoreDirectorFactory,
 boolean lookUpEnabled,
 ConstraintMatchPolicy constraintMatchPolicy,
 boolean expectShadowVariablesInCorrectState)

Method Details

getConstraintMatchPolicy

public final ConstraintMatchPolicy getConstraintMatchPolicy()

Specified by:

getConstraintMatchPolicy in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

ConstraintMatchPolicy.ENABLED if InnerScoreDirector.getConstraintMatchTotalMap() and InnerScoreDirector.getIndictmentMap() can be called. ConstraintMatchPolicy.ENABLED_WITHOUT_JUSTIFICATIONS if only the former can be called. ConstraintMatchPolicy.DISABLED if neither can be called.

getScoreDirectorFactory

public Factory_ getScoreDirectorFactory()

Specified by:

getScoreDirectorFactory in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

never null

getSolutionDescriptor

public SolutionDescriptor<Solution_> getSolutionDescriptor()

Specified by:

getSolutionDescriptor in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

getSolutionDescriptor in interface VariableDescriptorAwareScoreDirector<Solution_>

Returns:

never null

getScoreDefinition

public ScoreDefinition<Score_> getScoreDefinition()

Specified by:

getScoreDefinition in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

never null

getVariableDescriptorCache

public VariableDescriptorCache<Solution_> getVariableDescriptorCache()

Specified by:

getVariableDescriptorCache in interface VariableDescriptorAwareScoreDirector<Solution_>

getListVariableStateSupply

public ListVariableStateSupply<Solution_> getListVariableStateSupply(ListVariableDescriptor<Solution_> variableDescriptor)

Specified by:

getListVariableStateSupply in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

expectShadowVariablesInCorrectState

public boolean expectShadowVariablesInCorrectState()

Description copied from interface: InnerScoreDirector

Inverse shadow variables have a fail-fast for cases where the shadow variable doesn't actually point to its correct inverse. This is very useful to pinpoint improperly initialized solutions.

However, SolutionManager.update(Object) exists precisely for the purpose of initializing solutions. And when this API is used, the fail-fast must not be triggered as it is guaranteed and expected that the inverse relationships will be wrong. In fact, they will be null.

For this case and this case only, this method is allowed to return false. All other cases must return true, otherwise a very valuable fail-fast is lost.

Specified by:

expectShadowVariablesInCorrectState in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

false if the fail-fast on shadow variables should not be triggered

getWorkingSolution

public @NonNull Solution_ getWorkingSolution()

Description copied from interface: ScoreDirector

The PlanningSolution that is used to calculate the Score.

Because a Score is best calculated incrementally (by deltas), the ScoreDirector needs to be notified when its working solution changes.

Specified by:

getWorkingSolution in interface ScoreDirector<Solution_>

getWorkingInitScore

public int getWorkingInitScore()

Specified by:

getWorkingInitScore in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

getWorkingEntityListRevision

public long getWorkingEntityListRevision()

Specified by:

getWorkingEntityListRevision in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

used to check InnerScoreDirector.isWorkingEntityListDirty(long) later on

getWorkingGenuineEntityCount

public int getWorkingGenuineEntityCount()

Specified by:

getWorkingGenuineEntityCount in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

setAllChangesWillBeUndoneBeforeStepEnds

public void setAllChangesWillBeUndoneBeforeStepEnds(boolean allChangesWillBeUndoneBeforeStepEnds)

Description copied from interface: InnerScoreDirector

Do not waste performance by propagating changes to step (or higher) mechanisms.

Specified by:

setAllChangesWillBeUndoneBeforeStepEnds in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

allChangesWillBeUndoneBeforeStepEnds - true if all changes will be undone

getCalculationCount

public long getCalculationCount()

Specified by:

getCalculationCount in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

at least 0L

resetCalculationCount

public void resetCalculationCount()

Specified by:

resetCalculationCount in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

incrementCalculationCount

public void incrementCalculationCount()

Specified by:

incrementCalculationCount in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

getSupplyManager

public SupplyManager getSupplyManager()

Specified by:

getSupplyManager in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Returns:

never null

getMoveDirector

public MoveDirector<Solution_,Score_> getMoveDirector()

Specified by:

getMoveDirector in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

setWorkingSolution

protected void setWorkingSolution(Solution_ workingSolution,
 Consumer<Object> entityAndFactVisitor)

Note: resetting the working solution does NOT substitute the calls to before/after methods of the ProblemChangeDirector during problem changes, as these calls are propagated to variable listeners, which update shadow variables in the working solution to keep it consistent.

Parameters:

workingSolution - the working solution to set

entityAndFactVisitor - maybe null; a function to apply to all problem facts and problem entities

setMoveRepository

public void setMoveRepository(@Nullable MoveRepository<Solution_> moveRepository)

Description copied from interface: InnerScoreDirector

Different phases may need different move repositories, as they may be based on different sets of moves. Therefore move repository cannot be injected at score director construction time. A phase may not need a move repository at all, such as construction heuristics, which currently does not support Move Streams. Each phase is responsible for calling this method to set its repository, and also calling it again at the end to null it out.

Specified by:

setMoveRepository in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

executeMove

public void executeMove(Move<Solution_> move)

Specified by:

executeMove in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

executeTemporaryMove

public InnerScore<Score_> executeTemporaryMove(Move<Solution_> move,
 boolean assertMoveScoreFromScratch)

Description copied from interface: InnerScoreDirector

Executes a move, finds out its score, and immediately undoes it.

Specified by:

executeTemporaryMove in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

move - never null

assertMoveScoreFromScratch - true will hurt performance

Returns:

never null

isWorkingEntityListDirty

public boolean isWorkingEntityListDirty(long expectedWorkingEntityListRevision)

Specified by:

isWorkingEntityListDirty in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

expectedWorkingEntityListRevision - an

Returns:

true if the entityList might have a different set of instances now

isWorkingSolutionInitialized

public boolean isWorkingSolutionInitialized()

Specified by:

isWorkingSolutionInitialized in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

setWorkingEntityListDirty

protected void setWorkingEntityListDirty()

cloneSolution

public Solution_ cloneSolution(Solution_ originalSolution)

Description copied from interface: InnerScoreDirector

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

Specified by:

cloneSolution in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

originalSolution - never null

Returns:

never null, planning clone

triggerVariableListeners

public void triggerVariableListeners()

Specified by:

triggerVariableListeners in interface ScoreDirector<Solution_>

clearVariableListenerEvents

protected void clearVariableListenerEvents()

This function clears all listener events that have been generated without triggering any of them. Using this method requires caution because clearing the event queue can lead to inconsistent states. This occurs when the shadow variables are not updated, causing constraints reliant on these variables to be inaccurately evaluated.

forceTriggerVariableListeners

public void forceTriggerVariableListeners()

Description copied from interface: InnerScoreDirector

Unlike ScoreDirector.triggerVariableListeners() which only triggers notifications already in the queue, this triggers every variable listener on every genuine variable. This is useful in SolutionManager.update(Object) to fill in shadow variable values.

Specified by:

forceTriggerVariableListeners in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

setCalculatedScore

protected void setCalculatedScore(Score_ score)

clone

@Deprecated(forRemoval=true,
            since="1.14.0")
public AbstractScoreDirector<Solution_,Score_,Factory_> clone()

Deprecated, for removal: This API element is subject to removal in a future version.

Unused, but kept for backward compatibility.

Overrides:

clone in class Object

createChildThreadScoreDirector

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

Specified by:

createChildThreadScoreDirector in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

close

public void close()

Description copied from interface: InnerScoreDirector

Needs to be called after use because some implementations need to clean up their resources.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

beforeEntityAdded

public void beforeEntityAdded(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

beforeEntityAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

afterEntityAdded

public void afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

afterEntityAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

beforeVariableChanged

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

Specified by:

beforeVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

afterVariableChanged

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

Specified by:

afterVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

beforeListVariableElementAssigned

public void beforeListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that will be assigned (added to a list variable of one entity without being removed from a list variable of another entity).

Specified by:

beforeListVariableElementAssigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Parameters:

variableDescriptor - the list variable descriptor

element - the assigned element

afterListVariableElementAssigned

public void afterListVariableElementAssigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that was assigned (added to a list variable of one entity without being removed from a list variable of another entity).

Specified by:

afterListVariableElementAssigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Parameters:

variableDescriptor - the list variable descriptor

element - the assigned element

beforeListVariableElementUnassigned

public void beforeListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that will be unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

beforeListVariableElementUnassigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Parameters:

variableDescriptor - the list variable descriptor

element - the unassigned element

afterListVariableElementUnassigned

public void afterListVariableElementUnassigned(ListVariableDescriptor<Solution_> variableDescriptor,
 Object element)

Description copied from interface: VariableDescriptorAwareScoreDirector

Call this for each element that was unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

afterListVariableElementUnassigned in interface VariableDescriptorAwareScoreDirector<Solution_>

Parameters:

variableDescriptor - the list variable descriptor

element - the unassigned element

beforeListVariableChanged

public void beforeListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor,
 Object entity,
 int fromIndex,
 int toIndex)

Description copied from interface: VariableDescriptorAwareScoreDirector

Notify the score director before a list variable changes.

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.

For the sake of variable listeners' efficiency, the change notification requires an index range that contains elements affected by the change. The range starts at fromIndex (inclusive) and ends at toIndex (exclusive).

The range has to comply with the following contract:

1. fromIndex must be greater than or equal to 0; toIndex must be less than or equal to the list variable size.
2. toIndex must be greater than or equal to fromIndex.
3. The range must contain all elements that are going to be changed.
4. The range is allowed to 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.

VariableDescriptorAwareScoreDirector.beforeListVariableElementUnassigned(ListVariableDescriptor, Object) must be called for each element that will be unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

beforeListVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

Parameters:

variableDescriptor - descriptor of the list variable being changed

entity - the entity owning the list variable being changed

fromIndex - low endpoint (inclusive) of the changed range

toIndex - high endpoint (exclusive) of the changed range

afterListVariableChanged

public void afterListVariableChanged(ListVariableDescriptor<Solution_> variableDescriptor,
 Object entity,
 int fromIndex,
 int toIndex)

Description copied from interface: VariableDescriptorAwareScoreDirector

Notify the score director after a list variable changes.

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.

For the sake of variable listeners' efficiency, the change notification requires an index range that contains elements affected by the change. The range starts at fromIndex (inclusive) and ends at toIndex (exclusive).

The range has to comply with the following contract:

1. fromIndex must be greater than or equal to 0; toIndex must be less than or equal to the list variable size.
2. toIndex must be greater than or equal to fromIndex.
3. The range must contain all elements that have changed.
4. The range is allowed to 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.

VariableDescriptorAwareScoreDirector.afterListVariableElementUnassigned(ListVariableDescriptor, Object) must be called for each element that was unassigned (removed from a list variable of one entity without being added to a list variable of another entity).

Specified by:

afterListVariableChanged in interface VariableDescriptorAwareScoreDirector<Solution_>

Parameters:

variableDescriptor - descriptor of the list variable being changed

entity - the entity owning the list variable being changed

fromIndex - low endpoint (inclusive) of the changed range

toIndex - high endpoint (exclusive) of the changed range

beforeEntityRemoved

public void beforeEntityRemoved(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

beforeEntityRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

afterEntityRemoved

public void afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor,
 Object entity)

Specified by:

afterEntityRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

beforeProblemFactAdded

public void beforeProblemFactAdded(Object problemFact)

Specified by:

beforeProblemFactAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

beforeProblemFactAdded in interface ScoreDirector<Solution_>

afterProblemFactAdded

public void afterProblemFactAdded(Object problemFact)

Specified by:

afterProblemFactAdded in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

afterProblemFactAdded in interface ScoreDirector<Solution_>

beforeProblemPropertyChanged

public void beforeProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

beforeProblemPropertyChanged in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

beforeProblemPropertyChanged in interface ScoreDirector<Solution_>

afterProblemPropertyChanged

public void afterProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

afterProblemPropertyChanged in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

afterProblemPropertyChanged in interface ScoreDirector<Solution_>

beforeProblemFactRemoved

public void beforeProblemFactRemoved(Object problemFact)

Specified by:

beforeProblemFactRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

beforeProblemFactRemoved in interface ScoreDirector<Solution_>

afterProblemFactRemoved

public void afterProblemFactRemoved(Object problemFact)

Specified by:

afterProblemFactRemoved in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Specified by:

afterProblemFactRemoved in interface ScoreDirector<Solution_>

lookUpWorkingObject

public <E> @Nullable E lookUpWorkingObject(@Nullable E externalObject)

Description copied from interface: ScoreDirector

Translates an entity or fact instance (often from another Thread or JVM) to this ScoreDirector's internal working instance. Useful for move rebasing and in a ProblemChange.

Matching is determined by the LookUpStrategyType on PlanningSolution. Matching uses a PlanningId by default.

Specified by:

lookUpWorkingObject in interface ScoreDirector<Solution_>

Type Parameters:

E - the object type

Returns:

null if externalObject is null

lookUpWorkingObjectOrReturnNull

public <E> @Nullable E lookUpWorkingObjectOrReturnNull(@Nullable E externalObject)

Description copied from interface: ScoreDirector

As defined by ScoreDirector.lookUpWorkingObject(Object), but doesn't fail fast if no workingObject was ever added for the externalObject. It's recommended to use ScoreDirector.lookUpWorkingObject(Object) instead, especially in move rebasing code.

Specified by:

lookUpWorkingObjectOrReturnNull in interface ScoreDirector<Solution_>

Type Parameters:

E - the object type

Returns:

null if externalObject is null or if there is no workingObject for externalObject

assertExpectedWorkingScore

public void assertExpectedWorkingScore(InnerScore<Score_> expectedWorkingScore,
 Object completedAction)

Description copied from interface: InnerScoreDirector

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 InnerScoreDirector.calculateScore() (when the score is otherwise determined) is correct.

Specified by:

assertExpectedWorkingScore in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

expectedWorkingScore - never null

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

assertShadowVariablesAreNotStale

public void assertShadowVariablesAreNotStale(InnerScore<Score_> expectedWorkingScore,
 Object completedAction)

Description copied from interface: InnerScoreDirector

Asserts that if all VariableListeners 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.

Specified by:

assertShadowVariablesAreNotStale in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

expectedWorkingScore - never null

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

buildShadowVariableAnalysis

protected String buildShadowVariableAnalysis(boolean predicted)

Parameters:

predicted - true if the score was predicted and might have been calculated on another thread

Returns:

never null

assertWorkingScoreFromScratch

public void assertWorkingScoreFromScratch(InnerScore<Score_> workingScore,
 Object completedAction)

Description copied from interface: InnerScoreDirector

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.

Specified by:

assertWorkingScoreFromScratch in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

workingScore - never null

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

See Also:

• ScoreDirectorFactory.assertScoreFromScratch(Solution_)

assertPredictedScoreFromScratch

public void assertPredictedScoreFromScratch(InnerScore<Score_> workingScore,
 Object completedAction)

Description copied from interface: InnerScoreDirector

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.

Specified by:

assertPredictedScoreFromScratch in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

workingScore - never null

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

See Also:

• ScoreDirectorFactory.assertScoreFromScratch(Solution_)

assertExpectedUndoMoveScore

public void assertExpectedUndoMoveScore(Move<Solution_> move,
 InnerScore<Score_> beforeMoveInnerScore,
 SolverLifecyclePoint executionPoint)

Description copied from interface: InnerScoreDirector

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.

Specified by:

assertExpectedUndoMoveScore in interface InnerScoreDirector<Solution_,Score_ extends Score<Score_>>

Parameters:

move - never null

beforeMoveInnerScore - never null

getSolutionCorruptionAfterUndo

public SolutionTracker.SolutionCorruptionResult getSolutionCorruptionAfterUndo(Move<Solution_> move,
 InnerScore<Score_> undoInnerScore)

buildScoreCorruptionAnalysis

protected String buildScoreCorruptionAnalysis(InnerScoreDirector<Solution_,Score_> uncorruptedScoreDirector,
 boolean predicted)

Parameters:

uncorruptedScoreDirector - never null

predicted - true if the score was predicted and might have been calculated on another thread

Returns:

never null

isConstraintConfiguration

protected boolean isConstraintConfiguration(Object problemFactOrEntity)

toString

public String toString()

Overrides:

toString in class Object