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

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

java.lang.Object

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

All Implemented Interfaces:

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

Direct Known Subclasses:

BavetConstraintStreamScoreDirector, DrlScoreDirector, DroolsConstraintStreamScoreDirector, EasyScoreDirector, IncrementalScoreDirector

public abstract class AbstractScoreDirector<Solution_,Score_ extends Score<Score_>,Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_>>
extends Object
implements InnerScoreDirector<Solution_,Score_>, 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<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 PlanningIds with a null value.
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<Solution_> variableDescriptor, Object entity)
protected String	buildScoreCorruptionAnalysis(InnerScoreDirector<Solution_,Score_> uncorruptedScoreDirector, boolean predicted)
protected String	buildShadowVariableAnalysis(boolean predicted)
void	changeVariableFacade(VariableDescriptor<Solution_> variableDescriptor, Object entity, Object newValue)
AbstractScoreDirector<Solution_,Score_,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_,Score_>	createChildThreadScoreDirector(ChildThreadType childThreadType)
protected String	createShadowVariablesViolationMessage()
Score_	doAndProcessMove(Move<Solution_> move, boolean assertMoveScoreFromScratch)
void	doAndProcessMove(Move<Solution_> move, boolean assertMoveScoreFromScratch, Consumer<Score_> moveProcessor)
long	getCalculationCount()
ScoreDefinition<Score_>	getScoreDefinition()
Factory_	getScoreDirectorFactory()
SolutionDescriptor<Solution_>	getSolutionDescriptor()
SupplyManager<Solution_>	getSupplyManager()
long	getWorkingEntityListRevision()
Solution_	getWorkingSolution()	The PlanningSolution that is used to calculate the Score.
boolean	isAllChangesWillBeUndoneBeforeStepEnds()
protected boolean	isConstraintConfiguration(Object problemFactOrEntity)
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.InnerScoreDirector

calculateScore, getConstraintMatchTotalMap, getIndictmentMap, isConstraintMatchEnabled, requiresFlushing

Field Detail

logger

protected final transient org.slf4j.Logger logger

scoreDirectorFactory

protected final Factory_ extends AbstractScoreDirectorFactory<Solution_,Score_> 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_,Score_ extends Score<Score_>>

Returns:

never null

getSolutionDescriptor

public SolutionDescriptor<Solution_> getSolutionDescriptor()

Specified by:

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

Returns:

never null

getScoreDefinition

public ScoreDefinition<Score_> getScoreDefinition()

Specified by:

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

Returns:

never null

isLookUpEnabled

public boolean isLookUpEnabled()

isConstraintMatchEnabledPreference

public boolean isConstraintMatchEnabledPreference()

overwriteConstraintMatchEnabledPreference

public void overwriteConstraintMatchEnabledPreference(boolean constraintMatchEnabledPreference)

Specified by:

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

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.

Specified by:

getWorkingSolution in interface ScoreDirector<Solution_>

Returns:

never null

getWorkingEntityListRevision

public long getWorkingEntityListRevision()

Specified by:

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

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

getSupplyManager

public SupplyManager<Solution_> getSupplyManager()

Specified by:

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

Returns:

never null

setWorkingSolution

public void setWorkingSolution(Solution_ workingSolution)

Description copied from interface: InnerScoreDirector

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

Specified by:

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

Parameters:

workingSolution - never null

assertNonNullPlanningIds

public void assertNonNullPlanningIds()

Description copied from interface: InnerScoreDirector

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

Specified by:

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

doAndProcessMove

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

Specified by:

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

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_,Score_ extends Score<Score_>>

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_,Score_ extends Score<Score_>>

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_,Score_ extends Score<Score_>>

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_,Score_ extends Score<Score_>>

Parameters:

originalSolution - never null

Returns:

never null, planning clone

triggerVariableListeners

public void triggerVariableListeners()

Specified by:

triggerVariableListeners in interface ScoreDirector<Solution_>

setCalculatedScore

protected void setCalculatedScore(Score_ score)

clone

public AbstractScoreDirector<Solution_,Score_,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_,Score_ extends Score<Score_>>

Overrides:

clone in class Object

Returns:

never null

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 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<Solution_> variableDescriptor,
                                  Object entity)

Specified by:

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

afterVariableChanged

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

Specified by:

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

changeVariableFacade

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

Specified by:

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

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

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 move rebasing 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 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(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

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

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

InnerScoreDirectorFactory.assertScoreFromScratch(Solution_)

assertExpectedUndoMoveScore

public void assertExpectedUndoMoveScore(Move<Solution_> 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_,Score_ extends Score<Score_>>

Parameters:

move - never null

beforeMoveScore - never null

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