org.eclipse.incquery.runtime.api

Class AdvancedIncQueryEngine

java.lang.Object

org.eclipse.incquery.runtime.api.IncQueryEngine

org.eclipse.incquery.runtime.api.AdvancedIncQueryEngine

Direct Known Subclasses:

IncQueryEngineImpl

public abstract class AdvancedIncQueryEngine
extends IncQueryEngine

Advanced interface to an IncQuery incremental evaluation engine.

You can create a new, private, unmanaged AdvancedIncQueryEngine instance using createUnmanagedEngine(IncQueryScope). Additionally, you can access the advanced interface on any IncQueryEngine by from(IncQueryEngine).

While the default interface IncQueryEngine, 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(IncQueryScope)); a managed engine (obtained via IncQueryEngine.on(IncQueryScope)) 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(IncQueryEngineLifecycleListener) to learn when another client has called the destructive methods dispose() or wipe().

Author:

Bergmann Gabor

Constructor Summary

Constructors

Constructor and Description
AdvancedIncQueryEngine()

Method Summary

Modifier and Type	Method and Description
abstract void	addLifecycleListener(IncQueryEngineLifecycleListener listener) Add an engine lifecycle listener to this engine instance.
abstract <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.
abstract void	addModelUpdateListener(IncQueryModelUpdateListener listener) Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).
static AdvancedIncQueryEngine	createUnmanagedEngine(IncQueryScope scope) Creates a new unmanaged IncQuery engine to evaluate queries over a given scope specified by an IncQueryScope.
static AdvancedIncQueryEngine	createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot) Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.
static AdvancedIncQueryEngine	createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot, BaseIndexOptions options) Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.
static AdvancedIncQueryEngine	createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot, boolean wildcardMode) Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.
static AdvancedIncQueryEngine	createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot, boolean wildcardMode, boolean dynamicEMFMode) Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.
abstract void	dispose() Completely disconnects and dismantles the engine.
static AdvancedIncQueryEngine	from(IncQueryEngine engine) Provides access to a given existing engine through the advanced interface.
abstract <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.
abstract IQueryBackend	getQueryBackend(java.lang.Class<? extends IQueryBackend> backendClass) Provides access to the selected query backend component of the IncQuery engine.
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 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(IncQueryEngineLifecycleListener listener) Remove an existing lifecycle listener from this engine instance.
abstract <Match extends IPatternMatch> void	removeMatchUpdateListener(IncQueryMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener) Remove an existing match update event listener to this engine instance.
abstract void	removeModelUpdateListener(IncQueryModelUpdateListener 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.incquery.runtime.api.IncQueryEngine

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

Methods inherited from class java.lang.Object

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

Constructor Detail

AdvancedIncQueryEngine

public AdvancedIncQueryEngine()

Method Detail

createUnmanagedEngine

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

Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.

Creates a new unmanaged EMF-IncQuery engine at an EMF model root (recommended: Resource or ResourceSet). 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 AdvancedIncQueryEngine.

The scope of pattern matching will be the given EMF model root and below (see FAQ for more precise definition). The match set of any patterns will be incrementally refreshed upon updates from this scope.

Parameters:

emfScopeRoot - the root of the EMF containment hierarchy where this engine should operate. Recommended: Resource or ResourceSet.

Returns:

the advanced interface to a newly created unmanaged engine

Throws:

IncQueryException

See Also:

for performance tuning and dynamic EMF options.

createUnmanagedEngine

@Deprecated
public static AdvancedIncQueryEngine createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot,
                                                                       boolean wildcardMode)
                                                                throws IncQueryException

Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.

Creates a new unmanaged EMF-IncQuery engine at an EMF model root (recommended: Resource or ResourceSet). 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 AdvancedIncQueryEngine.

The scope of pattern matching will be the given EMF model root and below (see FAQ for more precise definition). The match set of any patterns will be incrementally refreshed upon updates from this scope.

Parameters:

emfScopeRoot - the root of the EMF containment hierarchy where this engine should operate. Recommended: Resource or ResourceSet.

wildcardMode - specifies whether the base index should be built in wildcard mode. See BaseIndexOptions for the explanation of wildcard mode. Defaults to false.

Returns:

the advanced interface to a newly created unmanaged engine

Throws:

IncQueryException

createUnmanagedEngine

@Deprecated
public static AdvancedIncQueryEngine createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot,
                                                                       boolean wildcardMode,
                                                                       boolean dynamicEMFMode)
                                                                throws IncQueryException

Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.

Creates a new unmanaged EMF-IncQuery engine at an EMF model root (recommended: Resource or ResourceSet). 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 AdvancedIncQueryEngine.

