Package org.optaplanner.core.api.solver

## Interface Solver<Solution_>

- Type Parameters:
    `Solution_` - the solution type, the class with the `PlanningSolution` annotation
  All Known Implementing Classes:
    `AbstractSolver`, `DefaultSolver`, `PartitionSolver`

      public interface Solver<Solution_>

  A Solver solves a planning problem and returns the best solution found. It's recommended to create a new Solver instance for each dataset.

  To create a Solver, use `SolverFactory.buildSolver()`. To solve a planning problem, call `solve(Object)`. To solve a planning problem without blocking the current thread, use `SolverManager` instead.

  These methods are not thread-safe and should be called from the same thread, except for the methods that are explicitly marked as thread-safe. Note that despite that `solve(Solution_)` is not thread-safe for clients of this class, that method is free to do multithreading inside itself.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addEventListener​(SolverEventListener<Solution_> eventListener)` |
    `boolean` | `addProblemFactChange​(ProblemFactChange<Solution_> problemFactChange)` | Schedules a `ProblemFactChange` to be processed.
    `boolean` | `addProblemFactChanges​(List<ProblemFactChange<Solution_>> problemFactChangeList)` | Schedules multiple `ProblemFactChange`s to be processed.
    `boolean` | `isEveryProblemFactChangeProcessed()` | Checks if all scheduled `ProblemFactChange`s have been processed.
    `boolean` | `isSolving()` | This method is thread-safe.
    `boolean` | `isTerminateEarly()` | This method is thread-safe.
    `void` | `removeEventListener​(SolverEventListener<Solution_> eventListener)` |
    `Solution_` | `solve​(Solution_ problem)` | Solves the planning problem and returns the best solution encountered (which might or might not be optimal, feasible or even initialized).
    `boolean` | `terminateEarly()` | Notifies the solver that it should stop at its earliest convenience.

- - ### Method Detail

    - #### solve

          Solution_ solve​(Solution_ problem)

      Solves the planning problem and returns the best solution encountered (which might or might not be optimal, feasible or even initialized).

      It can take seconds, minutes, even hours or days before this method returns, depending on the `Termination` configuration. To terminate a `Solver` early, call `terminateEarly()`.

      Parameters:
        `problem` - never null, a `PlanningSolution`, usually its planning variables are uninitialized
      Returns:
        never null, but it can return the original, uninitialized `PlanningSolution` with a null `Score`.
      See Also:
        `terminateEarly()`

    - #### terminateEarly

          boolean terminateEarly()

      Notifies the solver that it should stop at its earliest convenience. This method returns immediately, but it takes an undetermined time for the `solve(Solution_)` to actually return.

      If the solver is running in daemon mode, this is the only way to terminate it normally.

      This method is thread-safe. It can only be called from a different thread because the original thread is still calling `solve(Object)`.

      Returns:
        true if successful, false if was already terminating or terminated
      See Also:
        `isTerminateEarly()`, `Future.cancel(boolean)`

    - #### isSolving

          boolean isSolving()

      This method is thread-safe.
      Returns:
        true if the `solve(Solution_)` method is still running.

    - #### isTerminateEarly

          boolean isTerminateEarly()

      This method is thread-safe.
      Returns:
        true if terminateEarly has been called since the `Solver` started.
      See Also:
        `Future.isCancelled()`

    - #### addProblemFactChange

          boolean addProblemFactChange​(ProblemFactChange<Solution_> problemFactChange)

      Schedules a `ProblemFactChange` to be processed.

      As a side-effect, this restarts the `Solver`, effectively resetting all `Termination`s, but not `terminateEarly()`.

      This method is thread-safe. Follows specifications of `BlockingQueue.add(Object)` with by default a capacity of `Integer.MAX_VALUE`.

      Parameters:
        `problemFactChange` - never null
      Returns:
        true (as specified by `Collection.add(E)`)
      See Also:
        `addProblemFactChanges(List)`

    - #### addProblemFactChanges

          boolean addProblemFactChanges​(List<ProblemFactChange<Solution_>> problemFactChangeList)

      Schedules multiple `ProblemFactChange`s to be processed.

      As a side-effect, this restarts the `Solver`, effectively resetting all `Termination`s, but not `terminateEarly()`.

      This method is thread-safe. Follows specifications of `Collection.addAll(Collection)` with by default a capacity of `Integer.MAX_VALUE`.

      Parameters:
        `problemFactChangeList` - never null
      Returns:
        true (as specified by `Collection.add(E)`)
      See Also:
        `addProblemFactChange(ProblemFactChange)`

    - #### isEveryProblemFactChangeProcessed

          boolean isEveryProblemFactChangeProcessed()

      Checks if all scheduled `ProblemFactChange`s have been processed.

      This method is thread-safe.

      Returns:
        true if there are no `ProblemFactChange`s left to do

    - #### addEventListener

          void addEventListener​(SolverEventListener<Solution_> eventListener)

      Parameters:
        `eventListener` - never null

    - #### removeEventListener

          void removeEventListener​(SolverEventListener<Solution_> eventListener)

      Parameters:
        `eventListener` - never null