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

Revision as of 10:38, 5 December 2013

Overview

This page describes how EMF-IncQuery 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 EMF-IncQuery, 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/incquery/org.eclipse.incquery.examples.git/tree/minilibrary Most notably,

• the patterns are found in eiqlibrary.eiq
• and the API usage samples are found in RunOnceTest.java

Usage

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<IncQueryMatcher<IPatternMatch>> specification = (IQuerySpecification<IncQueryMatcher<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.