The scope of pattern matching will be the given EMF model root and below (see FAQ for more precise definition). The match set of any patterns will be incrementally refreshed upon updates from this scope.

Parameters:

emfScopeRoot - the root of the EMF containment hierarchy where this engine should operate. Recommended: Resource or ResourceSet.

wildcardMode - specifies whether the base index should be built in wildcard mode. See BaseIndexOptions for the explanation of wildcard mode. Defaults to false.

dynamicEMFMode - specifies whether the base index should be built in dynamic EMF mode. See BaseIndexOptions for the explanation of dynamic EMF mode. Defaults to false.

Returns:

the advanced interface to a newly created unmanaged engine

Throws:

IncQueryException

createUnmanagedEngine

@Deprecated
public static AdvancedIncQueryEngine createUnmanagedEngine(org.eclipse.emf.common.notify.Notifier emfScopeRoot,
                                                                       BaseIndexOptions options)
                                                                throws IncQueryException

Deprecated. use createUnmanagedEngine(IncQueryScope) instead to evaluate queries on both EMF and non-EMF scopes.

Creates a new unmanaged EMF-IncQuery engine at an EMF model root (recommended: Resource or ResourceSet). 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 AdvancedIncQueryEngine.

The scope of pattern matching will be the given EMF model root and below (see FAQ for more precise definition). The match set of any patterns will be incrementally refreshed upon updates from this scope.

Parameters:

emfScopeRoot - the root of the EMF containment hierarchy where this engine should operate. Recommended: Resource or ResourceSet.

options - specifies how the base index is built, including wildcard mode (defaults to false) and dynamic EMF mode (defaults to false). See BaseIndexOptions for the explanation of wildcard mode and dynamic EMF mode.

Returns:

the advanced interface to a newly created unmanaged engine

Throws:

IncQueryException

createUnmanagedEngine

public static AdvancedIncQueryEngine createUnmanagedEngine(IncQueryScope scope)
                                                    throws IncQueryException

Creates a new unmanaged IncQuery engine to evaluate queries over a given scope specified by an IncQueryScope.

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 AdvancedIncQueryEngine.

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

Throws:

IncQueryException

Since:

0.9

from

public static AdvancedIncQueryEngine from(IncQueryEngine engine)

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

Caveat: if the referenced engine is managed (i.e. created via IncQueryEngine.on(IncQueryScope)), 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(IncQueryEngineLifecycleListener listener)

Add an engine lifecycle listener to this engine instance.

Parameters:

listener - the IncQueryEngineLifecycleListener that should listen to lifecycle events from this engine

removeLifecycleListener

public abstract void removeLifecycleListener(IncQueryEngineLifecycleListener listener)

Remove an existing lifecycle listener from this engine instance.

Parameters:

listener - the IncQueryEngineLifecycleListener that should not listen to lifecycle events from this engine anymore

addModelUpdateListener

public abstract void addModelUpdateListener(IncQueryModelUpdateListener listener)

Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).

Parameters:

listener - the IncQueryModelUpdateListener that should listen to model update events from this engine.

removeModelUpdateListener

public abstract void removeModelUpdateListener(IncQueryModelUpdateListener listener)

Remove an existing model update event listener to this engine instance.

Parameters:

listener - the IncQueryModelUpdateListener that should not listen to model update events from this engine anymore

addMatchUpdateListener

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

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

Parameters:

fireNow - if true, appearCallback will be immediately invoked on all current matches as a one-time effect. See also IncQueryMatcher.forEachMatch(IMatchProcessor).

listener - the listener that will be notified of each new match that appears or disappears, starting from now.

matcher - the IncQueryMatcher for which this listener should be active

removeMatchUpdateListener

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

Remove an existing match update event listener to this engine instance.

Parameters:

matcher - the IncQueryMatcher for which this listener should not be active anymore

listener - the IMatchUpdateListener that should not receive the callbacks anymore

getMatcher

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

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.

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

Since:

0.9

prepareGroup

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

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 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

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 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 wipe() and dispose() are not allowed.

On the other hand, if the engine is unmanaged (i.e. a private instance created using createUnmanagedEngine(IncQueryScope)), then wipe() and dispose() can be called. If you explicitly share a private, unmanaged engine between multiple sites, register a callback using addLifecycleListener(IncQueryEngineLifecycleListener) 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 IncQueryEngineLifecycleListener 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(IncQueryEngineLifecycleListener) 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 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 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(IncQueryEngineLifecycleListener) to learn when another client has called this destructive method.

Throws:

java.lang.UnsupportedOperationException - if engine is managed

getQueryBackend

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

Provides access to the selected query backend component of the IncQuery engine.

Throws:

IncQueryException