Release Notes

Nearby selection is now available for planning domains using a planning list variable.

The AbstractScoreHibernateType as well as all its subtypes have been deprecated. The parallel OptaPlanner 9 releases are going to introduce Hibernate 6, which unfortunately breaks backward compatibility of the CompositeUserType that the AbstractScoreHibernateType depends on.

The AbstractScoreHibernateType and its subtypes remain available in the OptaPlanner 8 releases to provide integration with Hibernate 5 but have been removed from the equivalent OptaPlanner 9.x release.

To integrate the PlanningScore of your choice with Hibernate 6, either use the score converters available in the org.optaplanner.persistence.jpa.api.score.buildin package or implement the CompositeUserType yourself.

The codebase for OptaWeb Vehicle Routing demo application has been frozen and will no longer receive any updates.

We encourage users to check out the OptaPlanner Vehicle Routing Quickstart for a simple and straight-forward way of integrating OptaPlanner in your application.

A new move selector for list variables, KOptListMoveSelector, has been added. The KOptListMoveSelector selects a single entity, removes k edges from its route, and add k new edges from the removed edges' endpoints. The KOptListMoveSelector can help the solver escape local optima in vehicle routing problems. Configuration options are available in the documentation.

SolutionManager (formerly ScoreManager) methods such as explain(solution) and update(solution) received a new overload with an extra argument, SolutionUpdatePolicy. This has often been requested by users who load their solutions from persistent storage (such as a relational database), where these solutions do not include the information carried by shadow variables or even the score. By calling these new overloads and picking the right policy, OptaPlanner will automatically compute values for all the shadow variables in the given solution and/or recalculate the score.

