org.eclipse.incquery.runtime.api

## Class IncQueryEngine

- java.lang.Object
- - org.eclipse.incquery.runtime.api.IncQueryEngine

- Direct Known Subclasses:
    AdvancedIncQueryEngine

      public abstract class IncQueryEngine
      extends java.lang.Object

  An IncQuery incremental evaluation engine, attached to a model such as an EMF resource. The engine hosts pattern matchers, and will listen on model update notifications stemming from the given model in order to maintain live results.

  By default, IncQueryEngines do not need to be separately disposed; they will be garbage collected along with the model. Advanced users: see `AdvancedIncQueryEngine` if you want fine control over the lifecycle of an engine.

  Pattern matchers within this engine may be instantiated in the following ways:

  - Recommended: instantiate the specific matcher class generated for the pattern by e.g. MyPatternMatcher.on(engine).
  - Use `getMatcher(IQuerySpecification)` if the pattern-specific generated matcher API is not available.
  - Advanced: use the query specification associated with the generated matcher class to achieve the same.
  Additionally, a group of patterns (see `IQueryGroup`) can be initialized together before usage; this may improve the performance of pattern matcher construction by trying to gather all necessary information from the model in one go. Note that no such improvement is to be expected if the engine is specifically constructed in wildcard mode, an option available in some scope implementations (see `EMFScope.EMFScope(Notifier, BaseIndexOptions)` and `BaseIndexOptions.withWildcardMode(boolean)`).
  Author:
    Bergmann Gábor

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IncQueryEngine()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract IBaseIndex` | `getBaseIndex()` Provides access to the internal base index component of the engine, responsible for keeping track of basic contents of the model.
    `abstract java.util.Set<? extends IncQueryMatcher<? extends IPatternMatch>>` | `getCurrentMatchers()` Access a copy of available `IncQueryMatcher` pattern matchers.
    `abstract org.eclipse.emf.common.notify.Notifier` | `getEMFRoot()` Deprecated. only valid for EMF scopes; use `getScope()` to get scope information in the general case.
    `abstract <Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher` | `getExistingMatcher(IQuerySpecification<Matcher> querySpecification)` Access an existing pattern matcher based on a `IQuerySpecification`.
    `abstract <Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher` | `getMatcher(IQuerySpecification<Matcher> querySpecification)` Access a pattern matcher based on a `IQuerySpecification`.
    `abstract IncQueryMatcher<? extends IPatternMatch>` | `getMatcher(java.lang.String patternFQN)` Access a pattern matcher for the graph pattern with the given fully qualified name.
    `java.util.Set<IQuerySpecification<? extends IncQueryMatcher<? extends IPatternMatch>>>` | `getRegisteredQuerySpecifications()`
    `abstract IncQueryScope` | `getScope()`
    `static IncQueryEngine` | `on(IncQueryScope scope)` Obtain a (managed) `IncQueryEngine` to evaluate queries over a given scope specified by an `IncQueryScope`.
    `static IncQueryEngine` | `on(org.eclipse.emf.common.notify.Notifier emfScopeRoot)` Deprecated. use `on(IncQueryScope)` instead to evaluate queries on both EMF and non-EMF scopes.

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### IncQueryEngine

          public IncQueryEngine()

  - ### Method Detail

    - #### on

          @Deprecated
          public static IncQueryEngine on(org.eclipse.emf.common.notify.Notifier emfScopeRoot)
                                               throws IncQueryException

      Deprecated. use `on(IncQueryScope)` instead to evaluate queries on both EMF and non-EMF scopes.
      Obtain a (managed) `IncQueryEngine` on a matcher scope specified by a scope root of type `Notifier`.

      For a given matcher scope, the same engine will be returned to any client. This facilitates the reuse of internal caches of the engine, greatly improving performance.

      The lifecycle of this engine is centrally managed, and will not be disposed as long as the model is retained in memory. The engine will be garbage collected along with the model.

      Advanced users: see `AdvancedIncQueryEngine.createUnmanagedEngine(Notifier)` to obtain a private, unmanaged engine that is not shared with other clients and allows tight control over its lifecycle.

      Parameters:
        `emfScopeRoot` - the scope in which matches supported by the engine should be registered
      Returns:
        a (managed) `IncQueryEngine` instance
      Throws:
        `IncQueryException` - on initialization errors.

    - #### on

          public static IncQueryEngine on(IncQueryScope scope)
                                   throws IncQueryException

      Obtain a (managed) `IncQueryEngine` to evaluate queries over a given scope specified by an `IncQueryScope`.

      For a given matcher scope, the same engine will be returned to any client. This facilitates the reuse of internal caches of the engine, greatly improving performance.

      The lifecycle of this engine is centrally managed, and will not be disposed as long as the model is retained in memory. The engine will be garbage collected along with the model.

      Advanced users: see `AdvancedIncQueryEngine.createUnmanagedEngine(IncQueryScope)` to obtain a private, unmanaged engine that is not shared with other clients and allows tight control over its lifecycle.

      Parameters:
        `scope` - the scope of query evaluation; the definition of the set of model elements that this engine is operates on. Provide e.g. a `EMFScope` for evaluating queries on an EMF model.
      Returns:
        a (managed) `IncQueryEngine` instance
      Throws:
        `IncQueryException` - on initialization errors.

    - #### getBaseIndex

          public abstract IBaseIndex getBaseIndex()
                                           throws IncQueryException

      Provides access to the internal base index component of the engine, responsible for keeping track of basic contents of the model.

      If using an `EMFScope`, consider `EMFScope.extractUnderlyingEMFIndex(IncQueryEngine)` instead to access EMF-specific details.

      Returns:
        the baseIndex the NavigationHelper maintaining the base index
      Throws:
        `IncQueryException` - if the base index could not be constructed

    - #### getMatcher

          public abstract <Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher getMatcher(IQuerySpecification<Matcher> querySpecification)
                                                                                                 throws IncQueryException

      Access a pattern matcher based on a `IQuerySpecification`. Multiple calls will return the same matcher.
      Parameters:
        `querySpecification` - a `IQuerySpecification` that describes an IncQuery query
      Returns:
        a pattern matcher corresponding to the specification
      Throws:
        `IncQueryException` - if the matcher could not be initialized

    - #### getMatcher

          public abstract IncQueryMatcher<? extends IPatternMatch> getMatcher(java.lang.String patternFQN)
                                                                       throws IncQueryException

      Access a pattern matcher for the graph pattern with the given fully qualified name. Will succeed only if a matcher for this pattern has already been constructed in this engine, or else if the matcher for the pattern has been generated and registered. Multiple calls will return the same matcher.
      Parameters:
        `patternFQN` - the fully qualified name of an IncQuery graph pattern
      Returns:
        a pattern matcher corresponding to the specification
      Throws:
        `IncQueryException` - if the matcher could not be initialized

    - #### getExistingMatcher

          public abstract <Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher getExistingMatcher(IQuerySpecification<Matcher> querySpecification)

      Access an existing pattern matcher based on a `IQuerySpecification`.
      Parameters:
        `querySpecification` - a `IQuerySpecification` that describes an IncQuery query
      Returns:
        a pattern matcher corresponding to the specification, `null` if a matcher does not exist yet.

    - #### getCurrentMatchers

          public abstract java.util.Set<? extends IncQueryMatcher<? extends IPatternMatch>> getCurrentMatchers()

      Access a copy of available `IncQueryMatcher` pattern matchers.
      Returns:
        a copy of the set of currently available pattern matchers registered on this engine instance

    - #### getRegisteredQuerySpecifications

          public java.util.Set<IQuerySpecification<? extends IncQueryMatcher<? extends IPatternMatch>>> getRegisteredQuerySpecifications()

    - #### getEMFRoot

          @Deprecated
          public abstract org.eclipse.emf.common.notify.Notifier getEMFRoot()

      Deprecated. only valid for EMF scopes; use `getScope()` to get scope information in the general case.
      Returns:
        the scope of pattern matching, i.e. the root of the EMF model tree that this engine is attached to.

    - #### getScope

          public abstract IncQueryScope getScope()

      Returns:
        the scope of query evaluation; the definition of the set of model elements that this engine is operates on.