Package tools.refinery.interpreter.internal.apiimpl

Class InterpreterEngineImpl

java.lang.Object

tools.refinery.interpreter.api.InterpreterEngine

tools.refinery.interpreter.api.AdvancedInterpreterEngine

tools.refinery.interpreter.internal.apiimpl.InterpreterEngineImpl

All Implemented Interfaces:

IQueryBackendHintProvider, IQueryCacheContext, IQueryResultProviderAccess

public final class InterpreterEngineImpl
extends AdvancedInterpreterEngine
implements IQueryBackendHintProvider, IQueryCacheContext, IQueryResultProviderAccess

A Refinery Interpreter engine back-end (implementation)

Constructor Summary

Constructors

Constructor	Description
InterpreterEngineImpl(QueryScope scope)
InterpreterEngineImpl(QueryScope scope, InterpreterEngineOptions engineOptions)

Method Summary

Modifier and Type	Method	Description
void	addLifecycleListener(InterpreterEngineLifecycleListener listener)	Add an engine lifecycle listener to this engine instance.
<Match extends IPatternMatch> void	addMatchUpdateListener(InterpreterMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener, boolean fireNow)	Registers low-level callbacks for match appearance and disappearance on this pattern matcher.
void	addModelUpdateListener(InterpreterModelUpdateListener listener)	Add an model update event listener to this engine instance (that fires its callbacks according to its notification level).
<V> V	delayUpdatePropagation(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.
void	dispose()	Completely disconnects and dismantles the engine.
void	flushChanges()
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.
Set<? extends InterpreterMatcher<? extends IPatternMatch>>	getCurrentMatchers()	Access a copy of available InterpreterMatcher pattern matchers.
InterpreterEngineOptions	getEngineOptions()	Returns the immutable InterpreterEngineOptions of the engine.
<Matcher extends InterpreterMatcher<? extends IPatternMatch>> Matcher	getExistingMatcher(IQuerySpecification<Matcher> querySpecification)	Access an existing pattern matcher based on a IQuerySpecification.
<Matcher extends InterpreterMatcher<? extends IPatternMatch>> Matcher	getExistingMatcher(IQuerySpecification<Matcher> querySpecification, QueryEvaluationHint optionalOverrideHints)	Access an existing pattern matcher based on a IQuerySpecification, and optional hints override.
final org.apache.log4j.Logger	getLogger()
InterpreterMatcher<? extends IPatternMatch>	getMatcher(String patternFQN)	Access a pattern matcher for the graph pattern with the given fully qualified name.
<Matcher extends InterpreterMatcher<? extends IPatternMatch>> Matcher	getMatcher(IQuerySpecification<Matcher> querySpecification)	Access a pattern matcher based on a IQuerySpecification.
<Matcher extends InterpreterMatcher<? 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.
IQueryBackend	getQueryBackend(IQueryBackendFactory iQueryBackendFactory)	Provides access to the selected query backend component of the Refinery Interpreter engine.
QueryEvaluationHint	getQueryEvaluationHint(PQuery query)	Suggests query evaluation hints regarding a query.
IQueryResultProvider	getResultProvider(IQuerySpecification<?> query)	Returns an internal interface towards the query backend to feed the matcher with results.
IQueryResultProvider	getResultProvider(IQuerySpecification<?> query, QueryEvaluationHint hint)	Returns an internal interface towards the query backend to feed the matcher with results.
IQueryResultProvider	getResultProvider(PQuery query, QueryEvaluationHint overrideHints)	Get a result provider for the given PQuery, which conforms the capabilities requested by the given QueryEvaluationHint object.
IQueryResultProvider	getResultProviderOfMatcher(InterpreterMatcher<? extends IPatternMatch> matcher)	Return the underlying result provider for the given matcher.
QueryScope	getScope()
boolean	isDisposed()	Returns true if the AdvancedInterpreterEngine.dispose() method was called on this engine previously.
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.
boolean	isUpdatePropagationDelayed()	Returns true if the update propagation in this engine is currently delayed, false otherwise.
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(InterpreterEngineLifecycleListener listener)	Remove an existing lifecycle listener from this engine instance.
<Match extends IPatternMatch> void	removeMatchUpdateListener(InterpreterMatcher<Match> matcher, IMatchUpdateListener<? super Match> listener)	Remove an existing match update event listener to this engine instance.
void	removeModelUpdateListener(InterpreterModelUpdateListener listener)	Remove an existing model update event listener to this engine instance.
void	wipe()	Discards any pattern matcher caches and forgets known patterns.
<T> T	withFlushingChanges(Supplier<T> callback)

Methods inherited from class tools.refinery.interpreter.api.AdvancedInterpreterEngine

createUnmanagedEngine, createUnmanagedEngine, from

Methods inherited from class tools.refinery.interpreter.api.InterpreterEngine

getRegisteredQuerySpecifications

Methods inherited from class java.lang.Object

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

Constructor Details

InterpreterEngineImpl

public InterpreterEngineImpl(QueryScope scope,
 InterpreterEngineOptions engineOptions)

Parameters:

scope -

engineDefaultHint -

Since:

1.4

InterpreterEngineImpl

public InterpreterEngineImpl(QueryScope scope)

Parameters:

scope -

manager - null if unmanaged

engineDefaultHint -

Method Details

isUpdatePropagationDelayed

public boolean isUpdatePropagationDelayed()

Description copied from class: AdvancedInterpreterEngine

Returns true if the update propagation in this engine is currently delayed, false otherwise.

Specified by:

isUpdatePropagationDelayed in class AdvancedInterpreterEngine

delayUpdatePropagation

public <V> V delayUpdatePropagation(Callable<V> callable)
                             throws InvocationTargetException

Description copied from class: AdvancedInterpreterEngine

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.

Specified by:

delayUpdatePropagation in class AdvancedInterpreterEngine

Parameters:

callable - the callable to be executed

Returns:

the result of the callable

Throws:

InvocationTargetException

flushChanges

public void flushChanges()

Specified by:

flushChanges in class InterpreterEngine

withFlushingChanges

public <T> T withFlushingChanges(Supplier<T> callback)

Specified by:

withFlushingChanges in class InterpreterEngine

getCurrentMatchers

public Set<? extends InterpreterMatcher<? extends IPatternMatch>> getCurrentMatchers()

Description copied from class: InterpreterEngine

Access a copy of available InterpreterMatcher pattern matchers.

Specified by:

getCurrentMatchers in class InterpreterEngine

Returns:

a copy of the set of currently available pattern matchers registered on this engine instance

getMatcher

public <Matcher extends InterpreterMatcher<? extends IPatternMatch>>
Matcher getMatcher(IQuerySpecification<Matcher> querySpecification)

Description copied from class: InterpreterEngine

Access a pattern matcher based on a IQuerySpecification. Multiple calls will return the same matcher.

Specified by:

getMatcher in class InterpreterEngine

Parameters:

querySpecification - a IQuerySpecification that describes a Refinery Interpreter query specification

Returns:

a pattern matcher corresponding to the specification

getMatcher

public <Matcher extends InterpreterMatcher<? extends IPatternMatch>>
Matcher getMatcher(IQuerySpecification<Matcher> querySpecification,
 QueryEvaluationHint optionalEvaluationHints)

Description copied from class: AdvancedInterpreterEngine

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.

Specified by:

getMatcher in class AdvancedInterpreterEngine

Parameters:

querySpecification - a IQuerySpecification that describes a Refinery Interpreter 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

getExistingMatcher

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

Description copied from class: InterpreterEngine

Access an existing pattern matcher based on a IQuerySpecification.

Specified by:

getExistingMatcher in class InterpreterEngine

Parameters:

querySpecification - a IQuerySpecification that describes a Refinery Interpreter query specification

Returns:

a pattern matcher corresponding to the specification, null if a matcher does not exist yet.

getExistingMatcher

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

Description copied from class: AdvancedInterpreterEngine

Access an existing pattern matcher based on a IQuerySpecification, and optional hints override.

Specified by:

getExistingMatcher in class AdvancedInterpreterEngine

Parameters:

querySpecification - a IQuerySpecification that describes a Refinery Interpreter 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.

getMatcher

public InterpreterMatcher<? extends IPatternMatch> getMatcher(String patternFQN)

Description copied from class: InterpreterEngine

Access a pattern matcher for the graph pattern with the given fully qualified name. Will succeed only if a query specification for this fully qualified name has been generated and registered. Multiple calls will return the same matcher unless the registered specification changes.

Specified by:

getMatcher in class InterpreterEngine

Parameters:

patternFQN - the fully qualified name of a Refinery Interpreter query specification

Returns:

a pattern matcher corresponding to the specification

getBaseIndex

public IBaseIndex getBaseIndex()

Description copied from class: InterpreterEngine

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

If using an

invalid reference

EMFScope

, consider

invalid reference

EMFScope#extractUnderlyingEMFIndex(InterpreterEngine)

instead to access EMF-specific details.

Specified by:

getBaseIndex in class InterpreterEngine

Returns:

the baseIndex the NavigationHelper maintaining the base index

getLogger

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

getQueryBackend

public IQueryBackend getQueryBackend(IQueryBackendFactory iQueryBackendFactory)

Provides access to the selected query backend component of the Refinery Interpreter engine.

Specified by:

getQueryBackend in class AdvancedInterpreterEngine

dispose

public void dispose()

Description copied from class: AdvancedInterpreterEngine

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

invalid reference

#isManaged()

), as there may be other clients using it.

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

