Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

< VIATRA‎ | Query
(Helper classes)
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{caution|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  ==
 
== Overview  ==
  
This page presents the basics of EMF-IncQuery's Java API. It supersedes the following contents of the original documentation on IncQuery.net:
+
This page presents the basics of VIATRA Query's Java API.
*http://incquery.net/incquery/new/examples/application (Headless example)
+
*http://incquery.net/incquery/documentation/api (Pattern Matcher API documentation)
+
*http://incquery.net/incquery/new/examples/school#Generated_code_overview (The latter part of the School example)
+
  
The contents only over the basic use-cases. For advanced features, see [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]].
+
The contents only over the basic use-cases. For advanced features, see [[VIATRA/Query/UserDocumentation/API/Advanced|Advanced API features]].  
  
=== Running example ===
+
=== Running example ===
All the code examples and explanations will be given in the context of the [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless]] 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/headless
+
All the code examples and explanations will be given in the context of the [[VIATRA/Query/UserDocumentation/HeadlessExecution|Headless]] 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/headless Most notably,  
Most notably,  
+
 
* the patterns are found in [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/headlessQueries.incquery/src/headless/headlessQueries.eiq headlessQueries.eiq]
+
*the patterns are found in [http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/examples/headless/org.eclipse.viatra.query.application.queries/src/org/eclipse/viatra/query/application/queries/headlessQueries.vql headlessQueries.vql]  
* and the API usage samples are found in [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/org.eclipse.incquery.application/src/org/eclipse/incquery/application/common/IncQueryHeadless.java IncQueryHeadless.java]
+
*and the API usage samples are found in [http://git.eclipse.org/c/viatra/org.eclipse.viatra.git/tree/examples/headless/org.eclipse.viatra.query.application/src/org/eclipse/viatra/query/application/common/ViatraQueryHeadless.java ViatraQueryHeadless.java]
  
 
=== Javadoc  ===
 
=== Javadoc  ===
The most up-to-date Javadocs for the EMF-IncQuery API can be found online at http://eclipse.org/incquery/javadoc/
 
  
== EMF-IncQuery Java API  ==
+
The most up-to-date Javadocs for the VIATRA Query API can be found online at https://wiki.eclipse.org/VIATRA/Releases.  
The most typical way of using the EMF-IncQuery API is to make use of the generated code that is found in the "src-gen" folder of your EMF-IncQuery project. This generated code provides easy and typesafe access to most of EMF-IncQuery's features from Java code. The only important thing to keep in mind is that the generated code is available only when your EMF-IncQuery project is loaded into the Eclipse runtime, i.e. for working with the generated code for development purposes you'll need to use Eclipse Application launch configurations.
+
  
EMF-IncQuery also supports a "dynamic", generic API that allows to make use of patterns without relying on the generated code. The generic API shares functionality with the base classes of the "generated" API, and for most scenarios there is no performance difference between the two. A notable exception for this rule of thumb are '''check() expressions''', where the generated code that is invoked through the generated API will execute the Java code instead of interpreting Xbase.
+
== VIATRA Query Java API ==
  
In this wiki, we will present a simple introduction to the basics of the "generated" API, to introduce features that will help you to integrate EMF-IncQuery queries into your Java application. The [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]] page discusses the usage of the dynamic and generic APIs.  
+
The most typical way of using the VIATRA Query API is to make use of the generated code that is found in the "src-gen" folder of your VIATRA Query project. This generated code provides easy and type-safe access to most of VIATRA Query's features from Java code. The only important thing to keep in mind is that the generated code is available only when your VIATRA Query project is loaded into the Eclipse runtime, i.e. for working with the generated code for development purposes you'll need to use Eclipse Application launch configurations.
 +
 
 +
VIATRA Query also supports a "dynamic", generic API that allows to make use of patterns without relying on the generated code. The generic API shares functionality with the base classes of the "generated" API, and for most scenarios there is no performance difference between the two. A notable exception for this rule of thumb are '''check() expressions''', where the generated code that is invoked through the generated API will execute the Java code instead of interpreting Xbase.
 +
 
 +
In this wiki, we will present a simple introduction to the basics of the "generated" API, to introduce features that will help you to integrate VIATRA Query queries into your Java application. The [[VIATRA/Query/UserDocumentation/API/Advanced|Advanced API features]] page discusses the usage of the dynamic and generic APIs.  
  
 
=== Most important classes and their relationships  ===
 
=== Most important classes and their relationships  ===
For every pattern definition, the EMF-IncQuery tooling generates a '''Match''', a '''Matcher''', into a Java package that corresponds to the package of the pattern definition, constituting the public API that is intended for client code usage. In addition, some helper classes are generated into the ".uitl" subpackage:
 
* if check expressions are present in your pattern definition, several '''Evaluator''' classes are also generated.
 
* a '''MatchProcessor''' class is generated to aid match set traversal.
 
