Class ViatraQueryEngine
- java.lang.Object
-
- org.eclipse.viatra.query.runtime.api.ViatraQueryEngine
-
- Direct Known Subclasses:
AdvancedViatraQueryEngine
public abstract class ViatraQueryEngine extends java.lang.Object
A Viatra Query (incremental) evaluation engine, attached to a model such as an EMF resource. The engine hosts pattern matchers, and will listen on model update notifications stemming from the given model in order to maintain live results.By default, ViatraQueryEngines do not need to be separately disposed; they will be garbage collected along with the model. Advanced users: see
AdvancedViatraQueryEngine
if you want fine control over the lifecycle of an engine.Pattern matchers within this engine may be instantiated in the following ways:
- Recommended: instantiate the specific matcher class generated for the pattern by e.g. MyPatternMatcher.on(engine).
- Use
getMatcher(IQuerySpecification)
if the pattern-specific generated matcher API is not available. - Advanced: use the query specification associated with the generated matcher class to achieve the same.
IQueryGroup
) can be initialized together before usage; this may improve the performance of pattern matcher construction by trying to gather all necessary information from the model in one go. Note that no such improvement is to be expected if the engine is specifically constructed in wildcard mode, an option available in some scope implementations (seeEMFScope(Notifier, BaseIndexOptions)
andBaseIndexOptions#withWildcardMode(boolean)
).- No Extend:
- This class is not intended to be subclassed by clients.
-
-
Constructor Summary
Constructors Constructor Description ViatraQueryEngine()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract IBaseIndex
getBaseIndex()
Provides access to the internal base index component of the engine, responsible for keeping track of basic contents of the model.abstract java.util.Set<? extends ViatraQueryMatcher<? extends IPatternMatch>>
getCurrentMatchers()
Access a copy of availableViatraQueryMatcher
pattern matchers.abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>>
MatchergetExistingMatcher(IQuerySpecification<Matcher> querySpecification)
Access an existing pattern matcher based on aIQuerySpecification
.abstract ViatraQueryMatcher<? extends IPatternMatch>
getMatcher(java.lang.String patternFQN)
Access a pattern matcher for the graph pattern with the given fully qualified name.abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>>
MatchergetMatcher(IQuerySpecification<Matcher> querySpecification)
Access a pattern matcher based on aIQuerySpecification
.java.util.Set<IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>>
getRegisteredQuerySpecifications()
abstract QueryScope
getScope()
static ViatraQueryEngine
on(QueryScope scope)
Obtain a (managed)ViatraQueryEngine
to evaluate queries over a given scope specified by anQueryScope
.static ViatraQueryEngine
on(QueryScope scope, ViatraQueryEngineOptions options)
Obtain a (managed)ViatraQueryEngine
to evaluate queries over a given scope specified by anQueryScope
.
-
-
-
Method Detail
-
on
public static ViatraQueryEngine on(QueryScope scope)
Obtain a (managed)ViatraQueryEngine
to evaluate queries over a given scope specified by anQueryScope
.For a given matcher scope, the same engine will be returned to any client. This facilitates the reuse of internal caches of the engine, greatly improving performance.
The lifecycle of this engine is centrally managed, and will not be disposed as long as the model is retained in memory. The engine will be garbage collected along with the model.
Advanced users: see
AdvancedViatraQueryEngine.createUnmanagedEngine(QueryScope)
to obtain a private, unmanaged engine that is not shared with other clients and allows tight control over its lifecycle.- Parameters:
scope
- the scope of query evaluation; the definition of the set of model elements that this engine is operates on. Provide e.g. aEMFScope
for evaluating queries on an EMF model.- Returns:
- a (managed)
ViatraQueryEngine
instance
-
on
public static ViatraQueryEngine on(QueryScope scope, ViatraQueryEngineOptions options)
Obtain a (managed)ViatraQueryEngine
to evaluate queries over a given scope specified by anQueryScope
.For a given matcher scope, the same engine will be returned to any client. This facilitates the reuse of internal caches of the engine, greatly improving performance.
The lifecycle of this engine is centrally managed, and will not be disposed as long as the model is retained in memory. The engine will be garbage collected along with the model.
Advanced users: see
AdvancedViatraQueryEngine.createUnmanagedEngine(QueryScope)
to obtain a private, unmanaged engine that is not shared with other clients and allows tight control over its lifecycle.- Parameters:
scope
- the scope of query evaluation; the definition of the set of model elements that this engine is operates on. Provide e.g. aEMFScope
for evaluating queries on an EMF model.- Returns:
- a (managed)
ViatraQueryEngine
instance - Since:
- 1.4
-
getBaseIndex
public abstract IBaseIndex getBaseIndex()
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
, considerEMFScope.extractUnderlyingEMFIndex(ViatraQueryEngine)
instead to access EMF-specific details.- Returns:
- the baseIndex the NavigationHelper maintaining the base index
- Throws:
ViatraQueryRuntimeException
- if the base index could not be constructed
-
getMatcher
public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getMatcher(IQuerySpecification<Matcher> querySpecification)
Access a pattern matcher based on aIQuerySpecification
. Multiple calls will return the same matcher.- Parameters:
querySpecification
- aIQuerySpecification
that describes a VIATRA query specification- Returns:
- a pattern matcher corresponding to the specification
- Throws:
ViatraQueryRuntimeException
- if the matcher could not be initialized
-
getMatcher
public abstract ViatraQueryMatcher<? extends IPatternMatch> getMatcher(java.lang.String patternFQN)
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.- Parameters:
patternFQN
- the fully qualified name of a VIATRA query specification- Returns:
- a pattern matcher corresponding to the specification
- Throws:
ViatraQueryRuntimeException
- if the matcher could not be initialized
-
getExistingMatcher
public abstract <Matcher extends ViatraQueryMatcher<? extends IPatternMatch>> Matcher getExistingMatcher(IQuerySpecification<Matcher> querySpecification)
Access an existing pattern matcher based on aIQuerySpecification
.- Parameters:
querySpecification
- aIQuerySpecification
that describes a VIATRA query specification- Returns:
- a pattern matcher corresponding to the specification,
null
if a matcher does not exist yet.
-
getCurrentMatchers
public abstract java.util.Set<? extends ViatraQueryMatcher<? extends IPatternMatch>> getCurrentMatchers()
Access a copy of availableViatraQueryMatcher
pattern matchers.- Returns:
- a copy of the set of currently available pattern matchers registered on this engine instance
-
getRegisteredQuerySpecifications
public java.util.Set<IQuerySpecification<? extends ViatraQueryMatcher<? extends IPatternMatch>>> getRegisteredQuerySpecifications()
-
getScope
public abstract QueryScope getScope()
- Returns:
- the scope of query evaluation; the definition of the set of model elements that this engine is operates on.
-
-