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
    Modifier and Type | Method and 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`.
    `java.lang.Class<? extends QueryScope>` | `getPreferredScopeClass()` The query is formulated over this kind of modeling platform.
    `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.

    - #### 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.