Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
VIATRA/Query/UserDocumentation/API/RunOnce
Overview
This page describes how VIATRA Query can be used to carry out one-time query evaluation which is useful in the following cases:
- You want less (steady-state) memory consumption instead of incremental evaluation.
- You have derived features that are not well-behaving, but you want to include them in queries.
- You like the query language of VIATRA Query, but you don't need incremental evaluation and the batch performance is better than the sum of model modification overheads between query usages.
These scenarios are now supported by a "run-once" query engine that will perform the evaluation on a given query and return the match set then dispose of the Rete network and base index to free up memory.
Example
The up-to-date sample source code to this page is found in Git here: http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/examples/minilibrary Most notably,
- the patterns are found in eiqlibrary.vql
- and the API usage samples are found in RunOnceTest.java
Usage
Run-once then dispose
The API of the run-once query engine is very simple, just instantiate the engine with the constructor using the proper scope (EObject, Resource or ResourceSet) and call the getAllMatches with a query specfication:
RunOnceQueryEngine engine = new RunOnceQueryEngine(notifier); // using generated query specification Collection<SumOfPagesInLibraryMatch> allMatches = engine.getAllMatches(SumOfPagesInLibraryMatcher.querySpecification()); // if you only have Pattern object IQuerySpecification<ViatraQueryMatcher<IPatternMatch>> specification = (IQuerySpecification<ViatraQueryMatcher<IPatternMatch>>) QuerySpecificationRegistry.getOrCreateQuerySpecification(BooksWithMultipleAuthorsMatcher.querySpecification().getPattern()); Collection<IPatternMatch> matches = engine.getAllMatches(specification);
Note that each invocation of getAllMatches will traverse the model completely, index the classes, features and data types that are required for the query, collect the match set than dispose the indexes.
Automatic re-sampling
In many cases, the derived features are only a small part of the queries and it would be better to keep the indices once they are built. However, in this case, we need a way to update the values of all derived features that are indexed.
The run-once query engine supports automatic re-sampling by listening to model modifications and updating values before returning match results.The following example shows how you can enable this mode:
RunOnceQueryEngine engine = new RunOnceQueryEngine(notifier); engine.setAutomaticResampling(true); // enable re-sampling mode Collection<SumOfPagesInLibraryMatch> allMatches = engine.getAllMatches(SumOfPagesInLibraryMatcher.querySpecification()); // some model modification // only re-sampling of derived features, not complete traversal allMatches = engine.getAllMatches(SumOfPagesInLibraryMatcher.querySpecification());
If you no longer need automatic re-sampling, you can turn it off. In this case the engine that was kept incrementally updated is removed from memory.
engine.setAutomaticResampling(false); // disable re-sampling mode, indices removed
Finally, if the value of derived features change without any model modifications (not recommended), you can tell the engine to run the re-sampling next time:
engine.resampleOnNextCall();