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

## Class BasePQuery

- java.lang.Object
- - org.eclipse.viatra.query.runtime.matchers.psystem.queries.BasePQuery

- All Implemented Interfaces:
    PTraceable, PQuery, PQueryHeader
  Direct Known Subclasses:
    BaseGeneratedEMFPQuery, GenericEMFPatternPQuery, GenericSingleConstraintPQuery

      public abstract class BasePQuery
      extends java.lang.Object
      implements PQuery

  Default implementation of PQuery.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.eclipse.viatra.query.runtime.matchers.psystem.queries.PQuery

      `PQuery.PQueryStatus`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.List<PProblem>` | `pProblems`
    `protected PQuery.PQueryStatus` | `status`
    `protected PVisibility` | `visibility`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BasePQuery(PVisibility visibility)`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addAnnotation(PAnnotation annotation)`
    `protected void` | `addError(PProblem problem)`
    `void` | `checkMutability()` Before a modification operation is executed, a mutability check is performed (via the `PQuery.getStatus()` implementation, and in case of problems an `IllegalStateException` is thrown.
    `protected abstract java.util.Set<PBody>` | `doGetContainedBodies()` Creates and returns the bodies of the query.
    `void` | `ensureInitialized()` If the query definition is uninitialized, initializes it.
    `java.util.List<PAnnotation>` | `getAllAnnotations()` Returns the list of annotations specified for this query
    `java.util.Set<PQuery>` | `getAllReferredQueries()` Returns all queries required to evaluate this query (transitively).
    `java.util.List<PAnnotation>` | `getAnnotationsByName(java.lang.String annotationName)` Returns the list of annotations with a specified name
    `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.Optional<PAnnotation>` | `getFirstAnnotationByName(java.lang.String annotationName)` Returns the first annotation with a specified name
    `java.util.List<java.lang.String>` | `getParameterNames()` Return the list of parameter names
    `java.lang.Integer` | `getPositionOfParameter(java.lang.String parameterName)` Returns the index of a named parameter
    `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.
    `PVisibility` | `getVisibility()` Returns the visibility information about the query.
    `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.
    `protected void` | `setBodies(java.util.Set<PBody> bodies)`
    `void` | `setEvaluationHints(QueryEvaluationHint hints)`
    `protected void` | `setStatus(PQuery.PQueryStatus newStatus)`
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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

      `getFullyQualifiedName, getParameter, getParameters, getSimpleName`

- - ### Field Detail

    - #### status

          protected PQuery.PQueryStatus status

    - #### visibility

          protected final PVisibility visibility

      Since:
        2.0

    - #### pProblems

          protected java.util.List<PProblem> pProblems

  - ### Constructor Detail

    - #### BasePQuery

          public BasePQuery(PVisibility visibility)

      Since:
        2.0

  - ### Method Detail

    - #### getPositionOfParameter

          public java.lang.Integer getPositionOfParameter(java.lang.String parameterName)

      Description copied from interface: `PQueryHeader`
      Returns the index of a named parameter
      Specified by:
        `getPositionOfParameter` in interface `PQueryHeader`
      Returns:
        the index, or null of no such parameter is available

    - #### setStatus

          protected void setStatus(PQuery.PQueryStatus newStatus)

    - #### addError

          protected void addError(PProblem problem)

    - #### getStatus

          public PQuery.PQueryStatus getStatus()

      Description copied from interface: `PQuery`
      Returns the initialization status of the definition
      Specified by:
        `getStatus` in interface `PQuery`

    - #### getPProblems

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

      Description copied from interface: `PQuery`
      Returns a list describing the problems that were found in this query.

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

      Specified by:
        `getPProblems` in interface `PQuery`
      Returns:
        a non-null, but possibly empty list of problems

    - #### isMutable

          public boolean isMutable()

      Description copied from interface: `PQuery`
      An option to check mutability of the query. It can be used to avoid getting an `IllegalStateException` by the execution of `PQuery.checkMutability()`.
      Specified by:
        `isMutable` in interface `PQuery`
      Returns:
        true if the query specification is still editable

    - #### checkMutability

          public void checkMutability()

      Description copied from interface: `PQuery`
      Before a modification operation is executed, a mutability check is performed (via the `PQuery.getStatus()` implementation, and in case of problems an `IllegalStateException` is thrown.
      Specified by:
        `checkMutability` in interface `PQuery`

    - #### setEvaluationHints

          public void setEvaluationHints(QueryEvaluationHint hints)

      Since:
        1.5

    - #### getEvaluationHints

          public QueryEvaluationHint getEvaluationHints()

      Description copied from interface: `PQuery`
      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.

      Specified by:
        `getEvaluationHints` in interface `PQuery`

    - #### addAnnotation

          protected void addAnnotation(PAnnotation annotation)

    - #### getAllAnnotations

          public java.util.List<PAnnotation> getAllAnnotations()

      Description copied from interface: `PQueryHeader`
      Returns the list of annotations specified for this query
      Specified by:
        `getAllAnnotations` in interface `PQueryHeader`
      Returns:
        a non-null, but possibly empty list of annotations

    - #### getAnnotationsByName

          public java.util.List<PAnnotation> getAnnotationsByName(java.lang.String annotationName)

      Description copied from interface: `PQueryHeader`
      Returns the list of annotations with a specified name
      Specified by:
        `getAnnotationsByName` in interface `PQueryHeader`
      Returns:
        a non-null, but possibly empty list of annotations

    - #### getFirstAnnotationByName

          public java.util.Optional<PAnnotation> getFirstAnnotationByName(java.lang.String annotationName)

      Description copied from interface: `PQueryHeader`
      Returns the first annotation with a specified name
      Specified by:
        `getFirstAnnotationByName` in interface `PQueryHeader`

    - #### getParameterNames

          public java.util.List<java.lang.String> getParameterNames()

      Description copied from interface: `PQueryHeader`
      Return the list of parameter names
      Specified by:
        `getParameterNames` in interface `PQueryHeader`
      Returns:
        a non-null, but possibly empty list of parameter names

    - #### getDirectReferredQueries

          public java.util.Set<PQuery> getDirectReferredQueries()

      Description copied from interface: `PQuery`
      Returns all queries directly referred in the constraints. They are all required to evaluate this query
      Specified by:
        `getDirectReferredQueries` in interface `PQuery`
      Returns:
        a non-null, but possibly empty list of query definitions

    - #### getAllReferredQueries

          public java.util.Set<PQuery> getAllReferredQueries()

      Description copied from interface: `PQuery`
      Returns all queries required to evaluate this query (transitively).
      Specified by:
        `getAllReferredQueries` in interface `PQuery`
      Returns:
        a non-null, but possibly empty list of query definitions

    - #### publishedAs

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

      Description copied from interface: `PQuery`
      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.

      Specified by:
        `publishedAs` in interface `PQuery`
      Returns:
        a non-null, but possibly empty list of query specification objects;

    - #### getTypeGuarantees

          public java.util.Set<TypeJudgement> getTypeGuarantees()

      Description copied from interface: `PQuery`
      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.

      Specified by:
        `getTypeGuarantees` in interface `PQuery`
      Returns:
        a non-null set of type judgements that the query guarantees for its matches

    - #### getDisjunctBodies

          public PDisjunction getDisjunctBodies()

      Description copied from interface: `PQuery`
      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.
      Specified by:
        `getDisjunctBodies` in interface `PQuery`

    - #### ensureInitialized

          public final void ensureInitialized()

      Description copied from interface: `PQuery`
      If the query definition is uninitialized, initializes it.
      Specified by:
        `ensureInitialized` in interface `PQuery`

    - #### setBodies

          protected final void setBodies(java.util.Set<PBody> bodies)

    - #### doGetContainedBodies

          protected abstract java.util.Set<PBody> doGetContainedBodies()

      Creates and returns the bodies of the query. If recalled again, a new instance is created.
      Returns:
      Throws:
        `ViatraQueryRuntimeException`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getVisibility

          public PVisibility getVisibility()

      Description copied from interface: `PQueryHeader`
      Returns the visibility information about the query.
      Specified by:
        `getVisibility` in interface `PQueryHeader`
      Since:
        2.0