Package org.eclipse.viatra.query.runtime.api

## Interface IQuerySpecification<Matcher extends ViatraQueryMatcher<? extends IPatternMatch>>

- All Superinterfaces:
    `PQueryHeader`
  All Known Implementing Classes:
    `BaseGeneratedEMFQuerySpecification`, `BaseGeneratedEMFQuerySpecificationWithGenericMatcher`, `BaseQuerySpecification`, `GenericQuerySpecification`, `GenericQuerySpecification`

      public interface IQuerySpecification<Matcher extends ViatraQueryMatcher<? extends IPatternMatch>>
      extends PQueryHeader

  API interface for a VIATRA query specification. Each query is associated with a pattern. Methods instantiate a matcher of the pattern with various parameters.

  As of 0.9.0, some internal details (mostly relevant for query evaluator backends) have been moved to `getInternalQueryRepresentation()`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PQuery` | `getInternalQueryRepresentation()` | Returns the definition of the query in a format intended for consumption by the query evaluator.
    `Matcher` | `getMatcher​(ViatraQueryEngine engine)` | Initializes the pattern matcher within an existing `ViatraQueryEngine`.
    `default java.util.List<PProblem>` | `getPProblems()` | Returns a list describing the problems that were found in this query.
    `java.lang.Class<? extends QueryScope>` | `getPreferredScopeClass()` | The query is formulated over this kind of modeling platform.
    `default PQuery.PQueryStatus` | `getStatus()` | Returns the initialization status of the query specification
    `Matcher` | `instantiate()` | Creates a new uninitialized matcher, which is not functional until an engine initializes it.
    `IPatternMatch` | `newEmptyMatch()` | Returns an empty, mutable Match compatible with matchers of this query.
    `IPatternMatch` | `newMatch​(java.lang.Object... parameters)` | Returns a new (partial) Match object compatible with matchers of this query.

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.psystem.queries.PQueryHeader

      `getAllAnnotations, getAnnotationsByName, getFirstAnnotationByName, getFullyQualifiedName, getParameter, getParameterNames, getParameters, getPositionOfParameter, getSimpleName, getVisibility`

- - ### Method Detail

    - #### getMatcher

          Matcher getMatcher​(ViatraQueryEngine engine)

      Initializes the pattern matcher within an existing `ViatraQueryEngine`. If the pattern matcher is already constructed in the engine, only a lightweight reference is created.

      The match set will be incrementally refreshed upon updates.

      Parameters:
        `engine` - the existing VIATRA Query engine in which this matcher will be created.
      Throws:
        `ViatraQueryRuntimeException` - if an error occurs during pattern matcher creation

    - #### newEmptyMatch

          IPatternMatch newEmptyMatch()

      Returns an empty, mutable Match compatible with matchers of this query. Fields of the mutable match can be filled to create a partial match, usable as matcher input. This can be used to call the matcher with a partial match even if the specific class of the matcher or the match is unknown.
      Returns:
        the empty match

    - #### newMatch

          IPatternMatch newMatch​(java.lang.Object... parameters)

      Returns a new (partial) Match object compatible with matchers of this query. This can be used e.g. to call the matcher with a partial match.

      The returned match will be immutable. Use `newEmptyMatch()` to obtain a mutable match object.

      Parameters:
        `parameters` - the fixed value of pattern parameters, or null if not bound.
      Returns:
        the (partial) match object.

    - #### getPreferredScopeClass

          java.lang.Class<? extends QueryScope> getPreferredScopeClass()

      The query is formulated over this kind of modeling platform. E.g. for queries over EMF models, the `EMFScope` class is returned.

    - #### getInternalQueryRepresentation

          PQuery getInternalQueryRepresentation()

      Returns the definition of the query in a format intended for consumption by the query evaluator.
      Returns:
        the internal representation of the query.

    - #### getStatus

          default PQuery.PQueryStatus getStatus()

      Returns the initialization status of the query specification
      Since:
        2.9
      See Also:
        `PQuery.getStatus()`

    - #### getPProblems

          default java.util.List<PProblem> getPProblems()

      Returns a list describing the problems that were found in this query.
      Returns:
        a non-null, but possibly empty list of problems
      Since:
        2.9
      See Also:
        `PQuery.getPProblems()`

    - #### instantiate

          Matcher instantiate()

      Creates a new uninitialized matcher, which is not functional until an engine initializes it. Clients should not call this method, it is used by the `ViatraQueryEngine` instance to instantiate matchers.
      Throws:
        `ViatraQueryRuntimeException`
      Since:
        1.4
      No Reference:
        This method is not intended to be referenced by clients.