org.eclipse.incquery.runtime.api

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

- All Superinterfaces:
    PQueryHeader
  All Known Implementing Classes:
    ActionContextQuerySpecification, ActionInputQuerySpecification, ActionOutputQuerySpecification, ActivityEdgeInGroupQuerySpecification, ActivityGroupContainedEdgeQuerySpecification, ActivityGroupContainedNodeQuerySpecification, ActivityGroupInActivityQuerySpecification, ActivityGroupQuerySpecification, ActivityGroupSubgroupQuerySpecification, ActivityGroupSuperGroupQuerySpecification, ActivityNodeActivityQuerySpecification, ActivityNodeInGroupQuerySpecification, ActivityNodeQuerySpecification, AssociationEndTypeQuerySpecification, BaseGeneratedEMFQuerySpecification, BaseQuerySpecification, BehaviorContextQuerySpecification, ChildrenQuerySpecification, ClassExtensionQuerySpecification, ClassifierAllParentsQuerySpecification, ClassifierAttributeQuerySpecification, ClassifierFeatureQuerySpecification, ClassifierGeneralQuerySpecification, ClassifierParentsQuerySpecification, ClassSuperClassQuerySpecification, ConnectableElementEndQuerySpecification, ConnectorKindQuerySpecification, DeploymentTargetDeployedElementQuerySpecification, DirectedRelationshipSourceQuerySpecification, DirectedRelationshipTargetQuerySpecification, ElementOwnedElementQuerySpecification, ElementOwnerQuerySpecification, EmptyTraceQuerySpecification, EncapsulatedClassifierOwnedPortQuerySpecification, ExtensionMetaclassEndQuerySpecification, ExtensionMetaclassQuerySpecification, FeatureFeaturingClassifierQuerySpecification, GenericQuerySpecification, GenericQuerySpecification, GenericReferencedQuerySpecification, GenericTracedQuerySpecification, MessageMessageKindQuerySpecification, NamedElementClientDependencyQuerySpecification, NamedElementNamespaceQuerySpecification, NamedElementQualifiedNameQuerySpecification, NamespaceImportedMemberQuerySpecification, NamespaceMemberQuerySpecification, NamespaceOwnedMemberQuerySpecification, OpaqueExpressionResultQuerySpecification, OperationReturnResultQuerySpecification, PackageNestedPackageQuerySpecification, PackageNestingPackageQuerySpecification, PackageOwnedStereotypeQuerySpecification, PackageOwnedTypeQuerySpecification, PackageVisibleMemberQuerySpecification, Param2containmentQuerySpecification, Param2edgeQuerySpecification, Param2itemQuerySpecification, Param2targetQuerySpecification, PropertyIsCompositeQuerySpecification, ProtocolTransitionReferredQuerySpecification, RedefinableElementRedefinedElementQuerySpecification, RedefinableElementRedefinitionContextQuerySpecification, RedefinableTemplateSignatureInheritedParameterQuerySpecification, RelationshipRelatedElementQuerySpecification, StateIsCompositeQuerySpecification, StateIsOrthogonalQuerySpecification, StructuredClassifierPartQuerySpecification, StructuredClassifierRoleQuerySpecification, Trace2objectQuerySpecification, Trace2paramQuerySpecification, Trace2targetQuerySpecification, TraceQuerySpecification, TypePackageQuerySpecification, VertexIncomingQuerySpecification, VertexOutgoingQuerySpecification

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

  API interface for an IncQuery 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()`.

  Author:
    Bergmann Gábor

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated 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(IncQueryEngine engine)` Initializes the pattern matcher within an existing `IncQueryEngine`.
    `Matcher` | `getMatcher(org.eclipse.emf.common.notify.Notifier emfRoot)` Deprecated. use `getMatcher(IncQueryEngine)` instead, e.g. in conjunction with `IncQueryEngine.on(Notifier)`.
    `java.lang.Class<? extends IncQueryScope>` | `getPreferredScopeClass()` The query is formulated over this kind of modeling platform.
    `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.incquery.runtime.matchers.psystem.queries.PQueryHeader

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

- - ### Method Detail

    - #### getMatcher

          @Deprecated
          Matcher getMatcher(org.eclipse.emf.common.notify.Notifier emfRoot)
                                  throws IncQueryException

      Deprecated. use `getMatcher(IncQueryEngine)` instead, e.g. in conjunction with `IncQueryEngine.on(Notifier)`.
      Initializes the pattern matcher over a given EMF model root (recommended: Resource or ResourceSet). If a pattern matcher is already constructed with the same root, only a lightweight reference is created.

      The scope of pattern matching will be the given EMF model root and below (see FAQ for more precise definition).

      The match set will be incrementally refreshed upon updates from this scope.

      The matcher will be created within the managed `IncQueryEngine` belonging to the EMF model root, so multiple matchers will reuse the same engine and benefit from increased performance and reduced memory footprint.

      Parameters:
        `emfRoot` - the root of the EMF tree where the pattern matcher will operate. Recommended: Resource or ResourceSet.
      Throws:
        `IncQueryException` - if an error occurs during pattern matcher creation

    - #### getMatcher

          Matcher getMatcher(IncQueryEngine engine)
                      throws IncQueryException

      Initializes the pattern matcher within an existing `IncQueryEngine`. 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 IncQuery engine in which this matcher will be created.
      Throws:
        `IncQueryException` - 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 IncQueryScope> 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.