Package ai.timefold.solver.core.preview.api.move

Interface MoveTestContext<Solution_>

Type Parameters:

Solution_ - the planning solution type

All Known Implementing Classes:

DefaultMoveTestContext

@NullMarked
public interface MoveTestContext<Solution_>

Provides methods for executing moves on a bound planning solution instance.

Created via MoveTester.using(Object), this context binds a specific solution instance to the runner and exposes execution methods.

This class is NOT thread-safe.

This package and all of its contents are part of the Neighborhoods API, which is under development and is only offered as a preview feature. There are no guarantees for backward compatibility; any method or field may change or be removed without prior notice, although we will strive to avoid this as much as possible.

Method Summary

Modifier and Type	Method	Description
void	execute(Move<Solution_> move)	Executes the given move permanently on the bound solution.
void	executeTemporarily(Move<Solution_> move, Consumer<SolutionView<Solution_>> callback)	Executes the given move temporarily on the bound solution, runs assertions, then automatically undoes the move.

Method Details

execute

void execute(Move<Solution_> move)

Executes the given move permanently on the bound solution.

Changes made by the move persist after this method returns. Shadow variables are automatically updated via the solver's existing mechanisms.

If the move throws an exception, the exception propagates to the caller and the solution state may be only partially modified. In this case, the caller must discard the solution instance and get a new instance of this class via MoveTester.using(Object).

Parameters:

move - the move to execute

executeTemporarily

void executeTemporarily(Move<Solution_> move,
 Consumer<SolutionView<Solution_>> callback)

Executes the given move temporarily on the bound solution, runs assertions, then automatically undoes the move.

The move is executed, modifying the solution state. The assertions callback is then invoked, allowing the caller to verify the modified state. Finally, the move is automatically undone, restoring the solution to its exact pre-execution state.

Important constraints:

• Nesting executeTemporarily() calls is not supported and results in undefined behavior
• Do not modify the solution state directly within the assertions callback; doing so results in undefined behavior with unpredictable undo results
• If an exception occurs during move execution, the callback, or undo operation, the solution state is undefined and no restoration is attempted. The caller must discard the solution instance and get a new instance of this class via MoveTester.using(Object).

Parameters:

move - the move to execute temporarily

callback - to verify the modified solution state before it is undone; receives a SolutionView for read-only access