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

Interface NeighborhoodTestContext<Solution_>

Type Parameters:
Solution_ - the planning solution type
@NullMarked public interface NeighborhoodTestContext<Solution_>
Provides methods for enumerating moves for a given MoveProvider using a bound planning solution instance.

Created via NeighborhoodTester.using(Object), this context binds a specific solution instance to the evaluator and exposes extraction methods. Once any particular move was retrieved using methods such as getMovesAsStream(), it can optionally be executed using the MoveTestContext obtained via getMoveTestContext(). It is recommended to only execute moves temporarily, as that will have no lasting impact on the iterator or the bound solution instance.

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 Details

    • getMovesAsIterator

      default Iterator<Move<Solution_>> getMovesAsIterator()
      Returns an iterator over all moves provided by the given MoveProvider for the bound solution instance. The order of moves is not defined and is driven by the underlying MoveProvider, but it is guaranteed to be deterministic and reproducible across multiple invocations.
      Returns:
      an iterator over all moves

    • getMovesAsStream

      default Stream<Move<Solution_>> getMovesAsStream()
      As defined by getMovesAsIterator(), but returns a Stream of all the moves in the iterator. Parallel streams are not supported and the behavior of such stream is undefined.
      Returns:
      a stream of all moves

    • getMovesAsList

      default List<Move<Solution_>> getMovesAsList()
      As defined by getMovesAsIterator(), but returns a list of all the moves in the iterator. In case of a large expected number of moves, consider using getMovesAsIterator() instead to prevent excessive memory use.

    • getMovesAsIterator

      <Move_ extends Move<Solution_>> Iterator<Move_> getMovesAsIterator(Function<Move<Solution_>,Move_> moveCaster)
      As defined by getMovesAsIterator(), but the provided function allows casting each move to a more specific subtype, avoiding the need for external casting in the test. Only applicable if the underlying MoveProvider only provides moves of one particular subtype.
      Type Parameters:
      Move_ - expected move subtype
      Parameters:
      moveCaster - function to cast each move to the expected subtype
      Returns:
      an iterator over all moves

    • getMovesAsStream

      default <Move_ extends Move<Solution_>> Stream<Move_> getMovesAsStream(Function<Move<Solution_>,Move_> moveCaster)
      As defined by getMovesAsStream(), but the provided function allows casting each move to a more specific subtype, avoiding the need for external casting in the test. Only applicable if the underlying MoveProvider only provides moves of one particular subtype.
      Type Parameters:
      Move_ - expected move subtype
      Parameters:
      moveCaster - function to cast each move to the expected subtype
      Returns:
      a stream of all moves

    • getMovesAsList

      default <Move_ extends Move<Solution_>> List<Move_> getMovesAsList(Function<Move<Solution_>,Move_> moveCaster)
      As defined by getMovesAsList(), but the provided function allows casting each move to a more specific subtype, avoiding the need for external casting in the test. Only applicable if the underlying MoveProvider only provides moves of one particular subtype.
      Type Parameters:
      Move_ - expected move subtype
      Parameters:
      moveCaster - function to cast each move to the expected subtype
      Returns:
      a list of all moves

    • getMoveTestContext

      MoveTestContext<Solution_> getMoveTestContext()
      May be used to execute moves retrieved from this context on the bound solution instance. When executing moves permanently, any non-exhausted iterators obtained from this context become invalid and their further behavior is undefined; new moves should be obtained instead, for example by calling getMovesAsStream(). Temporary execution via MoveTestContext.executeTemporarily(Move, Consumer) does not have this limitation. Java streams and lists obtained from this context are not affected by permanent execution of moves either. Move lists are based on the solution as it was at the time when they were obtained. Streams of moves only materialize when their terminal operation is invoked, and they reflect the latest state of the solution at that time.
      Returns:
      the move run context for executing moves on the bound solution instance