Interface ScoreDirector<Solution_>
-
- Type Parameters:
Solution_
- the solution type, the class with thePlanningSolution
annotation
- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
InnerScoreDirector<Solution_>
- All Known Implementing Classes:
AbstractScoreDirector
,ConstraintStreamScoreDirector
,DroolsScoreDirector
,EasyScoreDirector
,IncrementalScoreDirector
,TestGenDroolsScoreDirector
public interface ScoreDirector<Solution_> extends AutoCloseable
The ScoreDirector holds theworking solution
and calculates theScore
for it.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description void
afterEntityAdded(Object entity)
void
afterEntityRemoved(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
beforeEntityAdded(Object entity)
void
beforeEntityRemoved(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)
Score
calculateScore()
Calculates theScore
and updates theworking solution
accordingly.void
changeVariableFacade(VariableDescriptor variableDescriptor, Object entity, Object newValue)
void
close()
Needs to be called after use because some implementations need to clean up their resources.default void
dispose()
Deprecated.in favor ofclose()
String
explainScore()
Returns a diagnostic text that explains theScore
through theConstraintMatch
API to identify which constraints or planning entities cause that score quality.Map<String,ConstraintMatchTotal>
getConstraintMatchTotalMap()
Collection<ConstraintMatchTotal>
getConstraintMatchTotals()
Map<Object,Indictment>
getIndictmentMap()
Explains the impact of each planning entity or problem fact on theScore
.Solution_
getWorkingSolution()
ThePlanningSolution
that is used to calculate theScore
.boolean
isConstraintMatchEnabled()
<E> E
lookUpWorkingObject(E externalObject)
Translates an entity or fact instance (often from anotherThread
or JVM) to thisScoreDirector
's internal working instance.<E> E
lookUpWorkingObjectOrReturnNull(E externalObject)
As defined bylookUpWorkingObject(Object)
, but doesn't fail fast if no workingObject was ever added for the externalObject.void
setWorkingSolution(Solution_ workingSolution)
Theworking solution
must never be the same instance as thebest solution
, it should be a (un)changed clone.void
triggerVariableListeners()
-
-
-
Method Detail
-
getWorkingSolution
Solution_ getWorkingSolution()
ThePlanningSolution
that is used to calculate theScore
.Because a
Score
is best calculated incrementally (by deltas), theScoreDirector
needs to be notified when itsworking solution
changes.If the
working solution
has been changed sincecalculateScore()
was called, itsScore
won't be correct.- Returns:
- never null
-
setWorkingSolution
void setWorkingSolution(Solution_ workingSolution)
Theworking solution
must never be the same instance as thebest solution
, it should be a (un)changed clone.Only call this method on a separate
ScoreDirector
instance, built bySolverFactory.getScoreDirectorFactory()
, not on the one used inside theSolver
itself.- Parameters:
workingSolution
- never null
-
calculateScore
Score calculateScore()
Calculates theScore
and updates theworking solution
accordingly.- Returns:
- never null, the
Score
of theworking solution
-
isConstraintMatchEnabled
boolean isConstraintMatchEnabled()
- Returns:
- true if
getConstraintMatchTotals()
,getConstraintMatchTotalMap()
andgetIndictmentMap()
can be called
-
getConstraintMatchTotals
Collection<ConstraintMatchTotal> getConstraintMatchTotals()
Explains theScore
ofcalculateScore()
by splitting it up perConstraint
.The sum of
ConstraintMatchTotal.getScore()
equalscalculateScore()
.Call
calculateScore()
before calling this method, unless that method has already been called since the lastPlanningVariable
changes.- Returns:
- never null
- Throws:
IllegalStateException
- ifisConstraintMatchEnabled()
returns false- See Also:
getConstraintMatchTotalMap()
,getIndictmentMap()
-
getConstraintMatchTotalMap
Map<String,ConstraintMatchTotal> getConstraintMatchTotalMap()
Explains theScore
ofcalculateScore()
by splitting it up perConstraint
.The sum of
ConstraintMatchTotal.getScore()
equalscalculateScore()
.Call
calculateScore()
before calling this method, unless that method has already been called since the lastPlanningVariable
changes.- Returns:
- never null, the key is the
constraintId
(to create one, useConstraintMatchTotal.composeConstraintId(String, String)
). - Throws:
IllegalStateException
- ifisConstraintMatchEnabled()
returns false- See Also:
getIndictmentMap()
-
getIndictmentMap
Map<Object,Indictment> getIndictmentMap()
Explains the impact of each planning entity or problem fact on theScore
. AnIndictment
is basically the inverse of aConstraintMatchTotal
: it is aScore
total for each justificationObject
inConstraintMatch.getJustificationList()
.The sum of
ConstraintMatchTotal.getScore()
differs fromcalculateScore()
because eachConstraintMatch.getScore()
is counted for each justification inConstraintMatch.getJustificationList()
.Call
calculateScore()
before calling this method, unless that method has already been called since the lastPlanningVariable
changes.- Returns:
- never null, the key is a
problem fact
or aplanning entity
- Throws:
IllegalStateException
- ifisConstraintMatchEnabled()
returns false- See Also:
getConstraintMatchTotalMap()
-
explainScore
String explainScore()
Returns a diagnostic text that explains theScore
through theConstraintMatch
API to identify which constraints or planning entities cause that score quality. In case of aninfeasible
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
getConstraintMatchTotalMap()
andgetIndictmentMap()
and convert those into a domain specific API.This automatically calls
calculateScore()
first.- Returns:
- never null
- Throws:
IllegalStateException
- ifisConstraintMatchEnabled()
returns false
-
beforeEntityAdded
void beforeEntityAdded(Object entity)
-
afterEntityAdded
void afterEntityAdded(Object entity)
-
triggerVariableListeners
void triggerVariableListeners()
-
beforeEntityRemoved
void beforeEntityRemoved(Object entity)
-
afterEntityRemoved
void afterEntityRemoved(Object entity)
-
beforeProblemFactAdded
void beforeProblemFactAdded(Object problemFact)
-
afterProblemFactAdded
void afterProblemFactAdded(Object problemFact)
-
beforeProblemPropertyChanged
void beforeProblemPropertyChanged(Object problemFactOrEntity)
-
afterProblemPropertyChanged
void afterProblemPropertyChanged(Object problemFactOrEntity)
-
beforeProblemFactRemoved
void beforeProblemFactRemoved(Object problemFact)
-
afterProblemFactRemoved
void afterProblemFactRemoved(Object problemFact)
-
lookUpWorkingObject
<E> E lookUpWorkingObject(E externalObject)
Translates an entity or fact instance (often from anotherThread
or JVM) to thisScoreDirector
's internal working instance. Useful forMove.rebase(ScoreDirector)
and in aProblemFactChange
.Matching is determined by the
LookUpStrategyType
onPlanningSolution
. Matching uses aPlanningId
by default.- Type Parameters:
E
- the object type- Parameters:
externalObject
- sometimes null- Returns:
- null if externalObject is null
- Throws:
IllegalArgumentException
- if there is no workingObject for externalObject, if it cannot be looked up or if the externalObject's class is not supportedIllegalStateException
- if it cannot be looked up
-
lookUpWorkingObjectOrReturnNull
<E> E lookUpWorkingObjectOrReturnNull(E externalObject)
As defined bylookUpWorkingObject(Object)
, but doesn't fail fast if no workingObject was ever added for the externalObject. It's recommended to uselookUpWorkingObject(Object)
instead, especially in aMove.rebase(ScoreDirector)
code.- Type Parameters:
E
- the object type- Parameters:
externalObject
- sometimes null- Returns:
- null if externalObject is null or if there is no workingObject for externalObject
- Throws:
IllegalArgumentException
- if it cannot be looked up or if the externalObject's class is not supportedIllegalStateException
- if it cannot be looked up
-
close
void close()
Needs to be called after use because some implementations need to clean up their resources.- Specified by:
close
in interfaceAutoCloseable
-
dispose
@Deprecated default void dispose()
Deprecated.in favor ofclose()
-
beforeVariableChanged
void beforeVariableChanged(VariableDescriptor variableDescriptor, Object entity)
-
afterVariableChanged
void afterVariableChanged(VariableDescriptor variableDescriptor, Object entity)
-
changeVariableFacade
void changeVariableFacade(VariableDescriptor variableDescriptor, Object entity, Object newValue)
-
-