EMF-IncQuery Base Documentation

About IncQuery Base

EMF-IncQuery Base aims to provide several useful (some would even argue critical) features for querying EMF models:

The point of IncQuery Base is to provide all of these in an incremental way, which means that once the query evaluator is attached to an EMF model, as long as it stays attached, the query results can be retrieved instantly (as the query result cache is automatically updated). IncQuery Base is a lightweight, small Java library that can be integrated easily to any EMF-based tool.

We are aware that some of the functionality can be found in some Ecore utility classes (for example ECrossReferenceAdapter). These standard implementations are non-incremental, and are thus do not scale well in scenarios where high query evaluation performance is necessary (such as e.g. on-the-fly well-formedness validation or live view maintenance). IncQuery Base has an additional important feature that is not present elsewhere: it contains very efficient implementations of transitive closure that can be used e.g. to maintain reachability regions incrementally, in very large EMF instance models. 

Incremental algorithms

The library contains incremental algorithms. In the case of EMF models, an incremental algorithm will visit the whole model only once (when the algorithm is initialized on the model) and after that it will maintain the data structures based on the modifications in the model, without visiting the whole model again. For the transitive closure this will result a remarkable performance speedup; because of the incremental manner of the algorithm, only small portions of a large-scale model will be visited when a modification occurs. Nevertheless, this comes with a price: for large EMF models the incremental algorithms will use additional memory, because the data structures are kept in memory during runtime. The implementation of the algorithms allow to dispose them (and the data structures) any time during the life-cycle.

Getting started

Example metamodel

In the tutorial we will use a simple EMF model which consists of the following elements:

Note that this metamodel is a slight modification of the metamodel which is used in many EMF tutorials (http://www.eclipse.org/edapt/libraryexample.php).

The following figure is the Ecore Diagram of the metamodel.

Project setup

You can download the required projects from the github repository of EMF-IncQuery:

You will need the following plug-ins:

Follow these steps to run the project:

  1. You will find a library.genmodel file under the model folder in the org.eclipse.viatra2.emf.incquery.base.test project. Open it and from the context menu choose Generate Model, Edit and Editor Code. This will create 3 plug-ins, named org.eclipse.viatra2.emf.incquery.base.test.library, org.eclipse.viatra2.emf.incquery.base.test.library.edit and org.eclipse.viatra2.emf.incquery.base.test.library.editor.
  2. Create a new Eclipse Application Run Configuration: go to Run menu -> Run Configurations. Choose Eclipse Application and add a new one.
  3. Optionally rename the Run Configuration as you like.
  4. Go to the Plug-ins tab and select Launch with -> plug-ins selected below only.
  5. Select all the six projects mentioned in this tutorial: the 3 downloaded and the 3 generated in the first step.
  6. Click on the Add Required Plug-ins button, this will select all the required plug-ins
  7. Click Apply and then Run. This will start a new Eclipse instance (Runtime Eclipse).

The test project

Simple queries

You will find several example queries in the org.eclipse.viatra2.emf.incquery.base.test plug-in's TestModule1.java file (executeQueries method). Note that, the example will print the match results to the STANDARD OUTPUT.

Transitive Closure queries (query 8)

We will demonstrate the usage of the TransitiveClosureHelper with the books and their citations in the library.

Suppose we want to borrow a book from the library but we also need all the books which is referred from the selected book via citations, because those may be necessary to understand the selected one (the required books may refer another books which also should be borrowed). This results that we have to know the transitive closure of the graph where the nodes will be the books and each reference between two books will be represented with an edge. To borrow the required books we have to query all the reachable targets of the selected book.

However, if we often go to the library we may query the "target" books many times which will result that we need an algorithm to compute it quickly. In this scenario an incremental algorithm will be really useful which will maintain the required books' citations automatically.

For example if we want to borrow the Angels and Demons book then we don't need to borrow any other books because it is an isolated node in the graph. However, if we want to borrow the Da Vinci Code we will need the Digital Fortress Manuscript, the Faithful Place, Alchemist and the 11 minutes Books too (query 9). Note that Da Vinci Code itself is also present in the result set as the engine allows self-loops.

The following figures illustrates the process of computing the result for the reachable targets of Da Vinci Code.

EMF-IncQuery Base Programmer documentation

IncQueryBaseFactory - integration with EMF models

The library provides the following interfaces:

Use the IncQueryBaseFactory class to create an instance implementing one of the above mentioned interfaces. You must pass a Notifier instance which is the root of the your EMF model. Only the sub model under the given EObject/Resource/ResourceSet root will be visited by the helper instances.

Note that if you do not need an instance later on, call the dispose method of the given interface to properly dispose the data structures of the given algorithm.

The NavigationHelper interface exposes the following methods (JavaDoc):

https://build.inf.mit.bme.hu/jenkins/job/EMF-IncQuery-Javadoc/javadoc/or...

The Helper can be instantiated either in wildcard mode or in 'parameterized' mode.  In wildcard mode, every aspect of the EMF model is automatically indexed. In 'parameterized mode', however, only selected types of model elements and features are indexed. Unused indices take up memory, so turn off wildcard mode to decrease the memory usage while working with very large models.

Unless in wildcard mode, the client has to register EClasses, EDataTypes and EStructuralFeatures before the Helper can index them and find../get... methods can provide the appropriate results. Note that registering new types will cause the Helper to re-iterate through the entire model to expand its index, which is costly, so it is best to register everything you need at once.

TransitiveClosureHelper

The TransitiveClosureHelper interface exposes methods to query reachability information along given EReferences in the EMF model. You must pass a Notifier instance and a set of EReferences when creating a helper instance with the appropriate method of the IncQueryBaseFactory class. The set of EReferences represents those instances which will be treated as edges in the 'graph'.

The TransitiveClosureHelper interface extends the ITcDataSource<V> interface defined in the org.eclipse.viatra2.emf.incquery.base.itc project. In this case the type parameter will be the EObject interface.

The ITcDataSource interface exposes the following methods (JavaDoc):

https://build.inf.mit.bme.hu/jenkins/job/EMF-IncQuery-Javadoc/javadoc/or...