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

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

java.lang.Object

org.optaplanner.core.impl.score.director.AbstractScoreDirector<Solution_,Factory_>

All Implemented Interfaces:

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

Direct Known Subclasses:

ConstraintStreamScoreDirector, DroolsScoreDirector, EasyScoreDirector, IncrementalScoreDirector

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

Abstract superclass for ScoreDirector.

Implementation note: Extending classes should follow these guidelines:

• before* method: last statement should be a call to the super method
• after* method: first statement should be a call to the super method

See Also:

ScoreDirector

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	allChangesWillBeUndoneBeforeStepEnds
protected long	calculationCount
protected boolean	constraintMatchEnabledPreference
protected org.slf4j.Logger	logger
protected boolean	lookUpEnabled
protected LookUpManager	lookUpManager
protected Factory_	scoreDirectorFactory
protected VariableListenerSupport<Solution_>	variableListenerSupport
protected long	workingEntityListRevision
protected Integer	workingInitScore
protected Solution_	workingSolution

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractScoreDirector(Factory_ scoreDirectorFactory, boolean lookUpEnabled, boolean constraintMatchEnabledPreference)

Method Summary

Modifier and Type	Method	Description
void	afterEntityAdded(Object entity)
void	afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	afterEntityRemoved(Object entity)
void	afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	afterProblemFactAdded(Object problemFact)
void	afterProblemFactRemoved(Object problemFact)
void	afterProblemPropertyChanged(Object problemFactOrEntity)
void	afterVariableChanged(Object entity, String variableName)
void	afterVariableChanged(VariableDescriptor variableDescriptor, Object entity)
void	assertExpectedUndoMoveScore(Move 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	assertPredictedScoreFromScratch(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(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(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(Object entity)
void	beforeEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	beforeEntityRemoved(Object entity)
void	beforeEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Object entity)
void	beforeProblemFactAdded(Object problemFact)
void	beforeProblemFactRemoved(Object problemFact)
void	beforeProblemPropertyChanged(Object problemFactOrEntity)
void	beforeVariableChanged(Object entity, String variableName)
void	beforeVariableChanged(VariableDescriptor variableDescriptor, Object entity)
protected String	buildScoreCorruptionAnalysis(ScoreDirector<Solution_> uncorruptedScoreDirector, boolean predicted)
protected String	buildShadowVariableAnalysis(boolean predicted)
void	changeVariableFacade(VariableDescriptor variableDescriptor, Object entity, Object newValue)
AbstractScoreDirector<Solution_,Factory_>	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_>	createChildThreadScoreDirector(ChildThreadType childThreadType)
protected String	createShadowVariablesViolationMessage()
Score	doAndProcessMove(Move<Solution_> move, boolean assertMoveScoreFromScratch)
void	doAndProcessMove(Move<Solution_> move, boolean assertMoveScoreFromScratch, Consumer<Score> moveProcessor)
String	explainScore()	Returns a diagnostic text that explains the Score through the ConstraintMatch API to identify which constraints or planning entities cause that score quality.
long	getCalculationCount()
ScoreDefinition	getScoreDefinition()
Factory_	getScoreDirectorFactory()
SolutionDescriptor<Solution_>	getSolutionDescriptor()
SupplyManager	getSupplyManager()
int	getWorkingEntityCount()
List<Object>	getWorkingEntityList()
long	getWorkingEntityListRevision()
Solution_	getWorkingSolution()	The PlanningSolution that is used to calculate the Score.
int	getWorkingValueCount()
boolean	isAllChangesWillBeUndoneBeforeStepEnds()
boolean	isConstraintMatchEnabledPreference()
boolean	isLookUpEnabled()
boolean	isWorkingEntityListDirty(long expectedWorkingEntityListRevision)
<E> E	lookUpWorkingObject(E externalObject)	Translates an entity or fact instance (often from another Thread or JVM) to this ScoreDirector's internal working instance.
<E> E	lookUpWorkingObjectOrReturnNull(E externalObject)	As defined by ScoreDirector.lookUpWorkingObject(Object), but doesn't fail fast if no workingObject was ever added for the externalObject.
void	overwriteConstraintMatchEnabledPreference(boolean constraintMatchEnabledPreference)
void	resetCalculationCount()
void	setAllChangesWillBeUndoneBeforeStepEnds(boolean allChangesWillBeUndoneBeforeStepEnds)	Do not waste performance by propagating changes to step (or higher) mechanisms.
protected void	setCalculatedScore(Score score)
protected void	setWorkingEntityListDirty()
void	setWorkingSolution(Solution_ workingSolution)	The working solution must never be the same instance as the best solution, it should be a (un)changed clone.
String	toString()
void	triggerVariableListeners()

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.optaplanner.core.impl.score.director.ScoreDirector

calculateScore, dispose, getConstraintMatchTotalMap, getConstraintMatchTotals, getIndictmentMap, isConstraintMatchEnabled

Field Detail

logger

protected final transient org.slf4j.Logger logger

scoreDirectorFactory

protected final Factory_ extends AbstractScoreDirectorFactory<Solution_> scoreDirectorFactory

lookUpEnabled

protected final boolean lookUpEnabled

lookUpManager

protected final LookUpManager lookUpManager

constraintMatchEnabledPreference

protected boolean constraintMatchEnabledPreference

variableListenerSupport

protected final VariableListenerSupport<Solution_> variableListenerSupport

workingSolution

protected Solution_ workingSolution

workingEntityListRevision

protected long workingEntityListRevision

workingInitScore

protected Integer workingInitScore

allChangesWillBeUndoneBeforeStepEnds

protected boolean allChangesWillBeUndoneBeforeStepEnds

calculationCount

protected long calculationCount

Constructor Detail

AbstractScoreDirector

protected AbstractScoreDirector(Factory_ scoreDirectorFactory,
                                boolean lookUpEnabled,
                                boolean constraintMatchEnabledPreference)

Method Detail

getScoreDirectorFactory

public Factory_ getScoreDirectorFactory()

Specified by:

getScoreDirectorFactory in interface InnerScoreDirector<Solution_>

Returns:

never null

getSolutionDescriptor

public SolutionDescriptor<Solution_> getSolutionDescriptor()

Specified by:

getSolutionDescriptor in interface InnerScoreDirector<Solution_>

Returns:

never null

getScoreDefinition

public ScoreDefinition getScoreDefinition()

Specified by:

getScoreDefinition in interface InnerScoreDirector<Solution_>

Returns:

never null

isLookUpEnabled

public boolean isLookUpEnabled()

isConstraintMatchEnabledPreference

public boolean isConstraintMatchEnabledPreference()

overwriteConstraintMatchEnabledPreference

public void overwriteConstraintMatchEnabledPreference(boolean constraintMatchEnabledPreference)

Specified by:

overwriteConstraintMatchEnabledPreference in interface InnerScoreDirector<Solution_>

Parameters:

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

getWorkingSolution

public 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.

If the working solution has been changed since ScoreDirector.calculateScore() was called, its Score won't be correct.

Specified by:

getWorkingSolution in interface ScoreDirector<Solution_>

Returns:

never null

getWorkingEntityListRevision

public long getWorkingEntityListRevision()

Specified by:

getWorkingEntityListRevision in interface InnerScoreDirector<Solution_>

Returns:

used to check InnerScoreDirector.isWorkingEntityListDirty(long) later on

isAllChangesWillBeUndoneBeforeStepEnds

public boolean isAllChangesWillBeUndoneBeforeStepEnds()

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_>

Parameters:

allChangesWillBeUndoneBeforeStepEnds - true if all changes will be undone

getCalculationCount

public long getCalculationCount()

Specified by:

getCalculationCount in interface InnerScoreDirector<Solution_>

Returns:

at least 0L

resetCalculationCount

public void resetCalculationCount()

Specified by:

resetCalculationCount in interface InnerScoreDirector<Solution_>

getSupplyManager

public SupplyManager getSupplyManager()

Specified by:

getSupplyManager in interface InnerScoreDirector<Solution_>

Returns:

never null

setWorkingSolution

public void setWorkingSolution(Solution_ workingSolution)

Description copied from interface: ScoreDirector

The working solution must never be the same instance as the best solution, it should be a (un)changed clone.

Only call this method on a separate ScoreDirector instance, built by SolverFactory.getScoreDirectorFactory(), not on the one used inside the Solver itself.

Specified by:

setWorkingSolution in interface ScoreDirector<Solution_>

Parameters:

workingSolution - never null

doAndProcessMove

public Score doAndProcessMove(Move<Solution_> move,
                              boolean assertMoveScoreFromScratch)

Specified by:

doAndProcessMove in interface InnerScoreDirector<Solution_>

Parameters:

move - never null

assertMoveScoreFromScratch - true will hurt performance

Returns:

never null

doAndProcessMove

public void doAndProcessMove(Move<Solution_> move,
                             boolean assertMoveScoreFromScratch,
                             Consumer<Score> moveProcessor)

Specified by:

doAndProcessMove in interface InnerScoreDirector<Solution_>

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

public boolean isWorkingEntityListDirty(long expectedWorkingEntityListRevision)

Specified by:

isWorkingEntityListDirty in interface InnerScoreDirector<Solution_>

Parameters:

expectedWorkingEntityListRevision - an

Returns:

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

setWorkingEntityListDirty

protected void setWorkingEntityListDirty()

cloneWorkingSolution

public Solution_ cloneWorkingSolution()

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:

cloneWorkingSolution in interface InnerScoreDirector<Solution_>

Returns:

never null, planning clone

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_>

Parameters:

originalSolution - never null

Returns:

never null, planning clone

getWorkingEntityCount

public int getWorkingEntityCount()

Specified by:

getWorkingEntityCount in interface InnerScoreDirector<Solution_>

Returns:

>= 0

getWorkingEntityList

public List<Object> getWorkingEntityList()

Specified by:

getWorkingEntityList in interface InnerScoreDirector<Solution_>

Returns:

never null: an empty list if there are none

getWorkingValueCount

public int getWorkingValueCount()

Specified by:

getWorkingValueCount in interface InnerScoreDirector<Solution_>

Returns:

>= 0

triggerVariableListeners

public void triggerVariableListeners()

Specified by:

triggerVariableListeners in interface ScoreDirector<Solution_>

setCalculatedScore

protected void setCalculatedScore(Score score)

explainScore

public String explainScore()

Description copied from interface: ScoreDirector

Returns a diagnostic text that explains the Score through the ConstraintMatch API to identify which constraints or planning entities cause that score quality. In case of an infeasible solution, this can help diagnose the cause of that.

Do not parse this string. Instead, to provide this information in a UI or a service, use ScoreDirector.getConstraintMatchTotalMap() and ScoreDirector.getIndictmentMap() and convert those into a domain specific API.

This automatically calls ScoreDirector.calculateScore() first.

Specified by:

explainScore in interface ScoreDirector<Solution_>

Returns:

never null

clone

public AbstractScoreDirector<Solution_,Factory_> clone()

Description copied from interface: InnerScoreDirector

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.

Specified by:

clone in interface InnerScoreDirector<Solution_>

Overrides:

clone in class Object

Returns:

never null

createChildThreadScoreDirector

public InnerScoreDirector<Solution_> createChildThreadScoreDirector(ChildThreadType childThreadType)

Specified by:

createChildThreadScoreDirector in interface InnerScoreDirector<Solution_>

close

public void close()

Description copied from interface: ScoreDirector

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 ScoreDirector<Solution_>

beforeEntityAdded

public final void beforeEntityAdded(Object entity)

Specified by:

beforeEntityAdded in interface ScoreDirector<Solution_>

afterEntityAdded

public final void afterEntityAdded(Object entity)

Specified by:

afterEntityAdded in interface ScoreDirector<Solution_>

beforeVariableChanged

public final void beforeVariableChanged(Object entity,
                                        String variableName)

Specified by:

beforeVariableChanged in interface ScoreDirector<Solution_>

afterVariableChanged

public final void afterVariableChanged(Object entity,
                                       String variableName)

Specified by:

afterVariableChanged in interface ScoreDirector<Solution_>

beforeEntityRemoved

public final void beforeEntityRemoved(Object entity)

Specified by:

beforeEntityRemoved in interface ScoreDirector<Solution_>

afterEntityRemoved

public final void afterEntityRemoved(Object entity)

Specified by:

afterEntityRemoved in interface ScoreDirector<Solution_>

beforeEntityAdded

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

afterEntityAdded

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

beforeVariableChanged

public void beforeVariableChanged(VariableDescriptor variableDescriptor,
                                  Object entity)

Specified by:

beforeVariableChanged in interface ScoreDirector<Solution_>

afterVariableChanged

public void afterVariableChanged(VariableDescriptor variableDescriptor,
                                 Object entity)

Specified by:

afterVariableChanged in interface ScoreDirector<Solution_>

changeVariableFacade

public void changeVariableFacade(VariableDescriptor variableDescriptor,
                                 Object entity,
                                 Object newValue)

Specified by:

changeVariableFacade in interface ScoreDirector<Solution_>

beforeEntityRemoved

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

afterEntityRemoved

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

beforeProblemFactAdded

public void beforeProblemFactAdded(Object problemFact)

Specified by:

beforeProblemFactAdded in interface ScoreDirector<Solution_>

afterProblemFactAdded

public void afterProblemFactAdded(Object problemFact)

Specified by:

afterProblemFactAdded in interface ScoreDirector<Solution_>

beforeProblemPropertyChanged

public void beforeProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

beforeProblemPropertyChanged in interface ScoreDirector<Solution_>

afterProblemPropertyChanged

public void afterProblemPropertyChanged(Object problemFactOrEntity)

Specified by:

afterProblemPropertyChanged in interface ScoreDirector<Solution_>

beforeProblemFactRemoved

public void beforeProblemFactRemoved(Object problemFact)

Specified by:

beforeProblemFactRemoved in interface ScoreDirector<Solution_>

afterProblemFactRemoved

public void afterProblemFactRemoved(Object problemFact)

Specified by:

afterProblemFactRemoved in interface ScoreDirector<Solution_>

lookUpWorkingObject

public <E> E lookUpWorkingObject(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.rebase(ScoreDirector) and in a ProblemFactChange.

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

Parameters:

externalObject - sometimes null

Returns:

null if externalObject is null

lookUpWorkingObjectOrReturnNull

public <E> E lookUpWorkingObjectOrReturnNull(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 a Move.rebase(ScoreDirector) code.

Specified by:

lookUpWorkingObjectOrReturnNull in interface ScoreDirector<Solution_>

Type Parameters:

E - the object type

Parameters:

externalObject - sometimes null

Returns:

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

assertExpectedWorkingScore

public void assertExpectedWorkingScore(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 ScoreDirector.calculateScore() (when the score is otherwise determined) is correct.

Specified by:

assertExpectedWorkingScore in interface InnerScoreDirector<Solution_>

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(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_>

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

createShadowVariablesViolationMessage

protected String createShadowVariablesViolationMessage()

Returns:

null if there are no violations

assertWorkingScoreFromScratch

public void assertWorkingScoreFromScratch(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_>

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

public void assertPredictedScoreFromScratch(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_>

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_)

assertExpectedUndoMoveScore

public void assertExpectedUndoMoveScore(Move move,
                                        Score beforeMoveScore)

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_>

Parameters:

move - never null

beforeMoveScore - never null

buildScoreCorruptionAnalysis

protected String buildScoreCorruptionAnalysis(ScoreDirector<Solution_> 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

toString

public String toString()

Overrides:

toString in class Object