org.eclipse.viatra.query.runtime.matchers.psystem.queries

## Interface PQuery

- All Superinterfaces:
    PQueryHeader, PTraceable
  All Known Subinterfaces:
    InitializablePQuery
  All Known Implementing Classes:
    BaseGeneratedEMFPQuery, BasePQuery, GenericEMFPatternPQuery, GenericReferencedPQuery, GenericTracedPQuery

      public interface PQuery
      extends PQueryHeader, PTraceable

  Internal representation of a query / graph pattern (using a constraint system formalism), to be interpreted by a query evaluator (`IQueryBackend`). End-users of VIATRA Query should access a query as an IQuerySpecification instead.

  PQuerys are definitions of queries usable inside pattern descriptions. Such description always has (a non-null) name. The query itself is defined as a (non-empty) set of `PBody` instances, the result is the disjunction of the single `PBody` instances.

  A PQuery might be constructed from erroneous patterns or might be uninitialized - this is represented by its status.

  Since:
    0.8.0
  No Implement:
    This interface is not intended to be implemented by clients. Use `BasePQuery` as a base class instead.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `PQuery.PQueryStatus`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkMutability()` Before a modification operation is executed, a mutability check is performed (via the `getStatus()` implementation, and in case of problems an `IllegalStateException` is thrown.
    `void` | `ensureInitialized()` If the query definition is uninitialized, initializes it.
    `java.util.Set<PQuery>` | `getAllReferredQueries()` Returns all queries required to evaluate this query (transitively).
    `java.util.Set<PQuery>` | `getDirectReferredQueries()` Returns all queries directly referred in the constraints.
    `PDisjunction` | `getDisjunctBodies()` Returns all bodies associated with the query in their canonical form.
    `QueryEvaluationHint` | `getEvaluationHints()` Optional hints regarding the query evaluation strategy, to be interpreted by the query engine.
    `java.util.List<PProblem>` | `getPProblems()` Returns a list describing the problems that were found in this query.
    `PQuery.PQueryStatus` | `getStatus()` Returns the initialization status of the definition
    `java.util.Set<TypeJudgement>` | `getTypeGuarantees()` Type information, expressed on query parameters, that all matches of the query are guaranteed to respect.
    `boolean` | `isMutable()` An option to check mutability of the query.
    `java.util.List<java.lang.Object>` | `publishedAs()` Returns the end-user query specification API objects that wrap this query.

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

      `getAllAnnotations, getAnnotationsByName, getFirstAnnotationByName, getFullyQualifiedName, getParameterNames, getParameters, getPositionOfParameter`

- - ### Method Detail

    - #### getDisjunctBodies

          PDisjunction getDisjunctBodies()

      Returns all bodies associated with the query in their canonical form. If called multiple times, the same set with the same contents will be returned.

    - #### getDirectReferredQueries

          java.util.Set<PQuery> getDirectReferredQueries()

      Returns all queries directly referred in the constraints. They are all required to evaluate this query
      Returns:
        a non-null, but possibly empty list of query definitions

    - #### getAllReferredQueries

          java.util.Set<PQuery> getAllReferredQueries()

      Returns all queries required to evaluate this query (transitively).
      Returns:
        a non-null, but possibly empty list of query definitions

    - #### getStatus

          PQuery.PQueryStatus getStatus()

      Returns the initialization status of the definition

    - #### getPProblems

          java.util.List<PProblem> getPProblems()

      Returns a list describing the problems that were found in this query.

      TODO: formulate invariant connecting `getPProblems()` and `getStatus()`.

      Returns:
        a non-null, but possibly empty list of problems

    - #### checkMutability

          void checkMutability()
                        throws java.lang.IllegalStateException

      Before a modification operation is executed, a mutability check is performed (via the `getStatus()` implementation, and in case of problems an `IllegalStateException` is thrown.
      Throws:
        `java.lang.IllegalStateException`

    - #### isMutable

          boolean isMutable()

      An option to check mutability of the query. It can be used to avoid getting an `IllegalStateException` by the execution of `checkMutability()`.
      Returns:
        true if the query specification is still editable

    - #### getEvaluationHints

          QueryEvaluationHint getEvaluationHints()

      Optional hints regarding the query evaluation strategy, to be interpreted by the query engine.

      To ensure the possibility of external overrides, the evaluation engine should not directly consult this field, but use an `IQueryBackendHintProvider` instead.

    - #### getTypeGuarantees

          java.util.Set<TypeJudgement> getTypeGuarantees()

      Type information, expressed on query parameters, that all matches of the query are guaranteed to respect.

      At the very minimum, this should include the declared types of the parameters.

      The type judgement tuples shall contain the parameter index, NOT the `PParameter` object.

      Returns:
        a non-null set of type judgements that the query guarantees for its matches

    - #### ensureInitialized

          void ensureInitialized()
                          throws QueryInitializationException

      If the query definition is uninitialized, initializes it.
      Throws:
        `QueryInitializationException` - if initialization of query specification fails

    - #### publishedAs

          java.util.List<java.lang.Object> publishedAs()

      Returns the end-user query specification API objects that wrap this query.

      Intended for traceability and debug purposes, not part of normal operation. Returned list is intended to be appended during query specification construction time.

      Returns:
        a non-null, but possibly empty list of query specification objects;