org.eclipse.viatra.query.runtime.localsearch.matcher

## Interface ILocalSearchAdapter

- All Known Implementing Classes:
    ExecutionLoggerAdapter, LocalSearchProfilerAdapter

      public interface ILocalSearchAdapter

  A local search adapter allows external code to follow the internal executions of the local search matcher. Possible implementations of the interface include profilers and debuggers.

  EXPERIMENTAL. A few shortcomings have been found for this interface late during the development lifecycle of version 2.0 whose solution might need breaking possible future implementors. Because of this, right now it is not recommended to provide implementations outside of VIATRA. If necessary, have a look at the built-in adapters that should fulfill most cases in the meantime. See bugs https://bugs.eclipse.org/bugs/show_bug.cgi?id=535101 and https://bugs.eclipse.org/bugs/show_bug.cgi?id=535102 for details.

  See Also:
    `ExecutionLoggerAdapter`, `LocalSearchProfilerAdapter`

- - ### Method Summary

    All Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default void` | `adapterRegistered(ILocalSearchAdaptable adaptable)`
    `default void` | `adapterUnregistered(ILocalSearchAdaptable adaptable)`
    `default void` | `duplicateMatchFound(MatchingFrame frame)` Callback that is used to indicate that the previously reported match has been found as a duplicate, thus will be ignored from the match results.
    `default void` | `executorInitializing(SearchPlan searchPlan, MatchingFrame frame)` Callback method to indicate that a search plan is initialized in an executor with the given frame and starting operation
    `default void` | `matchFound(SearchPlan plan, MatchingFrame frame)` Callback that is used to indicate that a match has been found
    `default void` | `noMoreMatchesAvailable(LocalSearchMatcher lsMatcher)` Callback method to indicate the end of a matching process
    `default void` | `operationExecuted(SearchPlan plan, ISearchOperation operation, MatchingFrame frame, boolean isSuccessful)` Callback method to indicate that an operation is executed
    `default void` | `operationSelected(SearchPlan plan, ISearchOperation operation, MatchingFrame frame, boolean isBacktrack)` Callback method to indicate the selection of an operation to execute
    `default void` | `patternMatchingStarted(LocalSearchMatcher lsMatcher)` Callback method to indicate the start of a matching process
    `default void` | `planChanged(java.util.Optional<SearchPlan> oldPlan, java.util.Optional<SearchPlan> newPlan)` Callback method to indicate switching to a new plan during the execution of a pattern matching

- - ### Method Detail

    - #### adapterRegistered

          default void adapterRegistered(ILocalSearchAdaptable adaptable)

      Since:
        1.2

    - #### adapterUnregistered

          default void adapterUnregistered(ILocalSearchAdaptable adaptable)

      Since:
        1.2

    - #### patternMatchingStarted

          default void patternMatchingStarted(LocalSearchMatcher lsMatcher)

      Callback method to indicate the start of a matching process
      Parameters:
        `lsMatcher` - the local search matcher that starts the matching

    - #### noMoreMatchesAvailable

          default void noMoreMatchesAvailable(LocalSearchMatcher lsMatcher)

      Callback method to indicate the end of a matching process WARNING: It is not guaranteed that this method will be called; it is possible that a match process will end after a match is found and no other matches are accessed.
      Parameters:
        `lsMatcher` - the local search matcher that finished
      Since:
        2.0

    - #### planChanged

          default void planChanged(java.util.Optional<SearchPlan> oldPlan,
                                   java.util.Optional<SearchPlan> newPlan)

      Callback method to indicate switching to a new plan during the execution of a pattern matching
      Parameters:
        `oldPlan` - the plan that is finished. Value is null when the first plan is starting.
        `newPlan` - the plan that will begin execution
      Since:
        2.0

    - #### operationSelected

          default void operationSelected(SearchPlan plan,
                                         ISearchOperation operation,
                                         MatchingFrame frame,
                                         boolean isBacktrack)

      Callback method to indicate the selection of an operation to execute
      Parameters:
        `plan` - the current plan executor
        `frame` - the current matching frame
        `isBacktrack` - if true, the selected operation was reached via backtracking
      Since:
        2.0

    - #### operationExecuted

          default void operationExecuted(SearchPlan plan,
                                         ISearchOperation operation,
                                         MatchingFrame frame,
                                         boolean isSuccessful)

      Callback method to indicate that an operation is executed
      Parameters:
        `plan` - the current plan
        `frame` - the current matching frame
        `isSuccessful` - if true, the operation executed successfully, or false if the execution failed and backtracking will happen
      Since:
        2.0

    - #### matchFound

          default void matchFound(SearchPlan plan,
                                  MatchingFrame frame)

      Callback that is used to indicate that a match has been found
      Parameters:
        `plan` - the search plan executor that found the match
        `frame` - the frame that holds the substitutions of the variables that match
      Since:
        2.0

    - #### duplicateMatchFound

          default void duplicateMatchFound(MatchingFrame frame)

      Callback that is used to indicate that the previously reported match has been found as a duplicate, thus will be ignored from the match results.
      Parameters:
        `plan` - the search plan executor that found the match
        `frame` - the frame that holds the substitutions of the variables that match
      Since:
        2.0

    - #### executorInitializing

          default void executorInitializing(SearchPlan searchPlan,
                                            MatchingFrame frame)

      Callback method to indicate that a search plan is initialized in an executor with the given frame and starting operation
      Parameters:
        `searchPlan` -
        `frame` -
      Since:
        2.0