Specified by:

dispose in class AdvancedInterpreterEngine

wipe

public void wipe()

Description copied from class: AdvancedInterpreterEngine

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

invalid reference

#isManaged()

), as there may be other clients using it.

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

Specified by:

wipe in class AdvancedInterpreterEngine

isTainted

public boolean isTainted()

Description copied from class: AdvancedInterpreterEngine

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

Specified by:

isTainted in class AdvancedInterpreterEngine

Returns:

the tainted state

addMatchUpdateListener

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

Description copied from class: AdvancedInterpreterEngine

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.

Performance note: expected to be much more efficient than polling at

invalid reference

#addCallbackAfterUpdates(Runnable)

, but prone to "signal hazards", e.g. spurious match appearances that will disappear immediately afterwards.

The callback can be unregistered via

invalid reference

#removeCallbackOnMatchUpdate(IMatchUpdateListener)

.

Specified by:

addMatchUpdateListener in class AdvancedInterpreterEngine

Parameters:

matcher - the InterpreterMatcher 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 InterpreterMatcher.forEachMatch(IMatchProcessor).

removeMatchUpdateListener

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

Description copied from class: AdvancedInterpreterEngine

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

Specified by:

removeMatchUpdateListener in class AdvancedInterpreterEngine

Parameters:

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