Similarly, ProblemChangeDirector received a new method called `updateShadowVariables(), so that you can update shadow variables on demand in real-time planning.

OptaPlanner can now auto-detect situations where multiple pillar move selectors can share a pre-computed pillar cache and reuse it instead of recomputing it for each move selector. Users who combine different pillar moves (such as PillarChangeMove and PillarSwapMove) should see significant benefits.

The same applies to users of nearby selection. OptaPlanner can now auto-detect situations where a pre-computed distance matrix can be shared between multiple move selectors, saving a considerable amount of memory and CPU processing time.

As a consequence, implementations of the following interfaces are expected to be stateless:

In general, if solver configuration asks the user to implement an interface, the expectation is that the implementation will be stateless or at the very least not try to include external state. With the aforementioned performance improvements, failing to follow this requirement will result in subtle bugs and score corruption as the solver will now reuse these instances as it sees fit.

Various configuration classes, such as EntitySelectorConfig and ValueSelectorConfig, received new builder methods which make it easier than ever to replace XML-based solver config with fluent Java code.

In most cases, links between planning variables and value ranges can now be auto-detected. Therefore, @ValueRangeProvider no longer needs to provide an id property. Likewise, planning variables no longer need to reference value range providers via valueRangeProviderRefs property.

No code changes or configuration changes are required. Users who prefer clarity over brevity may continue to explicitly reference their value range providers.

Given that XStream has multiple CVEs against it and no recent releases, we have decided to deprecate OptaPlanner’s support for serializing into XML using XStream. To continue serializing into XML, please switch to the optaplanner-persistence-jaxb module.

All classes in the optaplanner-persistence-xstream, as well as the module itself, are now deprecated and will be removed in a future major version of OptaPlanner.

All examples in the optaplanner-examples module have been refactored to JSON using the optaplanner-persistance-jackson module. Quickstarts were not affected by these changes, as they already were serializing into JSON.

In an ongoing effort to clean up code and reduce technical debt, the following examples were removed the optaplanner-examples module:

We believe these examples were rarely used if ever, and they did not showcase any unique feature of OptaPlanner that would not be showcased already in any of the 16 remaining examples and many quickstarts.

No OptaPlanner feature was removed or deprecated in the process.

Fixed a bug that prevented using two or more chained planning variables, each defined on a different planning entity class.

While the OptaPlanner operator remains experimental, it has now become a part of the OptaPlanner distribution.

If you want to learn more about the operator, follow the Kubernetes demo.

With a new Constraint Streams API, it is now easy to define custom constraint justifications and indictments in your constraints:

Note the new methods: justifyWith(…​) and indictWith(…​). To find out more, see customizing justifications and indictments.

OpenJDK 19 was recently released and OptaPlanner is fully compatible with it.

We always test our releases against the long-term supported versions of the JDK, currently 11 and 17, as well as against the latest release. We encourage you to upgrade your JDK regularly to benefit from the enhancements that come with the new releases.

@ShadowVariable annotation is repeatable and allows to specify 1 listener per source variable.

@PiggybackShadowVariable is a specialized annotation to mark shadow variables that are updated by another shadow variable’s listener.

The @CustomShadowVariable has been deprecated.

Read more about custom shadow variables in the documentation.

OptaPlanner now adds a limited support for planning list variables that can hold multiple planning values. The planning list variable provides an alternative approach to modeling planning problems that were previously modeled using the chained planning variable.

Both the planning list variable and the chained planning variable should be used with problems where the goal is to distribute a number of workload elements among limited resources in a specific order. For example, in vehicle routing, vehicles represent the limited resource and customers represent the workload elements.

The chained planning variable defines a recursive data structure, in which customers form chains ending with vehicles. On the other hand, the planning list variable allows for a more intuitive model where each vehicle holds a list of customers it goes to. It is defined using the new @PlaningListVariable annotation.

See planning list variable.

The alternative constraint streams implementation Bavet is feature complete. You can now use it as an alternative to Drools (which is still the default).

Bavet will not be supported in Red Hat’s support offering. Drools intends to catch up performance wise.

The codebase for OptaWeb Employee Rostering demo application has been frozen and will no longer receive any updates.

We encourage users to check out the OptaPlanner Employee Rostering Quickstart for a simple and straight-forward way of integrating OptaPlanner in your application.

Support for Score DRL has been deprecated and users are encouraged to migrate to Constraint Streams at their earliest convenience. Read the migration guide from score DRL to Constraint Streams. Score DRL is not going away in OptaPlanner 8.

SolverManager.addProblemChange() returns CompletableFuture<Void>, which completes when a new best solution containing the problem change has been passed to a user-defined Consumer.

The SolverManager now accepts problem changes via the addProblemChange() method, allowing for real-time planning without much boilerplate code.

SolverFactory newly caches some internal data structures, leading to much faster Solver creation times. This is beneficial if you instantiate multiple Solver instances in quick succession.

The latest final OptaPlanner documentation is now available on a new documentation website built using Antora. The single-HTML and PDF documentation will continue to be published in the archive.

OptaPlanner now uses Micrometer to monitor key metrics such as active solver count, solve durations, and error count.

OptaPlanner is now fully compatible with the recently released Quarkus 2.0.

There is a new quarkus-call-center quickstart that shows real-time planning of incoming calls in a call center.

The Constraint Streams API received a major new functionality. You can now modify your streams using mapping functions.

We have made some tweaks under the hood so that your experience with the recently released OpenJDK 16 continues to be smooth.

You can now inject the Constraint Verifier in Quarkus and autowire the Constraint Verifier in Spring Boot, allowing you to test your constraint streams more easily.

OptaWeb Vehicle Routing and OptaWeb Employee Rostering have been migrated from Spring Boot to Quarkus.

Other noteworthy changes done during the migration to Quarkus:

We have added Gizmo generated domain accessors and solution cloners, which offer better performance than the reflection based domain accessors and solution cloners.

There is a new activemq-quarkus-school-timetabling quickstart that shows how to integrate ActiveMQ with OptaPlanner to horizontally scale when solving multiple data sets.

The default implementation of the Constraint Streams API has seen major performance improvements. Use cases with tri and quad streams may experience order of magnitude speedups. Use cases with grouping are likely to experience some speedups too, albeit comparatively smaller.

Kudos to the Drools team for helping make this possible!

The Constraint Streams API has been extended to allow using more than 2 collectors in a single grouping. The following is now possible:

The new OptaPlanner Quickstarts repository contains pretty web demos for several use cases. It also shows you how to integrate OptaPlanner with different technologies:

Clone the quickstarts repo now!

The OptaPlanner 8 API has been groomed to maximize compatibility with the latest OpenJDK and GraalVM releases and game-changing platforms such as Quarkus. Meanwhile, we still fully support OpenJDK 11 and platforms such as Spring Boot or plain Java.

For example, when running OptaPlanner in Java 11 or higher with a classpath, OptaPlanner no longer triggers WARNING: An illegal reflective access operation has occurred for XStream.

To validate XML configuration during development, add the new XML Schema Definition (XSD) on the solver or benchmark configuration:

This enables code completion for XML in most IDEs:

The OptaPlanner Quarkus extension is now stable and displays no warnings when compiling Java to a native executable.

The ScoreManager can now also explain why a solution has a certain score:

Additionally, use scoreExplanation.getConstraintMatchTotalMap() and scoreExplanation.getIndictmentMap() to extract the ConstraintMatchTotal<HardSoftScore> and Indictment<HardSoftScore> information without triggering a new score calculation.