Documentation updates related to version 2.4.1
diff --git a/documentation/query-api.html b/documentation/query-api.html
index 77c3dac..7e21d1f 100644
--- a/documentation/query-api.html
+++ b/documentation/query-api.html
@@ -59,7 +59,7 @@
<ul class="sectlevel2">
<li><a href="#_match">1.1. Match</a></li>
<li><a href="#sec-querymatcher">1.2. Matcher</a></li>
-<li><a href="#_helper_classes">1.3. Helper classes</a></li>
+<li><a href="#_query_specification">1.3. Query Specification</a></li>
</ul>
</li>
<li><a href="#_lifecycle_management">2. Lifecycle management</a></li>
@@ -71,7 +71,7 @@
<li><a href="#_initialization_of_pattern_groups">3.4. Initialization of pattern groups</a></li>
</ul>
</li>
-<li><a href="#_the_viatra_query_generic_api">4. The VIATRA Query Generic API</a></li>
+<li><a href="#_parsing_patterns">4. Parsing Patterns</a></li>
<li><a href="#_viatra_query_base">5. VIATRA Query Base</a>
<ul class="sectlevel2">
<li><a href="#_extracting_reachability_paths_from_transitive_closure">5.1. Extracting reachability paths from transitive closure</a></li>
@@ -145,14 +145,26 @@
<p>A <strong>Match object</strong> represents a single match of the pattern, i.e. a tuple of objects whose members point to corresponding elements of the instance model (or scalar values) that the pattern is matched against. It is essentially a Data Transfer Object that is used to extract query result information from VIATRA Query, with an SQL analogy you could think of it as one "row" of the result set of a query. The generated fields correspond to the pattern header parameters.</p>
</div>
<div class="paragraph">
-<p>You can also use <strong>Match</strong> objects to specify fixed input parameters to a query (while other fields can be left unspecified) - analogously to a "prepared" SQL statement that accepts input parameter bindings. In this case, the input Match will act as a filter (mask) and the results of you queries will also be instances of this class (where parameters already have the values given in the input). See TODO below for further details.</p>
+<p>You can also use <strong>Match</strong> objects to specify fixed input parameters to a query (while other fields can be left unspecified) - analogously to a "prepared" SQL statement that accepts input parameter bindings. In this case, the input Match will act as a filter (mask) and the results of you queries will also be instances of this class (where parameters already have the values given in the input). See below for further details.</p>
</div>
<div class="paragraph">
<p>The code example below shows the <code>ApplicationInstancesMatch</code> class generated for the <strong>applicationInstances</strong> pattern (with a single parameter AI). The generated class implements the interface <code>IPatternMatch</code> through the <code>BasePatternMatch</code> internal implementation class.</p>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Immutable matches returned by pattern matchers never include null as a parameter value and can never change after initialized. Mutable matches, e.g. ones created for filtering uses null to represent unset values; but such matches are never returned from the matcher.
+</td>
+</tr>
+</table>
+</div>
<div id="query-api-match" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public abstract class ApplicationInstancesMatch extends BasePatternMatch {
+<pre class="highlight"><code class="language-java" data-lang="java">public abstract class ApplicationInstancesMatch extends BasePatternMatch {
/** getters and setters for each parameter */
public ApplicationInstance getAI();
public void setAI(final ApplicationInstance pAI);
@@ -199,17 +211,31 @@
<div class="paragraph">
<p>The example generated source code below demonstrates the <strong>ApplicationInstancesMatcher</strong> class generated for the <strong>eClassNames</strong> pattern from the running example. The matcher class implements the ViatraQueryMatcher generic interface, and its implementation code extends the <code>BaseGeneratedMatcher</code> internal class, inheriting several useful methods. In the listing below, we show some methods that are not actually part of generated code, but conform to the interface <code>ViatraQueryMatcher</code> and are accessible through inheritance from <code>BaseGeneratedMatcher</code>.</p>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Each function of the pattern matcher API has an overridden version that accepts a (partial) match as input parameters. These input matches may be both mutable and immutable, and can contain null values. However, VIATRA matchers always return immutable matches without null values. This means, there is no need to check for null when processing matches.
+</td>
+</tr>
+</table>
+</div>
<div id="query-api-matcher" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class EClassNamesMatcher implements ViatraQueryMatcher<EClassNamesMatch> {
+<pre class="highlight"><code class="language-java" data-lang="java">public class EClassNamesMatcher implements ViatraQueryMatcher<EClassNamesMatch> {
/** factory method **/
- public static ApplicationInstancesMatcher on(final ViatraQueryEngine engine) throws ViatraQueryException;
+ public static ApplicationInstancesMatcher on(final ViatraQueryEngine engine);
/** access to match set **/
- public Collection<ApplicationInstancesMatch> getAllMatches(); // inherited
- public Collection<ApplicationInstancesMatch> getAllMatches(final ApplicationInstance pAI);
- public ApplicationInstancesMatch getOneArbitraryMatch(); // inherited
- public ApplicationInstancesMatch getOneArbitraryMatch(final ApplicationInstance pAI);
+ public Collection<ApplicationInstancesMatch> getAllMatches(); // inherited
+ public Collection<ApplicationInstancesMatch> getAllMatches(final ApplicationInstance pAI);
+ public Stream<ApplicationInstancesMatch> streamAllMatches(); // inherited
+ public Stream<ApplicationInstancesMatch> streamAllMatches(final ApplicationInstance pAI);
+ public Optional<ApplicationInstancesMatch> getOneArbitraryMatch(); // inherited
+ public Optional<ApplicationInstancesMatch> getOneArbitraryMatch(final ApplicationInstance pAI);
public boolean hasMatch(); // inherited
public boolean hasMatch(final ApplicationInstance pAI);
public int countMatches(); // inherited
@@ -219,47 +245,56 @@
public Set<ApplicationInstance> getAllValuesOfAI() {}
/** iterate over matches using a lambda **/
- public void forEachMatch(IMatchProcessor<? super EClassNamesMatch> processor); // inherited
- public void forEachMatch(final ApplicationInstance pAI, final IMatchProcessor<? super ApplicationInstancesMatch> processor);
- public void forOneArbitraryMatch(IMatchProcessor<? super EClassNamesMatch> processor); // inherited
- public boolean forOneArbitraryMatch(final ApplicationInstance pAI, final IMatchProcessor<? super ApplicationInstancesMatch> processor) {}
+ public void forEachMatch(Consumer<? super EClassNamesMatch> processor); // inherited
+ public void forEachMatch(final ApplicationInstance pAI, final Consumer<? super ApplicationInstancesMatch> processor);
+ public void forOneArbitraryMatch(Consumer<? super EClassNamesMatch> processor); // inherited
+ public boolean forOneArbitraryMatch(final ApplicationInstance pAI, final Consumer<? super ApplicationInstancesMatch> processor) {}
/** Returns a new (partial) Match object for the matcher.
* This can be used e.g. to call the matcher with a partial match. **/
public ApplicationInstancesMatch newMatch(final ApplicationInstance pAI);
/** Access query specification */
- public static IQuerySpecification<ApplicationInstancesMatcher> querySpecification() throws ViatraQueryException;
+ public static IQuerySpecification<ApplicationInstancesMatcher> querySpecification();
}</code></pre>
</div>
</div>
+<div class="paragraph">
+<p>Starting with VIATRA 2.0 the matcher API also returns stream of matches. These streams can be used for processing the streams functionally, greatly extending the similar capabilities provided by the forEachMatch calls available since earlier version. Furthermore, relying on these streams might provide better performance: (1) the use of these streams does not necessitate the copying of the match set, and (2) the pattern matcher is allowed to postpone the match set calculation until the next match is necessary.</p>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
+The new Stream-based APIs cannot handle if the underlying model is changed during match processing. If a snapshot of the match set is required, either rely on the similar <code>getAllMatches()</code> call or collect the results of the stream in end-user code.
+</td>
+</tr>
+</table>
+</div>
</div>
<div class="sect2">
-<h3 id="_helper_classes"><a class="link" href="#_helper_classes">1.3. Helper classes</a></h3>
+<h3 id="_query_specification"><a class="link" href="#_query_specification">1.3. Query Specification</a></h3>
<div class="paragraph">
-<p><code>MatchProcessor</code></p>
-</div>
-<div class="paragraph">
-<p>The Matcher provides a function to iterate over the match set and invoke the process() method of the IMatchProcessor interface with every match. You can think of this as a "lambda" to ease typical query result processing tasks. To this end, an abstract processor class is generated, which you can override to implement the logic you would like to use. The abstract class unpacks the match variables so it can be used directly in the process() method.</p>
-</div>
-<div class="paragraph">
-<p><code>QuerySpecification</code>: A pattern-specific specification that can instantiate a Matcher class in a type-safe way. You can get an instance of it via the Matcher class’s specification() method. The recommended way to instantiate a Matcher is with an <code>ViatraQueryEngine</code>. In both cases if the pattern is already registered (with the same root in the case of the Notifier method) then only a lightweight reference is created which points to the existing engine.</p>
+<p>A pattern-specific specification that can instantiate a Matcher class in a type-safe way. You can get an instance of it via the Matcher class’s specification() method. The recommended way to instantiate a Matcher is with an <code>ViatraQueryEngine</code>. In both cases if the pattern is already registered (with the same root in the case of the Notifier method) then only a lightweight reference is created which points to the existing engine.</p>
</div>
<div class="paragraph">
<p>The code sample extends the BaseGeneratedQuerySpecification class.</p>
</div>
<div id="query-api-queryspecification" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">/**
+<pre class="highlight"><code class="language-java" data-lang="java">/**
* A pattern-specific query specification that can instantiate EClassNamesMatcher in a type-safe way.
*/
public final class ApplicationInstancesQuerySpecification extends BaseGeneratedEMFQuerySpecification<ApplicationInstancesMatcher> {
/** Singleton instance access */
- public static ApplicationInstancesQuerySpecification instance() throws ViatraQueryException;
+ public static ApplicationInstancesQuerySpecification instance();
/** Instantiate matches and matchers */
- public ApplicationInstancesMatcher instantiate() throws ViatraQueryException;
+ public ApplicationInstancesMatcher instantiate();
public ApplicationInstancesMatch newEmptyMatch();
public ApplicationInstancesMatch newMatch(final Object... parameters);
@@ -330,7 +365,7 @@
<h3 id="_loading_an_instance_model_and_executing_a_query"><a class="link" href="#_loading_an_instance_model_and_executing_a_query">3.1. Loading an instance model and executing a query</a></h3>
<div id="query-api-loadmodelandquery" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// get all matches of the pattern
+<pre class="highlight"><code class="language-java" data-lang="java">// get all matches of the pattern
// initialization
// phase 1: (managed) ViatraQueryEngine
ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource /* or resourceSet */));
@@ -351,7 +386,7 @@
</div>
<div id="query-api-matchprocessor" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">matcher2.forEachMatch(new EClassNamesProcessor() {
+<pre class="highlight"><code class="language-java" data-lang="java">matcher2.forEachMatch(new EClassNamesProcessor() {
@Override
public void process(EClass c, String n) {
results.append("\tEClass: " + c.toString() + "\n");
@@ -367,7 +402,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">matcher2.forEachMatch( matcher2.newMatch(null, "A") , new EClassNamesProcessor() {
+<pre class="highlight"><code class="language-java" data-lang="java">matcher2.forEachMatch( matcher2.newMatch(null, "A") , new EClassNamesProcessor() {
@Override
public void process(EClass c, String n) {
results.append("\tEClass with name A: " + c.toString() + "\n");
@@ -391,7 +426,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// projections
+<pre class="highlight"><code class="language-java" data-lang="java">// projections
for (EClass ec: matcher2.getAllValuesOfc(matcher2.newMatch(null,"A")))
{
results.append("\tEClass with name A: " + ec.toString() + "\n");
@@ -406,7 +441,7 @@
</div>
<div id="query-api-groupinit" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// phase 1: (managed) ViatraQueryEngine
+<pre class="highlight"><code class="language-java" data-lang="java">// phase 1: (managed) ViatraQueryEngine
ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource));
// phase 2: the group of pattern matchers
HeadlessQueries patternGroup = HeadlessQueries.instance();
@@ -426,10 +461,10 @@
</div>
</div>
<div class="sect1">
-<h2 id="_the_viatra_query_generic_api"><a class="link" href="#_the_viatra_query_generic_api">4. The VIATRA Query Generic API</a></h2>
+<h2 id="_parsing_patterns"><a class="link" href="#_parsing_patterns">4. Parsing Patterns</a></h2>
<div class="sectionbody">
<div class="paragraph">
-<p>All features provided by the generated pattern matcher API can be executed using the generic pattern matcher API of VIATRA. This generic API differs from the generated one in two key aspects:</p>
+<p>VIATRA provides an API to parse patterns from a text and creates query specifications from them that can be used similar to generated query specifications. This is based on the <strong>generic</strong> pattern matcher API that differs from the generated one in two key aspects:</p>
</div>
<div class="ulist">
<ul>
@@ -441,77 +476,58 @@
</li>
</ul>
</div>
-<div id="query-api-genericapi" class="listingblock">
-<div class="title">Example using the generic API</div>
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public String executeDemo_GenericAPI_LoadFromEIQ(String modelPath, String patternFQN) {
- final StringBuilder results = new StringBuilder();
- Resource resource = loadModel(modelPath);
- if (resource != null) {
- try {
- // get all matches of the pattern
- // create an *unmanaged* engine to ensure that noone else is going
- // to use our engine
- AdvancedViatraQueryEngine engine = AdvancedViatraQueryEngine.createUnmanagedEngine(resource);
- // instantiate a pattern matcher through the registry, by only knowing its FQN
- // assuming that there is a pattern definition registered matching 'patternFQN'
-
- Pattern p = null;
-
- // Initializing Xtext-based resource parser
- // Do not use if VIATRA Query tooling is loaded!
- EMFPatternLanguageStandaloneSetup.createInjectorAndDoEMFRegistration();
-
- //Loading pattern resource from file
- ResourceSet resourceSet = new ResourceSetImpl();
- URI fileURI = URI.createPlatformPluginURI("headlessQueries.incquery/src/headless/headlessQueries.vql", false);
- Resource patternResource = resourceSet.getResource(fileURI, true);
-
- // navigate to the pattern definition that we want
- if (patternResource != null) {
- if (patternResource.getErrors().size() == 0 && patternResource.getContents().size() >= 1) {
- EObject topElement = patternResource.getContents().get(0);
- if (topElement instanceof PatternModel) {
- for (Pattern _p : ((PatternModel) topElement).getPatterns()) {
- if (patternFQN.equals(CorePatternLanguageHelper.getFullyQualifiedName(_p))) {
- p = _p; break;
- }
- }
- }
- }
- }
- if (p == null) {
- throw new RuntimeException(String.format("Pattern %s not found", patternFQN));
- }
- // A specification builder is used to translate patterns to query specifications
- SpecificationBuilder builder = new SpecificationBuilder();
-
- // attempt to retrieve a registered query specification
- ViatraQueryMatcher<? extends IPatternMatch> matcher = engine.getMatcher(builder.getOrCreateSpecification(p));
-
- if (matcher!=null) {
- Collection<? extends IPatternMatch> matches = matcher.getAllMatches();
- prettyPrintMatches(results, matches);
- }
-
- // wipe the engine
- engine.wipe();
- // after a wipe, new patterns can be rebuilt with much less overhead than
- // complete traversal (as the base indexes will be kept)
-
- // completely dispose of the engine once's it is not needed
- engine.dispose();
- resource.unload();
- } catch (ViatraQueryException e) {
- e.printStackTrace();
- results.append(e.getMessage());
- }
- } else {
- results.append("Resource not found");
- }
- return results.toString();
-}</code></pre>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+To use this API, the code from the <code>org.eclipse.viatra.query.patternlanguage.emf</code> plug-in has to be added to the classpath (in standalone applications, rely on the Maven dependency <code>org.eclipse.viatra:viatra-query-language</code>). This will add further transitive dependencies, most notable on Xtext and Google Guice to your application.
+</td>
+</tr>
+</table>
</div>
+<div id="query-api-genericapi" class="listingblock">
+<div class="title">Using the Pattern Parser API</div>
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">final StringBuilder results = new StringBuilder();
+Resource resource = loadModel(modelURI);
+
+// Initializing Xtext-based resource parser (once per Java application)
+new EMFPatternLanguageStandaloneSetup().createInjectorAndDoEMFRegistration();
+
+// Parse pattern definition
+PatternParsingResults parseResults = PatternParserBuilder.instance()
+ .parse("import \"http://org.eclipse.viatra/model/cps\" \n"
+ + "\n"
+ + "pattern hostIpAddress(host: HostInstance, ip : java String) {\n"
+ + " HostInstance.nodeIp(host,ip);\n"
+ + "}");
+ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource));
+
+parseResults.getQuerySpecification("hostIpAddress").ifPresent(specification -> {
+ ViatraQueryMatcher<?> matcher = engine.getMatcher(specification);
+ prettyPrintMatches(results, matcher.getAllMatches());
+});
+
+return results.toString();</code></pre>
+</div>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+In VIATRA 2.1 the pattern parser API was updated to support more advanced cases, like updating previously loaded patterns (see below for details). In previous versions, the pattern parser could be initialized by calling <code>PatternParser.parser().parse(…​)</code>, but this call is deprecated in VIATRA version 2.1.
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>The pattern parser can be initialized in two modes: a <em>basic mode</em> (initialized with calling either the <code>parse</code> or <code>build</code> methods of the <code>PatternParserBuilder</code> class does not supports updating query definitions after being loaded; while in <em>advanced mode</em> (initialized with the <code>buildAdvanced</code> method of <code>PatterParserBuilder</code>) previously loaded specifications can be updated, and the resulting query specifications are updated (and revalidated) as necessary. Given the more complex infrastructure required for <em>advanced mode</em>, it is recommended to rely on the <em>basic mode</em> unless reparsing pattern is truly necessary, such as when integrating VIATRA in an environment where the user may specify custom queries with complex dependencies between them.</p>
</div>
</div>
</div>
@@ -599,7 +615,7 @@
</div>
<div id="query-runtime-filteredscope" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ResourceSet resourceSet = ...; //Use a Resource Set as the root of the engine
+<pre class="highlight"><code class="language-java" data-lang="java">ResourceSet resourceSet = ...; //Use a Resource Set as the root of the engine
BaseIndexOptions options = new BaseIndexOptions().withResourceFilterConfiguration(new IBaseIndexResourceFilter() {
@Override
@@ -637,7 +653,7 @@
</div>
<div id="query-runtime-danglingfree" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">BaseIndexOptions options = new BaseIndexOptions().withDanglingFreeAssumption(false);
+<pre class="highlight"><code class="language-java" data-lang="java">BaseIndexOptions options = new BaseIndexOptions().withDanglingFreeAssumption(false);
ResourceSet rSet = new ResourceSetImpl();
EMFScope scope = new EMFScope(rSet, options);
ViatraQueryEngine engine = ViatraQueryEngine.on(scope);</code></pre>
@@ -745,7 +761,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">search pattern minCPUs(n : java Integer) {
+<pre class="highlight"><code class="language-java" data-lang="java">search pattern minCPUs(n : java Integer) {
n == min find cpus(_hi1, #_);
}</code></pre>
</div>
@@ -781,7 +797,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IQuerySpecification<?> specification = ...;
+<pre class="highlight"><code class="language-java" data-lang="java">IQuerySpecification<?> specification = ...;
QueryEvaluationHint hint = LocalSearchHints.getDefault().setUseBase(false).build();
AdvancedViatraQueryEngine.from(queryEngine).getMatcher(specification, hint);</code></pre>
</div>
@@ -804,7 +820,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">final Map<IInputKey, Long> statistics = ..
+<pre class="highlight"><code class="language-java" data-lang="java">final Map<IInputKey, Long> statistics = ..
QueryEvaluationHint hint = LocalSearchHints.getDefault().setCostFunction(new StatisticsBasedConstraintCostFunction(){
public long countTuples(IConstraintEvaluationContext input, IInputKey supplierKey){
return statistics.get(supplierKey);
@@ -839,7 +855,7 @@
<p>As of version 1.4, it is not possible to combine different pattern matching algorithms for the evaluation of a single pattern. Either the entire search must use Rete or Local search based algorithms.</p>
</li>
<li>
-<p>The Local Search engine currently does not able to execute recursive queries. See <a href="http://bugs.eclipse.org/458278" class="bare">http://bugs.eclipse.org/458278</a> for more details.</p>
+<p>The Local Search engine currently is not able to execute recursive queries. See <a href="http://bugs.eclipse.org/458278" class="bare">http://bugs.eclipse.org/458278</a> for more details.</p>
</li>
</ul>
</div>
@@ -866,7 +882,7 @@
</ol>
</div>
<div class="paragraph">
-<p>In version 1.4 the hints are mostly used to fine tune the <a href="#sec-localsearch">local search based pattern matcher</a>, but their usage is gradually being extended. See classes <code>ReteHintOptions</code> and <code>LocalSearchHints</code> for hint options provided by the query backends.</p>
+<p>In version 1.4 the hints are mostly used to fine tune the <a href="#sec-localsearch">local search based pattern matcher</a>, but their usage is gradually being extended. See classes <code>ReteHintOptions</code> and <code>LocalSearchHints</code> for hint options provided by the query backends. As of 2.0, the <a href="#recursion-dred">delete and rederive (DRED)</a> hint option is available on the UI as well.</p>
</div>
</div>
</div>
@@ -886,7 +902,7 @@
</div>
<div id="query-runtime-registry-usage" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IQuerySpecificationRegistry registry = org.eclipse.viatra.query.runtime.registry.QuerySpecificationRegistry.getInstance();
+<pre class="highlight"><code class="language-java" data-lang="java">IQuerySpecificationRegistry registry = org.eclipse.viatra.query.runtime.registry.QuerySpecificationRegistry.getInstance();
IQuerySpecification<?> specification = registry.getDefaultView().getEntry("my.registered.query.fqn").get();</code></pre>
</div>
</div>
@@ -905,7 +921,7 @@
</div>
<div id="query-api-registry-views" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IQuerySpecificationRegistry registry = QuerySpecificationRegistry.getInstance();
+<pre class="highlight"><code class="language-java" data-lang="java">IQuerySpecificationRegistry registry = QuerySpecificationRegistry.getInstance();
// access default view
IDefaultRegistryView defaultView = registry.getDefaultView();
@@ -947,7 +963,7 @@
</div>
<div id="query-api-registry-listener" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IQuerySpecificationRegistry registry = QuerySpecificationRegistry.getInstance();
+<pre class="highlight"><code class="language-java" data-lang="java">IQuerySpecificationRegistry registry = QuerySpecificationRegistry.getInstance();
IRegistryView myView = registry.createView();
IQuerySpecificationRegistryChangeListener listener = new IQuerySpecificationRegistryChangeListener() {
@Override
@@ -977,7 +993,7 @@
</div>
<div id="query-api-registry-addspecification" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IQuerySpecificationRegistry registry = QuerySpecificationRegistry.getInstance();
+<pre class="highlight"><code class="language-java" data-lang="java">IQuerySpecificationRegistry registry = QuerySpecificationRegistry.getInstance();
// initialize your connector
IRegistrySourceConnector connector;
@@ -995,7 +1011,7 @@
</div>
<div id="query-api-registry-connectors" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IRegistrySourceConnector connector = new SpecificationMapSourceConnector("my.source.identifier", false /* do not include these in default views */);
+<pre class="highlight"><code class="language-java" data-lang="java">IRegistrySourceConnector connector = new SpecificationMapSourceConnector("my.source.identifier", true /* include these in default view; fqn clashes are errors */);
IQuerySpecification<?> specification = /* available from somewhere */
@@ -1008,6 +1024,18 @@
connector.removeQuerySpecificationProvider(specification.getFullyQualifiedName());</code></pre>
</div>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+The default view assumes all queries loaded there have a single qualified name. If this cannot ensured, the source should not be added to the default views and specific views are to be created accordingly.
+</td>
+</tr>
+</table>
+</div>
</div>
</div>
</div>
@@ -1025,7 +1053,7 @@
</div>
<div id="query-api-group-prepare" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">IQueryGroup queries = ...
+<pre class="highlight"><code class="language-java" data-lang="java">IQueryGroup queries = ...
ViatraQueryEngine engine = ...
queries.prepare(engine);</code></pre>
</div>
@@ -1035,7 +1063,7 @@
</div>
<div id="query-api-coalesce" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ViatraQueryEngine engine = ...
+<pre class="highlight"><code class="language-java" data-lang="java">ViatraQueryEngine engine = ...
engine.getBaseIndex().coalesceTraversals(new Callable<Void>() {
@Override
public Void call() throws Exception {
@@ -1053,7 +1081,7 @@
</div>
<div id="query-api-delayupdates" class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">AdvancedViatraQueryEngine engine = ...
+<pre class="highlight"><code class="language-java" data-lang="java">AdvancedViatraQueryEngine engine = ...
engine.delayUpdatePropagation(new Callable<Void>() {
@Override
public Void call() throws Exception {
@@ -1112,7 +1140,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">RunOnceQueryEngine engine = new RunOnceQueryEngine(notifier);
+<pre class="highlight"><code class="language-java" data-lang="java">RunOnceQueryEngine engine = new RunOnceQueryEngine(notifier);
// using generated query specification
Collection<SumOfPagesInLibraryMatch> allMatches = engine.getAllMatches(SumOfPagesInLibraryMatcher.querySpecification());
// if you only have Pattern object
@@ -1135,7 +1163,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">RunOnceQueryEngine engine = new RunOnceQueryEngine(notifier);
+<pre class="highlight"><code class="language-java" data-lang="java">RunOnceQueryEngine engine = new RunOnceQueryEngine(notifier);
engine.setAutomaticResampling(true); // enable re-sampling mode
Collection<SumOfPagesInLibraryMatch> allMatches = engine.getAllMatches(SumOfPagesInLibraryMatcher.querySpecification());
// some model modification
@@ -1148,7 +1176,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">engine.setAutomaticResampling(false); // disable re-sampling mode, indices removed</code></pre>
+<pre class="highlight"><code class="language-java" data-lang="java">engine.setAutomaticResampling(false); // disable re-sampling mode, indices removed</code></pre>
</div>
</div>
<div class="paragraph">
@@ -1156,7 +1184,7 @@
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">engine.resampleOnNextCall();</code></pre>
+<pre class="highlight"><code class="language-java" data-lang="java">engine.resampleOnNextCall();</code></pre>
</div>
</div>
</div>
@@ -1193,7 +1221,7 @@
<div class="content">
<pre> log4j:WARN No appenders could be found for logger (org.eclipse.viatra.query.runtime.util.ViatraQueryLoggingUtil).
log4j:WARN Please initialize the log4j system properly.</pre>
-</div>
+</div>x
</div>
<div class="paragraph">
<p>There are several cases where this can occur:</p>
diff --git a/documentation/query-language.html b/documentation/query-language.html
index f9ea2bf..d57ce69 100644
--- a/documentation/query-language.html
+++ b/documentation/query-language.html
@@ -165,7 +165,7 @@
<p>Enclose pattern definitions in a package: <code>package my.own.patterns</code></p>
</li>
<li>
-<p>Import declarations are required to indicate which EMF packages and Java classes are referenced in the query definitions.</p>
+<p>Import declarations are required to indicate which EMF packages, VQL patterns from other files and Java classes are referenced in the query definitions.</p>
<div class="ulist">
<ul>
<li>
@@ -183,6 +183,21 @@
<li>
<p>Note that here and elsewhere, a caret character can be used to escape keywords, such as java.</p>
</li>
+<li>
+<p>Note that similar to how Java handles subpackages they also have to be imported with fully qualified names.</p>
+</li>
+<li>
+<p>Patterns of other files can also be imported by their fully qualified names:</p>
+</li>
+<li>
+<p><code>import my.imported.package.PatternName</code></p>
+</li>
+<li>
+<p>Only public patterns can be imported</p>
+</li>
+<li>
+<p>Patterns defined in the same package as the current file are automatically imported.</p>
+</li>
</ul>
</div>
</li>
@@ -216,6 +231,9 @@
<li>
<p>Type declarations are optional, but <strong>strongly recommended</strong> to use. In future versions of VIATRA, they might become mandatory. We recommend using EClass types for all EObject parameter variables, and, since version 1.4, Java class types (prefixed with the <code>java</code> keyword) for attribute-valued and computed parameters.</p>
</li>
+<li>
+<p>It is possible to have a pattern without parameters - these pattern can be used to check whether the model structure described by the pattern body exists in the model or not.</p>
+</li>
</ul>
</div>
</li>
@@ -887,7 +905,7 @@
</table>
</div>
<div class="paragraph">
-<p>The first step is to provide a class that implements the Java interface <a href="http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/query/plugins/org.eclipse.viatra.query.runtime.matchers/src/org/eclipse/viatra/query/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java">IMultisetAggregationOperator</a> by subclassing <a href="http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/query/plugins/org.eclipse.viatra.query.runtime.matchers/src/org/eclipse/viatra/query/runtime/matchers/psystem/aggregations/AbstractMultisetAggregationOperator.java">AbstractMultisetAggregationOperator</a>. An instance of your class would represent a mathematical aggregation operator (independently of any context, such as patterns, variables, etc.) and provide incremental computation of the aggregate results from a changing multiset of values. Please read the Javadoc carefully to ensure that you meet all assumed contracts; you may also want to inspect the provided built-in implementors to gain a better understanding.</p>
+<p>The first step is to provide a class that implements the Java interface <a href="http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/query/plugins/org.eclipse.viatra.query.runtime.matchers/src/org/eclipse/viatra/query/runtime/matchers/psystem/aggregations/IMultisetAggregationOperator.java">IMultisetAggregationOperator</a>. An instance of your class would represent a mathematical aggregation operator (independently of any context, such as patterns, variables, etc.) and provide incremental computation of the aggregate results from a changing multiset of values. Please read the Javadoc carefully to ensure that you meet all assumed contracts; you may also want to inspect the provided built-in implementors to gain a better understanding.</p>
</div>
<div class="paragraph">
<p>In order to actually use your aggregator in the query language, the second step is to provide an implementation of <a href="http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/query/plugins/org.eclipse.viatra.query.runtime.matchers/src/org/eclipse/viatra/query/runtime/matchers/psystem/aggregations/IAggregatorFactory.java">IAggregatorFactory</a> that must be on the classpath of the query project in order to be accessible from queries. It is customary to take exception to Java naming conventions and use a lower-case class name, as the name of this class will be the aggregator operator name in the query language. The role of this class is twofold:</p>