listener - the IMatchUpdateListener that should not receive the callbacks anymore

addModelUpdateListener

public void addModelUpdateListener(InterpreterModelUpdateListener listener)

Description copied from class: AdvancedInterpreterEngine

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

Specified by:

addModelUpdateListener in class AdvancedInterpreterEngine

Parameters:

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

removeModelUpdateListener

public void removeModelUpdateListener(InterpreterModelUpdateListener listener)

Description copied from class: AdvancedInterpreterEngine

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

Specified by:

removeModelUpdateListener in class AdvancedInterpreterEngine

Parameters:

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

addLifecycleListener

public void addLifecycleListener(InterpreterEngineLifecycleListener listener)

Description copied from class: AdvancedInterpreterEngine

Add an engine lifecycle listener to this engine instance.

Specified by:

addLifecycleListener in class AdvancedInterpreterEngine

Parameters:

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

removeLifecycleListener

public void removeLifecycleListener(InterpreterEngineLifecycleListener listener)

Description copied from class: AdvancedInterpreterEngine

Remove an existing lifecycle listener from this engine instance.

Specified by:

removeLifecycleListener in class AdvancedInterpreterEngine

Parameters:

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

getResultProvider

public IQueryResultProvider getResultProvider(IQuerySpecification<?> query)

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:

InterpreterRuntimeException

getResultProvider

public IQueryResultProvider getResultProvider(IQuerySpecification<?> query,
 QueryEvaluationHint hint)

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:

InterpreterRuntimeException

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)

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

invalid reference

#getQueryBackend()

of the returned provider

Specified by:

getCachingResultProvider in interface IQueryCacheContext

getQueryEvaluationHint

public QueryEvaluationHint getQueryEvaluationHint(PQuery query)

Description copied from interface: IQueryBackendHintProvider

Suggests query evaluation hints regarding a query. The returned hints reflects the default hints of the query engine merged with the hints provided by the pattern itself. These can be overridden via specific advanced API of the engine.

Specified by:

getQueryEvaluationHint in interface IQueryBackendHintProvider

prepareGroup

public void prepareGroup(IQueryGroup queryGroup,
 QueryEvaluationHint optionalEvaluationHints)

Description copied from class: AdvancedInterpreterEngine

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 AdvancedInterpreterEngine

Parameters:

queryGroup - a IQueryGroup identifying a set of Refinery interpreter queries

optionalEvaluationHints - additional / overriding options on query evaluation; passing null means default options associated with each query

getScope

public QueryScope getScope()

Specified by:

getScope in class InterpreterEngine

Returns:

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

getEngineOptions

public InterpreterEngineOptions getEngineOptions()

Description copied from class: AdvancedInterpreterEngine

Returns the immutable InterpreterEngineOptions of the engine.

Specified by:

getEngineOptions in class AdvancedInterpreterEngine

Returns:

the engine options

getResultProviderOfMatcher

public IQueryResultProvider getResultProviderOfMatcher(InterpreterMatcher<? extends IPatternMatch> matcher)

Description copied from class: AdvancedInterpreterEngine

Return the underlying result provider for the given matcher.

Specified by:

getResultProviderOfMatcher in class AdvancedInterpreterEngine

getResultProvider

public IQueryResultProvider getResultProvider(PQuery query,
 QueryEvaluationHint overrideHints)

Description copied from interface: IQueryResultProviderAccess

Get a result provider for the given PQuery, which conforms the capabilities requested by the given QueryEvaluationHint object.

Specified by:

getResultProvider in interface IQueryResultProviderAccess

isDisposed

public boolean isDisposed()

Description copied from class: AdvancedInterpreterEngine

Returns true if the AdvancedInterpreterEngine.dispose() method was called on this engine previously.

Specified by:

isDisposed in class AdvancedInterpreterEngine