org.eclipse.incquery.runtime.internal.apiimpl

## Class IncQueryEngineImpl

- java.lang.Object
- - org.eclipse.incquery.runtime.api.IncQueryEngine
  - - org.eclipse.incquery.runtime.api.AdvancedIncQueryEngine
    - - org.eclipse.incquery.runtime.internal.apiimpl.IncQueryEngineImpl

- All Implemented Interfaces:
    IQueryBackendHintProvider, IQueryCacheContext

      public class IncQueryEngineImpl
      extends AdvancedIncQueryEngine
      implements IQueryBackendHintProvider, IQueryCacheContext

  An IncQuery engine back-end (implementation)
  Author:
    Bergmann Gábor

- - ### Field Summary

    - ### Fields inherited from interface org.eclipse.incquery.runtime.matchers.backend.IQueryBackendHintProvider

      `DEFAULT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IncQueryEngineImpl(IncQueryEngineManager manager, IncQueryScope scope)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addLifecycleListener(IncQueryEngineLifecycleListener listener)` Add an engine lifecycle listener to this engine instance.
    `<Match extends IPatternMatch> void` | `addMatchUpdateListener(IncQueryMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener, boolean fireNow)` Registers low-level callbacks for match appearance and disappearance on this pattern matcher.
    `void` | `addModelUpdateListener(IncQueryModelUpdateListener listener)` Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).
    `void` | `dispose()` Completely disconnects and dismantles the engine.
    `IBaseIndex` | `getBaseIndex()` Provides access to the internal base index component of the engine, responsible for keeping track of basic contents of the model.
    `IQueryResultProvider` | `getCachingResultProvider(PQuery query)` Returns a caching result provider for the given query; it must be constructed if it does not exist yet.
    `java.util.Set<? extends IncQueryMatcher<? extends IPatternMatch>>` | `getCurrentMatchers()` Access a copy of available `IncQueryMatcher` pattern matchers.
    `org.eclipse.emf.common.notify.Notifier` | `getEMFRoot()`
    `<Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher` | `getExistingMatcher(IQuerySpecification<Matcher> querySpecification)` Access an existing pattern matcher based on a `IQuerySpecification`.
    `java.util.Map<java.lang.String,java.lang.Object>` | `getHints(PQuery query)` Suggests query evaluation hints regarding a query.
    `org.apache.log4j.Logger` | `getLogger()`
    `<Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher` | `getMatcher(IQuerySpecification<Matcher> querySpecification)` Access a pattern matcher based on a `IQuerySpecification`.
    `<Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher` | `getMatcher(IQuerySpecification<Matcher> querySpecification, QueryEvaluationHint optionalEvaluationHints)` Access a pattern matcher based on a `IQuerySpecification`, overriding some of the default query evaluation hints.
    `IncQueryMatcher<? extends IPatternMatch>` | `getMatcher(java.lang.String patternFQN)` Access a pattern matcher for the graph pattern with the given fully qualified name.
    `IQueryBackend` | `getQueryBackend(java.lang.Class<? extends IQueryBackend> backendClass)` Provides access to the selected query backend component of the IncQuery engine.
    `IQueryResultProvider` | `getResultProvider(IQuerySpecification<?> query)` Returns an internal interface towards the query backend to feed the matcher with results.
    `IncQueryScope` | `getScope()`
    `boolean` | `isManaged()` Indicates whether the engine is managed, i.e.
    `boolean` | `isResultCached(PQuery query)` Checks if there already is a caching result provider for the given query.
    `boolean` | `isTainted()` Indicates whether the engine is in a tainted, inconsistent state due to some internal errors.
    `void` | `prepareGroup(IQueryGroup queryGroup, QueryEvaluationHint optionalEvaluationHints)` Initializes matchers for a group of patterns as one step (optionally overriding some of the default query evaluation hints).
    `void` | `removeLifecycleListener(IncQueryEngineLifecycleListener listener)` Remove an existing lifecycle listener from this engine instance.
    `<Match extends IPatternMatch> void` | `removeMatchUpdateListener(IncQueryMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener)` Remove an existing match update event listener to this engine instance.
    `void` | `removeModelUpdateListener(IncQueryModelUpdateListener listener)` Remove an existing model update event listener to this engine instance.
    `void` | `reportMatcherInitialized(IQuerySpecification<?> querySpecification, IncQueryMatcher<?> matcher)` Report when a pattern matcher has been completely initialized, so that it can be registered into the engine.
    `void` | `wipe()` Discards any pattern matcher caches and forgets known patterns.

    - ### Methods inherited from class org.eclipse.incquery.runtime.api.AdvancedIncQueryEngine

      `createUnmanagedEngine, createUnmanagedEngine, createUnmanagedEngine, createUnmanagedEngine, createUnmanagedEngine, from`

    - ### Methods inherited from class org.eclipse.incquery.runtime.api.IncQueryEngine

      `getRegisteredQuerySpecifications, on, on`

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

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

