Difference between revisions of "VIATRA/Query/UserDocumentation/API/RunOnce"

Latest revision as of 15:25, 14 November 2017

Old information
This page is not updated anymore; for more up-to-date details look at the query api documentation at https://www.eclipse.org/viatra/documentation/query-api.html instead.

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();