Chapter 19. Migration Guide

If you have a @ValueRangeProvider that returns a collection of numbers (for example List<Integer> or List<BigDecimal>), then you should switch to a ValueRange, which uses less memory and offers additional opportunities.

For example:

@ValueRangeProvider(id = "delayRange")
public List<Integer> getDelayRange() {
    List<Integer> = new ArrayList<Integer>(5000);
    for (int i = 0; i < 5000; i++) {
        delayRange.add(i);
    }
    return delayRange;
}

Is changed to:

@ValueRangeProvider(id = "delayRange")
public CountableValueRange<Integer> getDelayRange() {
    return ValueRangeFactory.createIntValueRange(0, 5000);
}

import org.optaplanner.core.api.domain.value.ValueRangeProvider;

import org.optaplanner.core.api.domain.valuerange.ValueRangeProvider;

The interface PlanningVariableListener has been renamed to VariableListener.

Previously in *.java :

public class VehicleUpdatingVariableListener implements PlanningVariableListener<Customer> {

Now in *.java :

public class VehicleUpdatingVariableListener implements VariableListener<Customer> {

The class AbstractPlanningVariableListener has been removed.

Previously in *.java :

public class VehicleUpdatingVariableListener extends AbstractPlanningVariableListener<Customer> {

Now in *.java :

public class VehicleUpdatingVariableListener implements VariableListener<Customer> {

The VariableListener is now declared on the shadow side, instead of the @PlanningVariable side. This way, Business Rules Planner recognizes the shadow variables, and all shadow variables are declared in a consistent matter. Furthermore, it allows a shadow variable to based on other shadow variable.

Previously in *.java :

@PlanningVariable(valueRangeProviderRefs = {"vehicleRange", "customerRange"},
        graphType = PlanningVariableGraphType.CHAINED,
        variableListenerClasses = {VehicleUpdatingVariableListener.class, ArrivalTimeUpdatingVariableListener.class})
public Standstill getPreviousStandstill() {
    return previousStandstill;
}

public Vehicle getVehicle() {
    return vehicle;
}

public Integer getArrivalTime() {
    return arrivalTime;
}

Now in *.java :

@PlanningVariable(...)
public Standstill getPreviousStandstill() {
    return previousStandstill;
}

@CustomShadowVariable(variableListenerClass = VehicleUpdatingVariableListener.class,
        sources = {@CustomShadowVariable.Source(variableName = "previousStandstill")})
public Vehicle getVehicle() {
    return vehicle;
}

@CustomShadowVariable(variableListenerClass = ArrivalTimeUpdatingVariableListener.class,
        sources = {@CustomShadowVariable.Source(variableName = "previousStandstill")})
public Integer getArrivalTime() {
    return arrivalTime;
}

There is now out-of-the-box support for a shadow variable representing the anchor of a chained variable. For example, in a VRP each Customer (= entity) needs to know to which Vehicle (= anchor) it belongs. This declarative support allows build-in selectors to reuse that knowledge without duplicating the calculation.

Previously in *.java :

@PlanningEntity
public class Customer implements Standstill {

    @PlanningVariable(...)
    public Standstill getPreviousStandstill() {...}

    @CustomShadowVariable(variableListenerClass = VehicleUpdatingVariableListener.class,
            sources = {@CustomShadowVariable.Source(variableName = "previousStandstill")})
    public Vehicle getVehicle() {...}

}
public class VehicleUpdatingVariableListener implements VariableListener<Customer> {
    ...
}

Now in *.java :

@PlanningEntity
public class Customer implements Standstill {

    @PlanningVariable(...)
    public Standstill getPreviousStandstill() {...}

