org.eclipse.viatra.query.runtime.api

## Class AdvancedViatraQueryEngine

- java.lang.Object
- - org.eclipse.viatra.query.runtime.api.ViatraQueryEngine
  - - org.eclipse.viatra.query.runtime.api.AdvancedViatraQueryEngine

-     public abstract class AdvancedViatraQueryEngine
      extends ViatraQueryEngine

  Advanced interface to a VIATRA incremental evaluation engine.

  You can create a new, private, unmanaged `AdvancedViatraQueryEngine` instance using `createUnmanagedEngine(QueryScope)`. Additionally, you can access the advanced interface on any `ViatraQueryEngine` by `from(ViatraQueryEngine)`.

  While the default interface `ViatraQueryEngine`, is suitable for most users, this advanced interface provides more control over the engine. The most important added functionality is the following:

  - You can have tighter control over the lifecycle of the engine, if you create a private, unmanaged engine instance. For instance, a (non-managed) engine can be disposed in order to detach from the EMF model and stop listening on update notifications. The indexes built previously in the engine can then be garbage collected, even if the model itself is retained. Total lifecycle control is only available for private, unmanaged engines (created using `createUnmanagedEngine(QueryScope)`); a managed engine (obtained via `ViatraQueryEngine.on(QueryScope)`) is shared among clients and can not be disposed or wiped.
  - You can add and remove listeners to receive notification when the model or the match sets change.
  - You can add and remove listeners to receive notification on engine lifecycle events, such as creation of new matchers. For instance, if you explicitly share a private, unmanaged engine between multiple sites, you should register a callback using `addLifecycleListener(ViatraQueryEngineLifecycleListener)` to learn when another client has called the destructive methods `dispose()` or `wipe()`.
  No Extend:
    This class is not intended to be subclassed by clients.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AdvancedViatraQueryEngine()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addLifecycleListener(ViatraQueryEngineLifecycleListener listener)` Add an engine lifecycle listener to this engine instance.
    `abstract <Match extends IPatternMatch> void` | `addMatchUpdateListener(ViatraQueryMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener, boolean fireNow)` Registers low-level callbacks for match appearance and disappearance on this pattern matcher.
    `abstract void` | `addModelUpdateListener(ViatraQueryModelUpdateListener listener)` Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).
    `static AdvancedViatraQueryEngine` | `createUnmanagedEngine(QueryScope scope)` Creates a new unmanaged VIATRA Query engine to evaluate queries over a given scope specified by an `QueryScope`.
    `static AdvancedViatraQueryEngine` | `createUnmanagedEngine(QueryScope scope, ViatraQueryEngineOptions options)` Creates a new unmanaged VIATRA Query engine to evaluate queries over a given scope specified by an `QueryScope`.
    `abstract <V> V` | `delayUpdatePropagation(java.util.concurrent.Callable<V> callable)` The given callable will be executed, and all update propagation in stateful query backends will be delayed until the execution is done.
    `abstract void` | `dispose()` Completely disconnects and dismantles the engine.
    `static AdvancedViatraQueryEngine` | `from(ViatraQueryEngine engine)` Provides access to a given existing engine through the advanced interface.
    `abstract ViatraQueryEngineOptions` | `getEngineOptions()` Returns the immutable `ViatraQueryEngineOptions` of the engine.
    `abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher` | `getExistingMatcher(IQuerySpecification<Matcher> querySpecification, QueryEvaluationHint optionalOverrideHints)` Access an existing pattern matcher based on a `IQuerySpecification`, and optional hints override.
    `abstract <Matcher extends ViatraQueryMatcher<? 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.
    `abstract IQueryBackend` | `getQueryBackend(IQueryBackendFactory iQueryBackendFactory)` Provides access to the selected query backend component of the VIATRA Query engine.
    `abstract IQueryResultProvider` | `getResultProviderOfMatcher(ViatraQueryMatcher<? extends IPatternMatch> matcher)` Return the underlying result provider for the given matcher.
    `abstract boolean` | `isDisposed()` Returns true if the `dispose()` method was called on this engine previously.
    `abstract boolean` | `isManaged()` Indicates whether the engine is managed, i.e.
    `abstract boolean` | `isTainted()` Indicates whether the engine is in a tainted, inconsistent state due to some internal errors.
    `abstract boolean` | `isUpdatePropagationDelayed()` Returns true if the update propagation in this engine is currently delayed, false otherwise.
    `abstract 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).
    `abstract void` | `removeLifecycleListener(ViatraQueryEngineLifecycleListener listener)` Remove an existing lifecycle listener from this engine instance.
    `abstract <Match extends IPatternMatch> void` | `removeMatchUpdateListener(ViatraQueryMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener)` Remove an existing match update event listener to this engine instance.
    `abstract void` | `removeModelUpdateListener(ViatraQueryModelUpdateListener listener)` Remove an existing model update event listener to this engine instance.
    `abstract void` | `wipe()` Discards any pattern matcher caches and forgets known patterns.

    - ### Methods inherited from class org.eclipse.viatra.query.runtime.api.ViatraQueryEngine

      `getBaseIndex, getCurrentMatchers, getExistingMatcher, getMatcher, getMatcher, getRegisteredQuerySpecifications, getScope, on, on`

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

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

- - ### Constructor Detail

    - #### AdvancedViatraQueryEngine

          public AdvancedViatraQueryEngine()

  - ### Method Detail

    - #### createUnmanagedEngine

          public static AdvancedViatraQueryEngine createUnmanagedEngine(QueryScope scope)

      Creates a new unmanaged VIATRA Query engine to evaluate queries over a given scope specified by an `QueryScope`.

      Repeated invocations will return different instances, so other clients are unable to independently access and influence the returned engine. Note that unmanaged engines do not benefit from some performance improvements that stem from sharing incrementally maintained indices and caches between multiple clients using the same managed engine instance.

      Client is responsible for the lifecycle of the returned engine, hence the usage of the advanced interface `AdvancedViatraQueryEngine`.

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

      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:
        the advanced interface to a newly created unmanaged engine
      Since:
        0.9

    - #### createUnmanagedEngine

          public static AdvancedViatraQueryEngine createUnmanagedEngine(QueryScope scope,
                                                                        ViatraQueryEngineOptions options)

      Creates a new unmanaged VIATRA Query engine to evaluate queries over a given scope specified by an `QueryScope`.

      Repeated invocations will return different instances, so other clients are unable to independently access and influence the returned engine. Note that unmanaged engines do not benefit from some performance improvements that stem from sharing incrementally maintained indices and caches between multiple clients using the same managed engine instance.

      Client is responsible for the lifecycle of the returned engine, hence the usage of the advanced interface `AdvancedViatraQueryEngine`.

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

      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:
        the advanced interface to a newly created unmanaged engine
      Since:
        1.4

    - #### from

          public static AdvancedViatraQueryEngine from(ViatraQueryEngine engine)

      Provides access to a given existing engine through the advanced interface.

      Caveat: if the referenced engine is managed (i.e. created via `ViatraQueryEngine.on(QueryScope)`), the advanced methods `dispose()` and `wipe()` will not be allowed.

      Parameters:
        `engine` - the engine to access using the advanced interface
      Returns:
        a reference to the same engine conforming to the advanced interface

    - #### addLifecycleListener

          public abstract void addLifecycleListener(ViatraQueryEngineLifecycleListener listener)

      Add an engine lifecycle listener to this engine instance.
      Parameters:
        `listener` - the `ViatraQueryEngineLifecycleListener` that should listen to lifecycle events from this engine

    - #### removeLifecycleListener

          public abstract void removeLifecycleListener(ViatraQueryEngineLifecycleListener listener)

      Remove an existing lifecycle listener from this engine instance.
      Parameters:
        `listener` - the `ViatraQueryEngineLifecycleListener` that should not listen to lifecycle events from this engine anymore

    - #### addModelUpdateListener

          public abstract void addModelUpdateListener(ViatraQueryModelUpdateListener listener)

      Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).
      Parameters:
        `listener` - the `ViatraQueryModelUpdateListener` that should listen to model update events from this engine.

    - #### removeModelUpdateListener

          public abstract void removeModelUpdateListener(ViatraQueryModelUpdateListener listener)

      Remove an existing model update event listener to this engine instance.
      Parameters:
        `listener` - the `ViatraQueryModelUpdateListener` that should not listen to model update events from this engine anymore

    - #### addMatchUpdateListener

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

      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 (`ViatraObservables`) or the event-driven 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)`.

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

    - #### removeMatchUpdateListener

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

      Remove an existing match update event listener to this engine instance.
      Parameters:
        `matcher` - the `ViatraQueryMatcher` for which this listener should not be active anymore
        `listener` - the `IMatchUpdateListener` that should not receive the callbacks anymore

    - #### getMatcher

          public abstract <Matcher extends ViatraQueryMatcher<? 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. Multiple calls may return the same matcher depending on the actual evaluation hints.

      It is guaranteed that this method will always return a matcher instance which is functionally compatible with the requested functionality (see `IMatcherCapability`). Otherwise, the query evaluator is free to ignore any hints.

      For stateful query backends (Rete), hints may be effective only the first time a matcher is created.

      Parameters:
        `querySpecification` - a `IQuerySpecification` that describes a VIATRA 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:
        `ViatraQueryRuntimeException` - if the matcher could not be initialized
      Since:
        0.9

    - #### prepareGroup

          public abstract 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). 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.

      Parameters:
        `queryGroup` - a `IQueryGroup` identifying a set of VIATRA queries
        `optionalEvaluationHints` - additional / overriding options on query evaluation; passing null means default options associated with each query
      Throws:
        `ViatraQueryRuntimeException` - if there was an error in preparing the engine
      Since:
        0.9

    - #### isManaged

          public abstract boolean isManaged()

      Indicates whether the engine is managed, i.e. the default engine assigned to the given scope root by `ViatraQueryEngine.on(QueryScope)`.

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

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

      Returns:
        true if the engine is managed, and therefore potentially shared with other clients querying the same EMF model

    - #### isTainted

          public abstract boolean isTainted()

      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 `ViatraQueryEngineLifecycleListener` interface provides a callback method for entering the tainted state.

      Returns:
        the tainted state

    - #### wipe

          public abstract void wipe()

      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 `isManaged()`), as there may be other clients using it.

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

      Throws:
        `java.lang.UnsupportedOperationException` - if engine is managed

    - #### dispose

          public abstract void dispose()

      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 `ViatraQueryEngine.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 `isManaged()`), as there may be other clients using it.

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

      Throws:
        `java.lang.UnsupportedOperationException` - if engine is managed

    - #### getQueryBackend

          public abstract IQueryBackend getQueryBackend(IQueryBackendFactory iQueryBackendFactory)

      Provides access to the selected query backend component of the VIATRA Query engine.
      Throws:
        `ViatraQueryRuntimeException`
      No Reference:
        for internal use only

    - #### getExistingMatcher

          public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getExistingMatcher(IQuerySpecification<Matcher> querySpecification,
                                                                                                                   QueryEvaluationHint optionalOverrideHints)

      Access an existing pattern matcher based on a `IQuerySpecification`, and optional hints override.
      Parameters:
        `querySpecification` - a `IQuerySpecification` that describes a VIATRA query specification
        `optionalOverrideHints` - a `QueryEvaluationHint` that may override the pattern hints (can be null)
      Returns:
        a pattern matcher corresponding to the specification, `null` if a matcher does not exist yet.
      Since:
        1.4

    - #### getEngineOptions

          public abstract ViatraQueryEngineOptions getEngineOptions()

      Returns the immutable `ViatraQueryEngineOptions` of the engine.
      Returns:
        the engine options
      Since:
        1.4

    - #### getResultProviderOfMatcher

          public abstract IQueryResultProvider getResultProviderOfMatcher(ViatraQueryMatcher<? extends IPatternMatch> matcher)

      Return the underlying result provider for the given matcher.
      Since:
        1.4
      No Reference:
        This method is considered internal API

    - #### delayUpdatePropagation

          public abstract <V> V delayUpdatePropagation(java.util.concurrent.Callable<V> callable)
                                                throws java.lang.reflect.InvocationTargetException

      The given callable will be executed, and all update propagation in stateful query backends will be delayed until the execution is done. Within the callback, these backends will provide stale results.

      It is optional for a `IQueryBackend` to support the delaying of update propagation; stateless backends will display up-to-date results. In this case, the given callable shall be executed, and the update propagation shall happen just like in non-delayed execution.

      Example: in the Rete network, no messages will be propagated until the given callable is executed. After the execution of the callable, all accumulated messages will be delivered.

      The purpose of this method is that stateful query backends may save work when multiple model modifications are performed within the callback that partially cancel each other out.

      Parameters:
        `callable` - the callable to be executed
      Returns:
        the result of the callable
      Throws:
        `java.lang.reflect.InvocationTargetException`
      Since:
        1.6

    - #### isUpdatePropagationDelayed

          public abstract boolean isUpdatePropagationDelayed()

      Returns true if the update propagation in this engine is currently delayed, false otherwise.
      Since:
        1.6
      See Also:
        `#delayUpdatePropagation(Callable)}`

    - #### isDisposed

          public abstract boolean isDisposed()

      Returns true if the `dispose()` method was called on this engine previously.
      Since:
        2.0