* Finally, a '''QuerySpecification''' helper class is also generated that supports advanced lifecycle management (which is not necessary in most cases).
 
  
In order to fully understand the capabilities of these classes, it is a good idea to read through the [[EMFIncQuery/UserDocumentation/API/Advanced#The_IncQuery_Generic_API|Generic API]] section of the [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]] page.
+
For every pattern definition, the VIATRA Query tooling generates a '''Match''', a '''Matcher''', into a Java package that corresponds to the package of the pattern definition, constituting the public API that is intended for client code usage. In addition, some helper classes are generated into the ".util" subpackage:
 +
 
 +
*if check expressions are present in your pattern definition, several '''Evaluator''' classes are also generated.
 +
*a '''MatchProcessor''' class is generated to aid match set traversal.
 +
*Finally, a '''QuerySpecification''' helper class is also generated that supports advanced lifecycle management (which is not necessary in most cases).
 +
 
 +
In order to fully understand the capabilities of these classes, it is a good idea to read through the [[VIATRA/Query/UserDocumentation/API/Advanced#The_VIATRA_Query_Generic_API|Generic API]] section of the [[VIATRA/Query/UserDocumentation/API/Advanced|Advanced API features]] page.  
 +
 
 +
==== Match  ====
  
==== Match ====
+
A '''Match object''' 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.  
A '''Match object''' 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 EMF-IncQuery, 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.  
+
  
You can also use '''Match''' 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.
+
You can also use '''Match''' 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.  
  
The code example below shows the '''EClassNamesMatch''' class generated for the '''eClassNames''' pattern of the running example. The generated class implements the interface [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IPatternMatch.html IPatternMatch] and extends the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/impl/BasePatternMatch.html BasePatternMatch] internal implementation class.
+
The code example below shows the '''EClassNamesMatch''' class generated for the '''eClassNames''' pattern of the running example. The generated class implements the interface IPatternMatch and extends the BasePatternMatch internal implementation class.  
  
 
<source lang="java">
 
<source lang="java">
Line 70: Line 72:
 
   static final class Mutable extends EClassNamesMatch {}
 
   static final class Mutable extends EClassNamesMatch {}
 
}
 
}
</source>
+
</source>  
  
==== Matcher ====
+
==== Matcher ====
The '''Matcher''' is the main entry point of the EMF-IncQuery API, with pattern-specific query methods. It provides access to the three key features of EMF-IncQuery:
+
* First of all it provides means to '''initialize a pattern matcher''' for a given EMF instance model which can either be a Resource, a ResourceSet, or an EObject (in this latter case, the scope of the matching will be the containment tree under the passed EObject). We recommend the use of ResourceSets if possible to avoid cross-reference related issues.
+
* After the initialization of the engine, the Matcher provides '''getter methods to retrieve the contents of the match set'''. For easy iteration over the match set it provides a convenience method (forEachMatch) as well, as this is the most frequent use case in our observation. Of course it contains other handy features (e.g.: countMatches, hasMatch) to help integration.
+
* Finally, it provides means to efficiently '''track the changes in the match set''' in an event-driven fashion.
+
  
The example generated source code below demonstrates the '''EClassNamesMatcher''' class generated for the '''eClassNames''' pattern from the running example.
+
The '''Matcher''' is the main entry point of the VIATRA Query API, with pattern-specific query methods. It provides access to the three key features of VIATRA Query:
The matcher class implements the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IncQueryMatcher.html IncQueryMatcher] generic interface, and its implementation code extends the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/impl/BaseGeneratedMatcher.html BaseGeneratedMatcher] 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 !IncQueryMatcher and are accessible through interitance from !BaseGeneratedMatcher.  
+
 
<source lang="java">
+
*First of all it provides means to '''initialize a pattern matcher''' for a given EMF instance model which can either be a Resource, a ResourceSet, or an EObject (in this latter case, the scope of the matching will be the containment tree under the passed EObject). We recommend the use of ResourceSets if possible to avoid cross-reference related issues.
public class EClassNamesMatcher implements IncQueryMatcher<EClassNamesMatch> {
+
*After the initialization of the engine, the Matcher provides '''getter methods to retrieve the contents of the match set'''. For easy iteration over the match set it provides a convenience method (forEachMatch) as well, as this is the most frequent use case in our observation. Of course it contains other handy features (e.g.: countMatches, hasMatch) to help integration.
 +
*Finally, it provides means to efficiently '''track the changes in the match set''' in an event-driven fashion.
 +
 
 +
The example generated source code below demonstrates the '''EClassNamesMatcher''' class generated for the '''eClassNames''' pattern from the running example. The matcher class implements the ViatraQueryMatcher generic interface, and its implementation code extends the BaseGeneratedMatcher 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&nbsp;!ViatraQueryMatcher and are accessible through inheritance from&nbsp;!BaseGeneratedMatcher. <source lang="java">
 +
public class EClassNamesMatcher implements ViatraQueryMatcher<EClassNamesMatch> {
 
   /** initializer methods **/
 
   /** initializer methods **/
   public EClassNamesMatcher(IncQueryEngine engine) throws IncQueryException {}
+
   public EClassNamesMatcher(ViatraQueryEngine engine) throws ViatraQueryException {}
  
 
   /** access to match set **/
 
   /** access to match set **/
Line 113: Line 115:
 
   public EClassNamesMatch newMatch(EClass pC, String pN) {}
 
   public EClassNamesMatch newMatch(EClass pC, String pN) {}
 
}
 
}
</source>
+
</source>  
  
 +