    @AnchorShadowVariable(sourceVariableName = "previousStandstill")
    public Vehicle getVehicle() {...}
}

To scale VRP cases, Nearby Selection is critical. It is now finally completely supported and documented.

ProblemIO has been renamed to SolutionFileIO and moved package (into the public API).

Previously in *.java :

import org.optaplanner.core.impl.solution.ProblemIO;
public class MachineReassignmentFileIO implements ProblemIO {
    ...
}

Now in *.java :

import org.optaplanner.persistence.common.api.domain.solution.SolutionFileIO;
public class MachineReassignmentFileIO implements SolutionFileIO {
    ...
}

Now in *.java :

Previously in *SolverConfig.xml and *BenchmarckConfig.xml :

<problemBenchmarks>
<problemIOClass>...MachineReassignmentProblemIO</problemIOClass>
...
</problemBenchmarks>

Now in *SolverConfig.xml and *BenchmarckConfig.xml :

<problemBenchmarks>
<solutionFileIOClass>...MachineReassignmentFileIO</solutionFileIOClass>
...
</problemBenchmarks>

The method SolutionFileIO.getFileExtension() has been split up in getInputFileExtension() and getOutputFileExtension();. It is still highly recommended to use the same input and output file extension.

Previously in *.java :

public String getFileExtension() {
    return FILE_EXTENSION;
}

Now in *.java :

public String getInputFileExtension() {
    return FILE_EXTENSION;
}
public String getOutputFileExtension() {
    return FILE_EXTENSION;
}

All child elements of <termination> have been renamed:

Configuration in *SolverConfig.xml and *BenchmarkConfig.xml has changed from:

<termination>
  <maximumTimeMillisSpend>...</maximumTimeMillisSpend>
  <maximumSecondsSpend>...</maximumSecondsSpend>
  <maximumMinutesSpend>...</maximumMinutesSpend>
  <maximumHoursSpend>...</maximumHoursSpend>
  <scoreAttained>...</scoreAttained>
  <maximumStepCount>...</maximumStepCount>
  <maximumUnimprovedStepCount>...</maximumUnimprovedStepCount>
</termination>

to:

<termination>
  <millisecondsSpentLimit>...</millisecondsSpentLimit>
  <secondsSpentLimit>...</secondsSpentLimit>
  <minutesSpentLimit>...</minutesSpentLimit>
  <hoursSpentLimit>...</hoursSpentLimit>
  <bestScoreLimit>...</bestScoreLimit>
  <stepCountLimit>...</stepCountLimit>
  <unimprovedStepCountLimit>...</unimprovedStepCountLimit>
</termination>

Classes BestSolutionChangedEvent and SolverEventListener moved from package impl.event to api.solver.event. They are now part of the public api.

Previously in *.java :

import org.optaplanner.core.impl.event.BestSolutionChangedEvent;
import org.optaplanner.core.impl.event.SolverEventListener;

Now in *.java :

import org.optaplanner.core.api.solver.event.BestSolutionChangedEvent;
import org.optaplanner.core.api.solver.event.SolverEventListener;

Specify an <initializingScoreTrend> in the <scoreDirectorFactory> to increase performance of some algorithms (Construction Heuristics and Exhaustive Search).

See the documentation section on InitializingScoreTrend when to use ANY, ONLY_UP, or ONLY_DOWN.

Previously in *SolverConfig.xml and *BenchmarkConfig.xml :

<scoreDirectorFactory>
  <scoreDefinitionType>HARD_SOFT</scoreDefinitionType>
  <scoreDrl>.../cloudBalancingScoreRules.drl</scoreDrl>
</scoreDirectorFactory>

Now in *SolverConfig.xml and *BenchmarkConfig.xml :

<scoreDirectorFactory>
  <scoreDefinitionType>HARD_SOFT</scoreDefinitionType>
  <scoreDrl>.../cloudBalancingScoreRules.drl</scoreDrl>
  <initializingScoreTrend>ONLY_DOWN</initializingScoreTrend>
</scoreDirectorFactory>

Replace <pickEarlyType> FIRST_NON_DETERIORATING_SCORE with <initializingScoreTrend> ONLY_DOWN. If the <initializingScoreTrend> is specified, the <constructionHeuristic> will automatically use the most appropriate <pickEarlyType>.

Previously in *SolverConfig.xml and *BenchmarkConfig.xml:

<scoreDirectorFactory>
  ...
</scoreDirectorFactory>
...
<constructionHeuristic>
  <constructionHeuristicType>FIRST_FIT_DECREASING</constructionHeuristicType>
  <forager>
    <pickEarlyType>FIRST_NON_DETERIORATING_SCORE</pickEarlyType>
  </forager>
</constructionHeuristic>

Now in *SolverConfig.xml and *BenchmarkConfig.xml :

<scoreDirectorFactory>
  ...
  <initializingScoreTrend>ONLY_DOWN</initializingScoreTrend>
</scoreDirectorFactory>
...
<constructionHeuristic>
  <constructionHeuristicType>FIRST_FIT_DECREASING</constructionHeuristicType>
</constructionHeuristic>

The interface SimpleScoreCalculator has been renamed to EasyScoreCalculator to avoid confusion with SimpleScore and SimpleScore: it can return other Score types. The package name has also changed.

Previously in *.java :

import org.optaplanner.core.impl.score.director.simple.SimpleScoreCalculator;

public class CloudBalancingEasyScoreCalculator implements SimpleScoreCalculator<CloudBalance> {
    ...
}

Now in *.java :

import org.optaplanner.core.impl.score.director.easy.EasyScoreCalculator;

public class CloudBalancingEasyScoreCalculator implements EasyScoreCalculator<CloudBalance> {
    ...
}

Previously in *SolverConfig.xml and *BenchmarkConfig.xml :

<simpleScoreCalculatorClass>org.optaplanner.examples.cloudbalancing.solver.score.CloudBalancingEasyScoreCalculator<simpleScoreCalculatorClass>

Now in *SolverConfig.xml and *BenchmarkConfig.xml :

<easyScoreCalculatorClass>org.optaplanner.examples.cloudbalancing.solver.score.CloudBalancingEasyScoreCalculator

The BendableScore configuration has changed: …​LevelCount has been renamed to …​LevelsSize.

Previously in *SolverConfig.xml and *BenchmarkConfig.xml :

<scoreDirectorFactory>
  <scoreDefinitionType>BENDABLE</scoreDefinitionType>
  <bendableHardLevelCount>2</bendableHardLevelCount>
  <bendableSoftLevelCount>3</bendableSoftLevelCount>
  ...
</scoreDirectorFactory>

Now in *SolverConfig.xml and *BenchmarkConfig.xml :

<scoreDirectorFactory>
  <scoreDefinitionType>BENDABLE</scoreDefinitionType>
  <bendableHardLevelsSize>2</bendableHardLevelsSize>
  <bendableSoftLevelsSize>3</bendableSoftLevelsSize>
  ...
</scoreDirectorFactory>