- - ### Constructor Detail

    - #### IncQueryEngineImpl

          public IncQueryEngineImpl(IncQueryEngineManager manager,
                                    IncQueryScope scope)
                             throws IncQueryException

      Parameters:
        `manager` - null if unmanaged
        `scope` -
      Throws:
        `IncQueryException` - if the emf root is invalid

  - ### Method Detail

    - #### getEMFRoot

          public org.eclipse.emf.common.notify.Notifier getEMFRoot()

      Specified by:
        `getEMFRoot` in class `IncQueryEngine`
      Returns:
        the scope of pattern matching, i.e. the root of the EMF model tree that this engine is attached to.

    - #### getCurrentMatchers

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

      Description copied from class: `IncQueryEngine`
      Access a copy of available `IncQueryMatcher` pattern matchers.
      Specified by:
        `getCurrentMatchers` in class `IncQueryEngine`
      Returns:
        a copy of the set of currently available pattern matchers registered on this engine instance

    - #### getMatcher

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

      Description copied from class: `IncQueryEngine`
      Access a pattern matcher based on a `IQuerySpecification`. Multiple calls will return the same matcher.
      Specified by:
        `getMatcher` in class `IncQueryEngine`
      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 <Matcher extends IncQueryMatcher<? extends IPatternMatch>> Matcher getMatcher(IQuerySpecification<Matcher> querySpecification,
                                                                                               QueryEvaluationHint optionalEvaluationHints)
                                                                                        throws IncQueryException

      Description copied from class: `AdvancedIncQueryEngine`
      Access a pattern matcher based on a `IQuerySpecification`, overriding some of the default query evaluation hints. Multiple calls will return the same matcher.

      Hints are only effective the first time a matcher is created.

      Specified by:
        `getMatcher` in class `AdvancedIncQueryEngine`
      Parameters:
        `querySpecification` - a `IQuerySpecification` that describes an IncQuery query
        `optionalEvaluationHints` - additional / overriding options on query evaluation; passing null means default options associated with the query
      Returns:
        a pattern matcher corresponding to the specification
      Throws:
        `IncQueryException` - if the matcher could not be initialized

    - #### getExistingMatcher

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

      Description copied from class: `IncQueryEngine`
      Access an existing pattern matcher based on a `IQuerySpecification`.
      Specified by:
        `getExistingMatcher` in class `IncQueryEngine`
      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.

    - #### getMatcher

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

      Description copied from class: `IncQueryEngine`
      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.
      Specified by:
        `getMatcher` in class `IncQueryEngine`
      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

    - #### getBaseIndex

          public IBaseIndex getBaseIndex()
                                  throws IncQueryException

      Description copied from class: `IncQueryEngine`
      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.

      Specified by:
        `getBaseIndex` in class `IncQueryEngine`
      Returns:
        the baseIndex the NavigationHelper maintaining the base index
      Throws:
        `IncQueryException` - if the base index could not be constructed

    - #### getLogger

          public final org.apache.log4j.Logger getLogger()

    - #### reportMatcherInitialized

          public void reportMatcherInitialized(IQuerySpecification<?> querySpecification,
                                               IncQueryMatcher<?> matcher)

      Report when a pattern matcher has been completely initialized, so that it can be registered into the engine.
      Parameters:
        `querySpecification` - the `IQuerySpecification` that corresponds to the matcher
        `matcher` - the `IncQueryMatcher` that has finished its initialization process TODO make it package-only visible when implementation class is moved to impl package

    - #### getQueryBackend

          public IQueryBackend getQueryBackend(java.lang.Class<? extends IQueryBackend> backendClass)
                                        throws IncQueryException

      Provides access to the selected query backend component of the IncQuery engine.
      Specified by:
        `getQueryBackend` in class `AdvancedIncQueryEngine`
      Throws:
        `IncQueryException`

    - #### dispose

          public void dispose()

      Description copied from class: `AdvancedIncQueryEngine`
      Completely disconnects and dismantles the engine. Cannot be reversed.

      Matcher objects will continue to return stale results. If no references are retained to the matchers or the engine, they can eventually be GC'ed, and they won't block the EMF model from being GC'ed anymore.

      The base indexer (see `IncQueryEngine.getBaseIndex()`) built on the model will be disposed alongside the engine, unless the user has manually added listeners on the base index that were not removed yet.

      Disallowed if the engine is managed (see `AdvancedIncQueryEngine.isManaged()`), as there may be other clients using it.

      If you explicitly share a private, unmanaged engine between multiple sites, register a callback using `AdvancedIncQueryEngine.addLifecycleListener(IncQueryEngineLifecycleListener)` to learn when another client has called this destructive method.

      Specified by:
        `dispose` in class `AdvancedIncQueryEngine`

    - #### wipe

          public void wipe()

      Description copied from class: `AdvancedIncQueryEngine`
      Discards any pattern matcher caches and forgets known patterns. The base index built directly on the underlying EMF model, however, is kept in memory to allow reuse when new pattern matchers are built. Use this method if you have e.g. new versions of the same patterns, to be matched on the same model.

      Matcher objects will continue to return stale results. If no references are retained to the matchers, they can eventually be GC'ed.

      Disallowed if the engine is managed (see `AdvancedIncQueryEngine.isManaged()`), as there may be other clients using it.

      If you explicitly share a private, unmanaged engine between multiple sites, register a callback using `AdvancedIncQueryEngine.addLifecycleListener(IncQueryEngineLifecycleListener)` to learn when another client has called this destructive method.

      Specified by:
        `wipe` in class `AdvancedIncQueryEngine`

    - #### isTainted

          public boolean isTainted()

      Description copied from class: `AdvancedIncQueryEngine`
      Indicates whether the engine is in a tainted, inconsistent state due to some internal errors. If true, results are no longer reliable; engine should be disposed.

      The engine is in a tainted state if any of its internal processes report back a fatal error. The `IncQueryEngineLifecycleListener` interface provides a callback method for entering the tainted state.

      Specified by:
        `isTainted` in class `AdvancedIncQueryEngine`
      Returns:
        the tainted state

    - #### isManaged

          public boolean isManaged()

      Description copied from class: `AdvancedIncQueryEngine`
      Indicates whether the engine is managed, i.e. the default engine assigned to the given scope root by `IncQueryEngine.on(IncQueryScope)`.

      If the engine is managed, there may be other clients using it, as all calls to `IncQueryEngine.on(IncQueryScope)` return the same managed engine instance for a given scope root. Therefore the destructive methods `AdvancedIncQueryEngine.wipe()` and `AdvancedIncQueryEngine.dispose()` are not allowed.

      On the other hand, if the engine is unmanaged (i.e. a private instance created using `AdvancedIncQueryEngine.createUnmanagedEngine(IncQueryScope)`), then `AdvancedIncQueryEngine.wipe()` and `AdvancedIncQueryEngine.dispose()` can be called. If you explicitly share a private, unmanaged engine between multiple sites, register a callback using `AdvancedIncQueryEngine.addLifecycleListener(IncQueryEngineLifecycleListener)` to learn when another client has called these destructive methods.

      Specified by:
        `isManaged` in class `AdvancedIncQueryEngine`
      Returns:
        true if the engine is managed, and therefore potentially shared with other clients querying the same EMF model

    - #### addMatchUpdateListener

          public <Match extends IPatternMatch> void addMatchUpdateListener(IncQueryMatcher<Match> matcher,
                                                                           IMatchUpdateListener<? super Match> listener,
                                                                           boolean fireNow)

      Description copied from class: `AdvancedIncQueryEngine`
      Registers low-level callbacks for match appearance and disappearance on this pattern matcher.

      Caution: This is a low-level callback that is invoked when the pattern matcher is not necessarily in a consistent state yet. Importantly, no model modification permitted during the callback. Most users should use the databinding support (org.eclipse.incquery.databinding.runtime.api.IncQueryObservables) or the event-driven API (org.eclipse.incquery.runtime.evm.api.EventDrivenVM) instead.

      Performance note: expected to be much more efficient than polling at `#addCallbackAfterUpdates(Runnable)`, but prone to "signal hazards", e.g. spurious match appearances that will disappear immediately afterwards.

      The callback can be unregistered via `#removeCallbackOnMatchUpdate(IMatchUpdateListener)`.

      Specified by:
        `addMatchUpdateListener` in class `AdvancedIncQueryEngine`
      Parameters:
        `matcher` - the `IncQueryMatcher` for which this listener should be active
        `listener` - the listener that will be notified of each new match that appears or disappears, starting from now.
        `fireNow` - if true, appearCallback will be immediately invoked on all current matches as a one-time effect. See also `IncQueryMatcher.forEachMatch(IMatchProcessor)`.

    - #### removeMatchUpdateListener

          public <Match extends IPatternMatch> void removeMatchUpdateListener(IncQueryMatcher<Match> matcher,
                                                                              IMatchUpdateListener<? super Match> listener)

      Description copied from class: `AdvancedIncQueryEngine`
      Remove an existing match update event listener to this engine instance.
      Specified by:
        `removeMatchUpdateListener` in class `AdvancedIncQueryEngine`
      Parameters:
        `matcher` - the `IncQueryMatcher` for which this listener should not be active anymore
        `listener` - the `IMatchUpdateListener` that should not receive the callbacks anymore

    - #### addModelUpdateListener

          public void addModelUpdateListener(IncQueryModelUpdateListener listener)

      Description copied from class: `AdvancedIncQueryEngine`
      Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).
      Specified by:
        `addModelUpdateListener` in class `AdvancedIncQueryEngine`
      Parameters:
        `listener` - the `IncQueryModelUpdateListener` that should listen to model update events from this engine.

    - #### removeModelUpdateListener

          public void removeModelUpdateListener(IncQueryModelUpdateListener listener)

      Description copied from class: `AdvancedIncQueryEngine`
      Remove an existing model update event listener to this engine instance.
      Specified by:
        `removeModelUpdateListener` in class `AdvancedIncQueryEngine`
      Parameters:
        `listener` - the `IncQueryModelUpdateListener` that should not listen to model update events from this engine anymore

    - #### addLifecycleListener

          public void addLifecycleListener(IncQueryEngineLifecycleListener listener)

      Description copied from class: `AdvancedIncQueryEngine`
      Add an engine lifecycle listener to this engine instance.
      Specified by:
        `addLifecycleListener` in class `AdvancedIncQueryEngine`
      Parameters:
        `listener` - the `IncQueryEngineLifecycleListener` that should listen to lifecycle events from this engine

    - #### removeLifecycleListener

          public void removeLifecycleListener(IncQueryEngineLifecycleListener listener)

      Description copied from class: `AdvancedIncQueryEngine`
      Remove an existing lifecycle listener from this engine instance.
      Specified by:
        `removeLifecycleListener` in class `AdvancedIncQueryEngine`
      Parameters:
        `listener` - the `IncQueryEngineLifecycleListener` that should not listen to lifecycle events from this engine anymore

    - #### getResultProvider

          public IQueryResultProvider getResultProvider(IQuerySpecification<?> query)
                                                 throws QueryProcessingException,
                                                        IncQueryException

      Returns an internal interface towards the query backend to feed the matcher with results.
      Parameters:
        `query` - the pattern for which the result provider should be delivered
      Throws:
        `QueryProcessingException`
        `IncQueryException`

    - #### isResultCached

          public boolean isResultCached(PQuery query)

      Description copied from interface: `IQueryCacheContext`
      Checks if there already is a caching result provider for the given query.

      Returns false if called while the caching result provider of the given query is being constructed in the first place.

      Specified by:
        `isResultCached` in interface `IQueryCacheContext`

    - #### getCachingResultProvider

          public IQueryResultProvider getCachingResultProvider(PQuery query)
                                                        throws QueryProcessingException

      Description copied from interface: `IQueryCacheContext`
      Returns a caching result provider for the given query; it must be constructed if it does not exist yet.

      Caution: behavior undefined if called while the caching result provider of the given query is being constructed. Beware of infinite loops.

      Postcondition: `IQueryBackend.isCaching()` returns true for the `#getQueryBackend()` of the returned provider

      Specified by:
        `getCachingResultProvider` in interface `IQueryCacheContext`
      Throws:
        `QueryProcessingException`

    - #### getHints

          public java.util.Map<java.lang.String,java.lang.Object> getHints(PQuery query)

      Description copied from interface: `IQueryBackendHintProvider`
      Suggests query evaluation hints regarding a query.
      Specified by:
        `getHints` in interface `IQueryBackendHintProvider`
      Returns:
        non-null map of option keys and values

    - #### prepareGroup

          public void prepareGroup(IQueryGroup queryGroup,
                                   QueryEvaluationHint optionalEvaluationHints)
                            throws IncQueryException

      Description copied from class: `AdvancedIncQueryEngine`
      Initializes matchers for a group of patterns as one step (optionally overriding some of the default query evaluation hints). If some of the pattern matchers are already constructed in the engine, no task is performed for them.

      This preparation step has the advantage that it prepares pattern matchers for an arbitrary number of patterns in a single-pass traversal of the model. This is typically more efficient than traversing the model each time an individual pattern matcher is initialized on demand. The performance benefit only manifests itself if the engine is not in wildcard mode.

      Specified by:
        `prepareGroup` in class `AdvancedIncQueryEngine`
      Parameters:
        `queryGroup` - a `IQueryGroup` identifying a set of IncQuery queries
        `optionalEvaluationHints` - additional / overriding options on query evaluation; passing null means default options associated with each query
      Throws:
        `IncQueryException` - if there was an error in preparing the engine

    - #### getScope

          public IncQueryScope getScope()

      Specified by:
        `getScope` in class `IncQueryEngine`
      Returns:
        the scope of query evaluation; the definition of the set of model elements that this engine is operates on.