<br>
  
 +
==== Helper classes  ====
  
==== Helper classes ====
+
*'''MatchProcessor'''
* '''MatchProcessor'''
+
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.
+
  
The source code example below implements the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IMatchProcessor.html IMatchProcessor] interface.
+
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.
<source lang="java">
+
 
 +
The source code example below implements the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IMatchProcessor.html IMatchProcessor] interface. <source lang="java">
 
/**
 
/**
 
  * A match processor tailored for the headless.eClassNames pattern.
 
  * A match processor tailored for the headless.eClassNames pattern.
Line 133: Line 136:
 
}
 
}
 
</source>  
 
</source>  
*'''Evaluator''': If your pattern contains check expressions an evaluator java code is generated from it. It is used by the engine during a query to evaluate the expression’s result. In most cases you don’t need to deal with these classes.
 
*'''QuerySpecification''': 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 '''IncQueryEngine'''. 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.
 
  
The code sample extends the [http://eclipse.org/incquery/javadoc/milestones/m3/org/eclipse/incquery/runtime/api/impl/BaseGeneratedQuerySpecification.html BaseGeneratedQuerySpecification] class.
+
*'''Evaluator''': If your pattern contains check expressions an evaluator java code is generated from it. It is used by the engine during a query to evaluate the expression’s result. In most cases you don’t need to deal with these classes.
<source lang="java">
+
*'''QuerySpecification''': 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 '''ViatraQueryEngine'''. 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.
 +
 
 +
The code sample extends the BaseGeneratedQuerySpecification class. <source lang="java">
 
/**
 
/**
 
  * A pattern-specific query specification that can instantiate EClassNamesMatcher in a type-safe way.
 
  * A pattern-specific query specification that can instantiate EClassNamesMatcher in a type-safe way.
Line 143: Line 146:
 
public final class EClassNamesQuerySpecification extends BaseGeneratedQuerySpecification<EClassNamesMatcher> {
 
public final class EClassNamesQuerySpecification extends BaseGeneratedQuerySpecification<EClassNamesMatcher> {
 
   /** @return the singleton instance of the query specification **/
 
   /** @return the singleton instance of the query specification **/
   public static EClassNamesQuerySpecification instance() throws IncQueryException {}
+
   public static EClassNamesQuerySpecification instance() throws ViatraQueryException {}
 
}
 
}
 
</source>
 
</source>
  
 
=== Lifecycle management  ===
 
