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)

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.

Class IncQueryEngineImpl

Field Summary

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

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

Constructor Detail

IncQueryEngineImpl

Method Detail

getEMFRoot

getCurrentMatchers

getMatcher

getMatcher

getExistingMatcher

getMatcher

getBaseIndex

getLogger

reportMatcherInitialized

getQueryBackend

dispose

wipe

isTainted

isManaged

addMatchUpdateListener

removeMatchUpdateListener

addModelUpdateListener

removeModelUpdateListener

addLifecycleListener

removeLifecycleListener

getResultProvider

isResultCached

getCachingResultProvider

getHints

prepareGroup

getScope