OptaPlanner core 6.0.0.CR4

org.optaplanner.core.api.domain.variable
Annotation Type PlanningVariable


@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface PlanningVariable

Specifies that a bean property can be changed and should be optimized by the optimization algorithms.

It is specified on a getter of a java bean property of a PlanningEntity class.


Optional Element Summary
 boolean chained
          In some use cases, such as Vehicle Routing, planning entities are chained.
 String mappedBy
          In a bidirectional relationship, the shadow side (= the slave side) uses this mappedBy() property (and nothing else) to declare for which normal PlanningVariable (= the master side) it is a shadow.
 boolean nullable
          A nullable planning variable will automatically add the planning value null to the ValueRangeProvider's range.
 Class<? extends SelectionFilter> reinitializeVariableEntityFilter
          Construction heuristics only change reinitializable planning variables.
 Class<? extends Comparator> strengthComparatorClass
          Allows a collection of planning values for this variable to be sorted by strength.
 Class<? extends SelectionSorterWeightFactory> strengthWeightFactoryClass
          The SelectionSorterWeightFactory alternative for strengthComparatorClass().
 String[] valueRangeProviderRefs
          Any ValueRangeProvider annotation on a PlanningSolution or PlanningEntity will automatically be registered with it's ValueRangeProvider.id().
 Class<? extends PlanningVariableListener>[] variableListenerClasses
          A PlanningVariableListener gets notified before and after a planning variable has changed.
 

mappedBy

public abstract String mappedBy
In a bidirectional relationship, the shadow side (= the slave side) uses this mappedBy() property (and nothing else) to declare for which normal PlanningVariable (= the master side) it is a shadow.

Both sides of a bidirectional relationship should be consistent: if A points to B then B must point to A. When planner changes a normal variable, it adjusts the shadow variable accordingly. In practice, planner ignores the shadow variables (except for consistency housekeeping).

Returns:
the variable property name on the opposite end of this bidirectional relationship
Default:
""

valueRangeProviderRefs

public abstract String[] valueRangeProviderRefs
Any ValueRangeProvider annotation on a PlanningSolution or PlanningEntity will automatically be registered with it's ValueRangeProvider.id().

There should be at least 1 valueRangeRef (unless mappedBy() is true).

Returns:
1 (or more) registered ValueRangeProvider.id()
Default:
{}

nullable

public abstract boolean nullable
A nullable planning variable will automatically add the planning value null to the ValueRangeProvider's range.

In repeated planning use cases, it's recommended to specify a reinitializeVariableEntityFilter() for every nullable planning variable too.

nullable() true is not compatible with {#link #chained} true. nullable() true is not compatible with a primitive property type.

Returns:
true if null is a valid value for this planning variable
Default:
false

reinitializeVariableEntityFilter

public abstract Class<? extends SelectionFilter> reinitializeVariableEntityFilter
Construction heuristics only change reinitializable planning variables. Non reinitializable planning variable is ignored by construction heuristics. This is especially useful in repeated planning use cases, in which starting from scratch would waste previous results and time.

If no reinitializeVariableEntityFilter() is specified, the default considers an entity uninitialized for a variable if its value is null (even if nullable() is true).

The method SelectionFilter.accept(ScoreDirector, Object) returns false if the selection entity should be reinitialized for this variable and it returns true if the selection entity should not be reinitialized for this variable

Returns:
PlanningVariable.NullReinitializeVariableEntityFilter when it is null (workaround for annotation limitation)
Default:
org.optaplanner.core.api.domain.variable.PlanningVariable.NullReinitializeVariableEntityFilter.class

chained

public abstract boolean chained
In some use cases, such as Vehicle Routing, planning entities are chained. A chained variable recursively points to a planning fact, which is called the anchor. So either it points directly to the anchor (that planning fact) or it points to another planning entity with the same planning variable (which recursively points to the anchor). Chains always have exactly 1 anchor, thus they never loop and the tail is always open. Chains never split into a tree: a anchor or planning entity has at most 1 trailing planning entity.

When a chained planning entity changes position, then chain correction must happen:

For example: Given A <- B <- C <- D <- X <- Y, when B moves between X and Y, pointing to X, then Y is also changed to point to B and C is also changed to point to A, giving the result A <- C <- D <- X <- B <- Y.

nullable() true is not compatible with {#link #chained} true.

Returns:
true if changes to this variable need to trigger chain correction
Default:
false

strengthComparatorClass

public abstract Class<? extends Comparator> strengthComparatorClass
Allows a collection of planning values for this variable to be sorted by strength. A strengthWeight estimates how strong a planning value is. Some algorithms benefit from planning on weaker planning values first or from focusing on them.

The Comparator should sort in ascending strength. For example: sorting 3 computers on strength based on their RAM capacity: Computer B (1GB RAM), Computer A (2GB RAM), Computer C (7GB RAM),

Do not use together with strengthWeightFactoryClass().

Returns:
PlanningVariable.NullStrengthComparator when it is null (workaround for annotation limitation)
See Also:
strengthWeightFactoryClass()
Default:
org.optaplanner.core.api.domain.variable.PlanningVariable.NullStrengthComparator.class

strengthWeightFactoryClass

public abstract Class<? extends SelectionSorterWeightFactory> strengthWeightFactoryClass
The SelectionSorterWeightFactory alternative for strengthComparatorClass().

Do not use together with strengthComparatorClass().

Returns:
PlanningVariable.NullStrengthWeightFactory when it is null (workaround for annotation limitation)
See Also:
strengthComparatorClass()
Default:
org.optaplanner.core.api.domain.variable.PlanningVariable.NullStrengthWeightFactory.class

variableListenerClasses

public abstract Class<? extends PlanningVariableListener>[] variableListenerClasses
A PlanningVariableListener gets notified before and after a planning variable has changed. That listener changes shadow variables (often on other planning entities) accordingly, Those shadow variables can make the score calculation more natural to write.

For example: VRP with time windows uses a PlanningVariableListener to update the arrival times of all the trailing entities when an entity is changed.

Returns:
never null
Default:
{}

OptaPlanner core 6.0.0.CR4

Copyright © 2006-2013 JBoss by Red Hat. All Rights Reserved.