=== Lifecycle management  ===
In EMF-IncQuery, all pattern matching (query evaluation) is carried out in '''IncQueryEngine''' instances that are accessed through the user-friendly generated classes of the public API. The '''IncQueryEngine''' associated to your patterns can be accessed and managed through the  '''EngineManager''' singleton class, to track and manipulate their lifecycles. By default, for each instance model root (Resource, ResourceSet or EObject tree) a single, managed '''IncQueryEngine''' is created, which is shared by all objects that access EMF-IncQuery's features through the generated API. The '''IncQueryEngine''' is attached to an EMF model root (Notifier of concrete type '''Resource''', '''ResourceSet''' or '''EObject''') and '''it is retained on the heap as long as the model itself is there'''. It will listen on EMF update notifications stemming from the given model in order to maintain live results. If you release all references to the model (e.g. unload the resource), the '''IncQueryEngine''' can also be garbage collected (as long as there are no other inbound references on it).
 
  
In all, for most (basic) scenarios, the following workflow should be followed:
+
In VIATRA Query, all pattern matching (query evaluation) is carried out in '''ViatraQueryEngine''' instances that are accessed through the user-friendly generated classes of the public API. The '''ViatraQueryEngine''' associated to your patterns can be accessed and managed through the '''EngineManager''' singleton class, to track and manipulate their lifecycles.
* initialize/load the model
+
* initialize your '''IncQueryEngine''' instance
+
* initialize pattern matchers, or groups of pattern matchers and use them
+
* if you release the model and your '''IncQueryEngine''' instance, all resources will be freed by the garbage collector.
+
  
For advanced scenarios (if you wish to manage lifecycles at a more finegrained level), you have the option of creating '''unmanaged''' IncQueryEngines and dispose of them independently of your instance model. For most use-cases though, we recommend the use of managed engines, this is the default and optimized behavior, as these engines can share common indices and caches to save memory and CPU time. The '''EngineManager''' ensures that there will be no duplicated engine for the same model root (Notifier) object. Creating an unmanaged engine will give you certain additional benefits, however additional considerations should be applied. See [[EMFIncQuery/UserDocumentation/API/Advanced##Advanced_IncQuery_Lifecycle_management|Advanced lifecycle management]] for details.
+
A ViatraQueryEngine is instantiated with a Scope implementation that describes the model the query should work with. By default, in case of EMF it is recommended to initialize an EMFScope instance with the ResourceSet containing the EMF model. For more details about scopes see [[VIATRA/Query/UserDocumentation/API/Advanced#Query_Scopes|Query Scopes]].
 +
 
 +
By default, for each scope a single, managed '''ViatraQueryEngine''' is created, which is shared by all objects that access VIATRA Query's features through the generated API. The '''ViatraQueryEngine''' is attached to the scope and '''it is retained on the heap as long as the model itself is there'''. It will listen on update notifications stemming from the given model in order to maintain live results. If you release all references to the model (e.g. unload the resource), the '''ViatraQueryEngine''' can also be garbage collected (as long as there are no other inbound references on it).
 +
 
 +
In all, for most (basic) scenarios, the following workflow should be followed:
 +
 
 +
*initialize/load the model
 +
*initialize your '''ViatraQueryEngine''' instance
 +
*initialize pattern matchers, or groups of pattern matchers and use them
 +
*if you release the model and your '''ViatraQueryEngine''' instance, all resources will be freed by the garbage collector.
 +
 
 +
For advanced scenarios (if you wish to manage lifecycles at a more finegrained level), you have the option of creating '''unmanaged''' ViatraQueryEngines and dispose of them independently of your instance model. For most use-cases though, we recommend the use of managed engines, this is the default and optimized behavior, as these engines can share common indices and caches to save memory and CPU time. The '''EngineManager''' ensures that there will be no duplicated engine for the same model root (Notifier) object. Creating an unmanaged engine will give you certain additional benefits, however additional considerations should be applied. See [[VIATRA/Query/UserDocumentation/API/Advanced#.23Advanced_VIATRA_Query_Lifecycle_management|Advanced lifecycle management]] for details.
  
 
=== Typical programming patterns  ===
 
=== Typical programming patterns  ===
In the followings, we provide short source code samples (with some explanations) that cover the most important use-cases supported by the EMF-IncQuery API.
+
 
'''Note:''' We recommend putting the '''@Handler'''&nbsp;on any pattern, because it will generate a project that contains code segments that illustrate the basic usage of the IncQuery Java API. The sample code will contain an Eclipse command handler and a dialog that shows the matches of the query in a selected file resource (you can try them in a runtime application run configuration, with right-clicking on the instance model file in e.g. the Project Explorer).&nbsp;
+
In the followings, we provide short source code samples (with some explanations) that cover the most important use-cases supported by the VIATRA Query API.  
  
 
===== Loading an instance model and executing a query  =====
 
===== Loading an instance model and executing a query  =====
 +
 
<source lang="java">
 
<source lang="java">
  
 
// get all matches of the pattern
 
// get all matches of the pattern
 
// initialization
 
// initialization
// phase 1: (managed) IncQueryEngine
+
// phase 1: (managed) ViatraQueryEngine
IncQueryEngine engine = IncQueryEngine.on(resource /* or resourceSet */);  
+
ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource /* or resourceSet */));  
 
// phase 2: the matcher itself
 
// phase 2: the matcher itself
 
EObjectMatcher matcher = EObjectMatcher.on(engine);
 
EObjectMatcher matcher = EObjectMatcher.on(engine);
Line 176: Line 186:
 
StringBuilder results = new StringBuilder();
 
StringBuilder results = new StringBuilder();
 
prettyPrintMatches(results, matches);
 
prettyPrintMatches(results, matches);
</source>
+
</source>  
  
 
===== Using the MatchProcessor  =====
 
===== Using the MatchProcessor  =====
With the MatchProcessor you can iterate over the matches of a pattern quite easily:  
+
 
<source lang="java">
+
With the MatchProcessor you can iterate over the matches of a pattern quite easily: <source lang="java">
 
matcher2.forEachMatch(new EClassNamesProcessor() {
 
matcher2.forEachMatch(new EClassNamesProcessor() {
 
  @Override
 
  @Override
Line 187: Line 197:
 
  }
 
  }
 
});
 
});
</source>
+
</source>  
  
 
===== Matching with partially bound input parameters and using result set projections  =====
 
===== Matching with partially bound input parameters and using result set projections  =====
An important aspect of EMF-IncQuery queries is that they are '''bidirectional''' in the sense that they accept input bindings, to filter/project the result set with a given input constraint.
+
 
The following example illustrates the usage of the match processor with an input binding that restricts the result set to the cases where the second parameter (the name of the EClass) takes the value "A":
+
An important aspect of VIATRA Query queries is that they are '''bidirectional''' in the sense that they accept input bindings, to filter/project the result set with a given input constraint. The following example illustrates the usage of the match processor with an input binding that restricts the result set to the cases where the second parameter (the name of the EClass) takes the value "A": <source lang="java">
<source lang="java">
+
 
matcher2.forEachMatch( matcher2.newMatch(null, "A") , new EClassNamesProcessor() {
 
matcher2.forEachMatch( matcher2.newMatch(null, "A") , new EClassNamesProcessor() {
 
  @Override
 
  @Override
Line 207: Line 216:
 
  }
 
  }
 
});
 
});
</source>
+
</source> The input bindings may be used for all match result set methods.  
The input bindings may be used for all match result set methods.
+
  
Additionally, the '''getAllValuesOf...''' methods allow you to perform projections of the result set to one of the parameters:
+
Additionally, the '''getAllValuesOf...''' methods allow you to perform projections of the result set to one of the parameters: <source lang="java">
<source lang="java">
+
 
// projections
 
// projections
 
for (EClass ec: matcher2.getAllValuesOfc(matcher2.newMatch(null,"A")))
 
for (EClass ec: matcher2.getAllValuesOfc(matcher2.newMatch(null,"A")))
Line 217: Line 224:
 
  results.append("\tEClass with name A: " + ec.toString() + "\n");
 
  results.append("\tEClass with name A: " + ec.toString() + "\n");
 
}
 
}
</source>
+
</source>  
  
 
===== Initialization of pattern groups  =====
 
===== Initialization of pattern groups  =====
Using pattern groups is important for performance. By default, EMF-IncQuery performs a traversal of the instance model when a matcher is accessed through the '''IncQueryEngine''' for the first time. If you wish to use several pattern matchers, it is a good idea to make use of the generated pattern group class and prepare the IncQueryEngine to perform a combined traversal (with minimal additional overhead) so that any additional Matcher initializations avoid re-traversals.
+
 
 +
Using pattern groups is important for performance. By default, VIATRA Query performs a traversal of the instance model when a matcher is accessed through the '''ViatraQueryEngine''' for the first time. If you wish to use several pattern matchers, it is a good idea to make use of the generated pattern group class and prepare the ViatraQueryEngine to perform a combined traversal (with minimal additional overhead) so that any additional Matcher initializations avoid re-traversals.  
  
 
<source lang="java">
 
<source lang="java">
// phase 1: (managed) IncQueryEngine
+
// phase 1: (managed) ViatraQueryEngine
IncQueryEngine engine = IncQueryEngine.on(resource);
+
ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource));
 
// phase 2: the group of pattern matchers
 
// phase 2: the group of pattern matchers
GroupOfFileHeadlessQueries patternGroup = HeadlessQueries.instance();
+
HeadlessQueries patternGroup = HeadlessQueries.instance();
 
patternGroup.prepare(engine);
 
patternGroup.prepare(engine);
 
// from here on everything is the same
 
// from here on everything is the same
Line 237: Line 245:
 
// because EClassNamesMatcher is included in the patterngroup, *no new traversal* will be done here
 
// because EClassNamesMatcher is included in the patterngroup, *no new traversal* will be done here
 
EClassNamesMatcher matcher2 = EClassNamesMatcher.on(engine);
 
EClassNamesMatcher matcher2 = EClassNamesMatcher.on(engine);
</source>
+
</source>  
  
 
===== Tracking changes in match sets efficiently  =====
 
===== Tracking changes in match sets efficiently  =====
There are some usecases where you don’t want to follow every change of a pattern’s match, just gather them together and process them when you’re ready.  
+
 
EMF-IncQuery provides several means of doing this (see the [[EMFIncQuery/UserDocumentation/API/Advanced#Advanced_query_result_set_change_processing|Advanced query result set change processing]] page for details), but we recommend using JFace databinding for basic purposes. To this end, the '''IncQueryObservables''' utility class can transform the result set of your matcher into an observable list or set that can be tracked and even data bound easily.
+
There are some usecases where you don’t want to follow every change of a pattern’s match, just gather them together and process them when you’re ready. VIATRA Query provides several means of doing this (see the [[VIATRA/Query/UserDocumentation/API/Advanced#Advanced_query_result_set_change_processing|Advanced query result set change processing]] page for details), but we recommend using JFace databinding for basic purposes. To this end, the '''ViatraObservables''' utility class can transform the result set of your matcher into an observable list or set that can be tracked and even data bound easily.
 +
 
 +
For headless (or non-UI thread) execution, please use the simple DefaultRealm implementation provided in the example (and invoke it on the appropriate thread).  
  
 
<source lang="java">
 
<source lang="java">
Line 251: Line 261:
 
//    * is does not support generics, hence typesafe programming is not possible
 
//    * is does not support generics, hence typesafe programming is not possible
 
//    * a "Realm" needs to be set up for headless execution
 
//    * a "Realm" needs to be set up for headless execution
DefaultRealm realm = new DefaultRealm();
+
DefaultRealm realm = new DefaultRealm(); // this is necessary for headless execution (or when you
IObservableSet set = IncQueryObservables.observeMatchesAsSet(matcher);
+
// wish to execute outside of the UI thread. make sure to invoke it on the appropriate thread!
 +
IObservableSet set = ViatraObservables.observeMatchesAsSet(matcher);
 
set.addSetChangeListener(new ISetChangeListener() {
 
set.addSetChangeListener(new ISetChangeListener() {
 
  @Override
 
  @Override
Line 262: Line 273:
 
   }
 
   }
 
});
 
});
</source>
+
</source>  
 +
 
 +
With this facility, it is easy to build an Eclipse UI on top of abstract views of your model. Additionally, two further features you may find useful are:
 +
*[[VIATRA/Addon/Databinding|VIATRA Query Databinding]] provides means to define observable values on pattern matches that can be used for displaying individual results in JFace viewers
 +
*A complementary feature is provided by [[VIATRA/Addon/VIATRA_Viewers|VIATRA Viewers]], which provides additional, higher level and easy-to-use generative features to further ease this task (and also add very powerful visualization capabilities to developing queries).
 +
 
 +
== Advanced capabilities  ==
  
With this facility, it is easy to build an Eclipse UI on top of abstract views of your model. [[EMFIncQuery/UserDocumentation/IncQuery_Viewers|IncQuery Viewers]] provides additional, easy-to-use generative features to help ease this task (and also add very powerful visualization capabilities to developing queries).
+
In addition to the basic features discussed above, VIATRA Query provides several additional advanced features of interest:
  
== Advanced capabilities ==
+
*the Generic API to dynamically instantiate and execute patterns from code, without code generation  
In addition to the basic features discussed above, EMF-IncQuery provides several additional advanced features of interest:
+
*advanced query result change processing and lifecycle management features for performance-critical and/or resource constrained applications  
* the Generic API to dynamically instantiate and execute patterns from code, without code generation
+
*VIATRA Query Base, a light-weight standalone base indexer library that provides incremental evaluation for core queries such as "get all instances", "get inverse reference targets", as well as incremental transitive closure.
* advanced query result change processing and lifecycle management features for performance-critical and/or resource constrained applications
+
* IncQuery Base, a light-weight standalone base indexer library that provides incremental evaluation for core queries such as "get all instances", "get inverse reference targets", as well as incremental transitive closure.
+
  
These topics are discussed in detail on the [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API topics]] page.
+
These topics are discussed in detail on the [[VIATRA/Query/UserDocumentation/API/Advanced|Advanced API topics]] page.

Latest revision as of 15:15, 14 November 2017

Stop.png
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 presents the basics of VIATRA Query's Java API.

The contents only over the basic use-cases. For advanced features, see Advanced API features.

Running example

All the code examples and explanations will be given in the context of the Headless 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/headless Most notably,

Javadoc

The most up-to-date Javadocs for the VIATRA Query API can be found online at https://wiki.eclipse.org/VIATRA/Releases.

VIATRA Query Java API

The most typical way of using the VIATRA Query API is to make use of the generated code that is found in the "src-gen" folder of your VIATRA Query project. This generated code provides easy and type-safe access to most of VIATRA Query's features from Java code. The only important thing to keep in mind is that the generated code is available only when your VIATRA Query project is loaded into the Eclipse runtime, i.e. for working with the generated code for development purposes you'll need to use Eclipse Application launch configurations.

VIATRA Query also supports a "dynamic", generic API that allows to make use of patterns without relying on the generated code. The generic API shares functionality with the base classes of the "generated" API, and for most scenarios there is no performance difference between the two. A notable exception for this rule of thumb are check() expressions, where the generated code that is invoked through the generated API will execute the Java code instead of interpreting Xbase.

In this wiki, we will present a simple introduction to the basics of the "generated" API, to introduce features that will help you to integrate VIATRA Query queries into your Java application. The Advanced API features page discusses the usage of the dynamic and generic APIs.

Most important classes and their relationships

For every pattern definition, the VIATRA Query tooling generates a Match, a Matcher, into a Java package that corresponds to the package of the pattern definition, constituting the public API that is intended for client code usage. In addition, some helper classes are generated into the ".util" subpackage:

  • if check expressions are present in your pattern definition, several Evaluator classes are also generated.
  • a MatchProcessor class is generated to aid match set traversal.
  • Finally, a QuerySpecification helper class is also generated that supports advanced lifecycle management (which is not necessary in most cases).

In order to fully understand the capabilities of these classes, it is a good idea to read through the Generic API section of the Advanced API features page.

Match

A Match object 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.

You can also use Match 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.

The code example below shows the EClassNamesMatch class generated for the eClassNames pattern of the running example. The generated class implements the interface IPatternMatch and extends the BasePatternMatch internal implementation class.

public abstract class EClassNamesMatch implements IPatternMatch {
  /**
   * members and constructor
   */
  private EClass fC;
  private String fN;
  private static String[] parameterNames = {"C", "N"};
  private EClassNamesMatch(EClass pC, String pN) {}
  /** getters and setters **/
  public Object get(String parameterName) { }
  public EClass getC() {}
  public String getN() {}
  public boolean set(String parameterName, Object newValue) {}
  public void setC(EClass pC) {}
  public void setN(String pN) {}
  /** utility functions **/
  public String patternName() {}
  public String[] parameterNames() {}
  public Object[] toArray() {}
  public String prettyPrint() {}
 
  public int hashCode() {}
  public boolean equals(Object obj) {}
  /** access to the internal EMF-based representation, as a sort of "reflection" **/
  public Pattern pattern() {}
  /** Mutable inner subclass so that matches can be "setted" - for parameter passing **/
  static final class Mutable extends EClassNamesMatch {}
}

Matcher

The Matcher is the main entry point of the VIATRA Query API, with pattern-specific query methods. It provides access to the three key features of VIATRA Query:

  • First of all it provides means to initialize a pattern matcher for a given EMF instance model which can either be a Resource, a ResourceSet, or an EObject (in this latter case, the scope of the matching will be the containment tree under the passed EObject). We recommend the use of ResourceSets if possible to avoid cross-reference related issues.
  • After the initialization of the engine, the Matcher provides getter methods to retrieve the contents of the match set. For easy iteration over the match set it provides a convenience method (forEachMatch) as well, as this is the most frequent use case in our observation. Of course it contains other handy features (e.g.: countMatches, hasMatch) to help integration.
  • Finally, it provides means to efficiently track the changes in the match set in an event-driven fashion.
The example generated source code below demonstrates the EClassNamesMatcher class generated for the eClassNames pattern from the running example. The matcher class implements the ViatraQueryMatcher generic interface, and its implementation code extends the BaseGeneratedMatcher 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 !ViatraQueryMatcher and are accessible through inheritance from !BaseGeneratedMatcher.
public class EClassNamesMatcher implements ViatraQueryMatcher<EClassNamesMatch> {
  /** initializer methods **/
  public EClassNamesMatcher(ViatraQueryEngine engine) throws ViatraQueryException {}
 
  /** access to match set **/
  public Collection<EClassNamesMatch> getAllMatches(); // inherited
  public Collection<EClassNamesMatch> getAllMatches(EClass pC, final String pN) {}
  public EClassNamesMatch getOneArbitraryMatch(); // inherited
  public EClassNamesMatch getOneArbitraryMatch(EClass pC, String pN) {}
  public boolean hasMatch(); // inherited
  public boolean hasMatch(EClass pC, String pN) {}
  public int countMatches(); // inherited
  public int countMatches(EClass pC, String pN) {}
 
  /** Retrieve the set of values that occur in matches for C or N.**/
  public Set<EClass> getAllValuesOfC() {}
  public Set<EClass> getAllValuesOfC(EClassNamesMatch partialMatch) {}
  public Set<EClass> getAllValuesOfC(String pN) {}
  public Set<String> getAllValuesOfN() {}
  public Set<String> getAllValuesOfN(EClassNamesMatch partialMatch) {}
  public Set<String> getAllValuesOfN(EClass pC) {}
 
  /** iterate over matches using a lambda **/
  public void forEachMatch(IMatchProcessor<? super EClassNamesMatch> processor); // inherited
  public void forEachMatch(EClass pC, String pN, IMatchProcessor<? super EClassNamesMatch> processor) {}
  public void forOneArbitraryMatch(IMatchProcessor<? super EClassNamesMatch> processor); // inherited
  public boolean forOneArbitraryMatch(EClass pC, String pN, IMatchProcessor<? super EClassNamesMatch> 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 EClassNamesMatch newMatch(EClass pC, String pN) {}
}


Helper classes

  • MatchProcessor

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.

The source code example below implements the IMatchProcessor interface.
/**
 * A match processor tailored for the headless.eClassNames pattern.
 */
public abstract class EClassNamesProcessor implements IMatchProcessor<EClassNamesMatch> {
  /**
   * Defines the action that is to be executed on each match.
   */
  public abstract void process(final EClass C, final String N);
}
  • Evaluator: If your pattern contains check expressions an evaluator java code is generated from it. It is used by the engine during a query to evaluate the expression’s result. In most cases you don’t need to deal with these classes.
  • QuerySpecification: 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 ViatraQueryEngine. 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.
The code sample extends the BaseGeneratedQuerySpecification class.
/**
 * A pattern-specific query specification that can instantiate EClassNamesMatcher in a type-safe way.
 */
public final class EClassNamesQuerySpecification extends BaseGeneratedQuerySpecification<EClassNamesMatcher> {
  /** @return the singleton instance of the query specification **/
  public static EClassNamesQuerySpecification instance() throws ViatraQueryException {}
}

Lifecycle management

In VIATRA Query, all pattern matching (query evaluation) is carried out in ViatraQueryEngine instances that are accessed through the user-friendly generated classes of the public API. The ViatraQueryEngine associated to your patterns can be accessed and managed through the EngineManager singleton class, to track and manipulate their lifecycles.

A ViatraQueryEngine is instantiated with a Scope implementation that describes the model the query should work with. By default, in case of EMF it is recommended to initialize an EMFScope instance with the ResourceSet containing the EMF model. For more details about scopes see Query Scopes.

By default, for each scope a single, managed ViatraQueryEngine is created, which is shared by all objects that access VIATRA Query's features through the generated API. The ViatraQueryEngine is attached to the scope and it is retained on the heap as long as the model itself is there. It will listen on update notifications stemming from the given model in order to maintain live results. If you release all references to the model (e.g. unload the resource), the ViatraQueryEngine can also be garbage collected (as long as there are no other inbound references on it).

In all, for most (basic) scenarios, the following workflow should be followed:

  • initialize/load the model
  • initialize your ViatraQueryEngine instance
  • initialize pattern matchers, or groups of pattern matchers and use them
  • if you release the model and your ViatraQueryEngine instance, all resources will be freed by the garbage collector.

For advanced scenarios (if you wish to manage lifecycles at a more finegrained level), you have the option of creating unmanaged ViatraQueryEngines and dispose of them independently of your instance model. For most use-cases though, we recommend the use of managed engines, this is the default and optimized behavior, as these engines can share common indices and caches to save memory and CPU time. The EngineManager ensures that there will be no duplicated engine for the same model root (Notifier) object. Creating an unmanaged engine will give you certain additional benefits, however additional considerations should be applied. See Advanced lifecycle management for details.

Typical programming patterns

In the followings, we provide short source code samples (with some explanations) that cover the most important use-cases supported by the VIATRA Query API.

Loading an instance model and executing a query
// get all matches of the pattern
// initialization
// phase 1: (managed) ViatraQueryEngine
ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource /* or resourceSet */)); 
// phase 2: the matcher itself
EObjectMatcher matcher = EObjectMatcher.on(engine);
// get all matches of the pattern
Collection<EObjectMatch> matches = matcher.getAllMatches();
// process matches, produce some output
StringBuilder results = new StringBuilder();
prettyPrintMatches(results, matches);
Using the MatchProcessor
With the MatchProcessor you can iterate over the matches of a pattern quite easily:
matcher2.forEachMatch(new EClassNamesProcessor() {
 @Override
 public void process(EClass c, String n) {
  results.append("\tEClass: " + c.toString() + "\n");
 }
});
Matching with partially bound input parameters and using result set projections
An important aspect of VIATRA Query queries is that they are bidirectional in the sense that they accept input bindings, to filter/project the result set with a given input constraint. The following example illustrates the usage of the match processor with an input binding that restricts the result set to the cases where the second parameter (the name of the EClass) takes the value "A":
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");
 }
});	
 
// alternatively:
matcher2.forEachMatch(null, "A" , new EClassNamesProcessor() {
 @Override
 public void process(EClass c, String n) {
  results.append("\tEClass with name A: " + c.toString() + "\n");
 }
});
The input bindings may be used for all match result set methods. Additionally, the getAllValuesOf... methods allow you to perform projections of the result set to one of the parameters:
// projections
for (EClass ec: matcher2.getAllValuesOfc(matcher2.newMatch(null,"A")))
{
 results.append("\tEClass with name A: " + ec.toString() + "\n");
}
Initialization of pattern groups

Using pattern groups is important for performance. By default, VIATRA Query performs a traversal of the instance model when a matcher is accessed through the ViatraQueryEngine for the first time. If you wish to use several pattern matchers, it is a good idea to make use of the generated pattern group class and prepare the ViatraQueryEngine to perform a combined traversal (with minimal additional overhead) so that any additional Matcher initializations avoid re-traversals.

// phase 1: (managed) ViatraQueryEngine
ViatraQueryEngine engine = ViatraQueryEngine.on(new EMFScope(resource));
// phase 2: the group of pattern matchers
HeadlessQueries patternGroup = HeadlessQueries.instance();
patternGroup.prepare(engine);
// from here on everything is the same
EObjectMatcher matcher = EObjectMatcher.on(engine);
// get all matches of the pattern
Collection<EObjectMatch> matches = matcher.getAllMatches();
prettyPrintMatches(results, matches);
// ... //
// matching with partially bound input parameters
// because EClassNamesMatcher is included in the patterngroup, *no new traversal* will be done here
EClassNamesMatcher matcher2 = EClassNamesMatcher.on(engine);
Tracking changes in match sets efficiently

There are some usecases where you don’t want to follow every change of a pattern’s match, just gather them together and process them when you’re ready. VIATRA Query provides several means of doing this (see the Advanced query result set change processing page for details), but we recommend using JFace databinding for basic purposes. To this end, the ViatraObservables utility class can transform the result set of your matcher into an observable list or set that can be tracked and even data bound easily.

For headless (or non-UI thread) execution, please use the simple DefaultRealm implementation provided in the example (and invoke it on the appropriate thread).

// (+) changes can also be tracked using JFace Databinding
// this approach provides good performance, as the observable callbacks are guaranteed to be called
//   in a consistent state, and only when there is a relevant change; anything
//   can be written into the callback method
// (-) * the databinding API introduces additional dependencies
//     * is does not support generics, hence typesafe programming is not possible
//     * a "Realm" needs to be set up for headless execution
DefaultRealm realm = new DefaultRealm(); // this is necessary for headless execution (or when you
// wish to execute outside of the UI thread. make sure to invoke it on the appropriate thread!
IObservableSet set = ViatraObservables.observeMatchesAsSet(matcher);
set.addSetChangeListener(new ISetChangeListener() {
 @Override
 public void handleSetChange(SetChangeEvent event) {
  for (Object _o : event.diff.getAdditions()) {
   if (_o instanceof EPackageMatch) {
    results.append("\tNew EPackage found by changeset databinding: " + ((EPackageMatch)_o).getP().getName()+"\n");
   }
  }
});

With this facility, it is easy to build an Eclipse UI on top of abstract views of your model. Additionally, two further features you may find useful are:

  • VIATRA Query Databinding provides means to define observable values on pattern matches that can be used for displaying individual results in JFace viewers
  • A complementary feature is provided by VIATRA Viewers, which provides additional, higher level and easy-to-use generative features to further ease this task (and also add very powerful visualization capabilities to developing queries).

Advanced capabilities

In addition to the basic features discussed above, VIATRA Query provides several additional advanced features of interest:

  • the Generic API to dynamically instantiate and execute patterns from code, without code generation
  • advanced query result change processing and lifecycle management features for performance-critical and/or resource constrained applications
  • VIATRA Query Base, a light-weight standalone base indexer library that provides incremental evaluation for core queries such as "get all instances", "get inverse reference targets", as well as incremental transitive closure.

These topics are discussed in detail on the Advanced API topics page.

Back to the top