Package ai.timefold.solver.core.api.solver

Interface SolverJobBuilder<Solution_,ProblemId_>

Type Parameters:
Solution_ - the solution type, the class with the PlanningSolution annotation
ProblemId_ - the ID type of submitted problem, such as Long or UUID.
All Known Implementing Classes:
DefaultSolverJobBuilder
public interface SolverJobBuilder<Solution_,ProblemId_>
Provides a fluent contract that allows customization and submission of planning problems to solve.

A SolverManager can solve multiple planning problems and can be used across different threads.

Hence, it is possible to have multiple distinct build configurations that are scheduled to run by the SolverManager instance.

To solve a planning problem, set the problem configuration: withProblemId(Object), withProblemFinder(Function) and withProblem(Object).

Then solve it by calling run().

  • Method Details

    • withProblemId

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withProblemId(@NonNull ProblemId_ problemId)
      Sets the problem id.
      Parameters:
      problemId - a ID for each planning problem. This must be unique.
      Returns:
      this

    • withProblem

      default @NonNull SolverJobBuilder<Solution_,ProblemId_> withProblem(@NonNull Solution_ problem)
      Sets the problem definition.
      Parameters:
      problem - a PlanningSolution usually with uninitialized planning variables
      Returns:
      this

    • withProblemFinder

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withProblemFinder(@NonNull Function<? super ProblemId_,? extends Solution_> problemFinder)
      Sets the mapping function to the problem definition.
      Parameters:
      problemFinder - a function that returns a PlanningSolution, usually with uninitialized planning variables
      Returns:
      this

    • withBestSolutionConsumer

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withBestSolutionConsumer(@NonNull Consumer<? super Solution_> bestSolutionConsumer)
      Sets the best solution consumer, which may be called multiple times during the solving process.

      Don't apply any changes to the solution instance while the solver runs. The solver's best solution instance is the same as the one in the event, and any modifications may lead to solver corruption due to its internal reuse.

      Parameters:
      bestSolutionConsumer - called multiple times for each new best solution on a consumer thread
      Returns:
      this

    • withFinalBestSolutionConsumer

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withFinalBestSolutionConsumer(@NonNull Consumer<? super Solution_> finalBestSolutionConsumer)
      Sets the final best solution consumer, which is called at the end of the solving process and returns the final best solution.
      Parameters:
      finalBestSolutionConsumer - called only once at the end of the solving process on a consumer thread
      Returns:
      this

    • withFirstInitializedSolutionConsumer

      @Deprecated(forRemoval=true, since="1.19.0") default @NonNull SolverJobBuilder<Solution_,ProblemId_> withFirstInitializedSolutionConsumer(@NonNull Consumer<? super Solution_> firstInitializedSolutionConsumer)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use withFirstInitializedSolutionConsumer(FirstInitializedSolutionConsumer) instead.
      As defined by #withFirstInitializedSolutionConsumer(FirstInitializedSolutionConsumer).

    • withFirstInitializedSolutionConsumer

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withFirstInitializedSolutionConsumer(@NonNull SolverJobBuilder.FirstInitializedSolutionConsumer<? super Solution_> firstInitializedSolutionConsumer)
      Sets the consumer of the first initialized solution, the beginning of the actual optimization process. First initialized solution is the solution at the end of the last phase that immediately precedes the first local search phase.
      Parameters:
      firstInitializedSolutionConsumer - called only once before starting the first Local Search phase
      Returns:
      this

    • withSolverJobStartedConsumer

      SolverJobBuilder<Solution_,ProblemId_> withSolverJobStartedConsumer(Consumer<? super Solution_> solverJobStartedConsumer)
      Sets the consumer for when the solver starts its solving process.
      Parameters:
      solverJobStartedConsumer - never null, called only once when the solver is starting the solving process
      Returns:
      this, never null

    • withExceptionHandler

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withExceptionHandler(@NonNull BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)
      Sets the custom exception handler.
      Parameters:
      exceptionHandler - called if an exception or error occurs. If null it defaults to logging the exception as an error.
      Returns:
      this

    • withConfigOverride

      @NonNull SolverJobBuilder<Solution_,ProblemId_> withConfigOverride(@NonNull SolverConfigOverride<Solution_> solverConfigOverride)
      Sets the solver config override.
      Parameters:
      solverConfigOverride - allows overriding the default behavior of Solver
      Returns:
      this

    • run

      @NonNull SolverJob<Solution_,ProblemId_> run()
      Submits a planning problem to solve and returns immediately. The planning problem is solved on a solver Thread, as soon as one is available.