Latest revision as of 15:25, 14 November 2017

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

Headless Execution Example

Overview

VIATRA Query can be used without any graphical user interface (in a headless RCP configuration - note: for now, running outside of the RCP environment is not supported). In this example, we take an existing VIATRA Query project and based on it, we create a (headless) Eclipse Application that can be executed from a console (command prompt) to print the matches for an arbitrary input model file.
First, the VIATRA Query project headless can be downloaded from: http://git.eclipse.org/c/viatra/org.eclipse.viatra.examples.git

The project contains simple patterns that match on Ecore models (i.e. .ecore files):

package headless
 
import "http://www.eclipse.org/emf/2002/Ecore"
 
pattern eClassNames(C: EClass, N : EString)= {
	EClass.name(C,N);
}
 
pattern eObject(O) {
	EObject(O);
}

Pattern eObject() will match on any EMF model object.

Using VIATRA Query in a headless Eclipse RCP application

The org.eclipse.viatra.query.application.queries bundle can be embedded into any Eclipse application through VIATRA Query's Java API. The org.eclipse.viatra.query.application bundle project demonstrates such usage.

The project includes several class files:

• GenericEclipseViatraQueryApplication and PatternSpecificEclipseViatraQueryApplication: by implementing the IApplication interface, these classes provide an RCP entry point that is also capable of handling command line parameters. It checks that the input model is provided using the -m <modelPath> switch, and the Generic variant is also able to accept the query name provided using the -p <patternFQN> switch and then invokes the pattern matcher (the PatternSpecific variant always applies the eObject query).
  • To execute the example (on Windows), call as follows (assuming the current folder contains eclipse.exe and the model can be found at c:/test/input.ecore): eclipse.exe -m c:/test/input.ecore - p headless.eClassNames
  • Pattern fully qualified names are the package fully qualified name of a pattern + "." + the local name of the pattern, e.g. headless.eClassNames or headless.eObject in the example above.
• ViatraQueryHeadless: utility class with two public methods called executeGeneric() and executePatternsSpecific() that demonstrate the basic usage of VIATRA Query's Java API. Both will
  • first try to load the model found at modelPath into an EMF Resource, and if that was successful,
  • then create a matcher (based on a pattern definition) and
  • then retrieve the matches as a collection.

The actual code also includes some additional fragments to illustrate performance measurements (timed execution for the EMF loading, VIATRA Query initialization and match set retrieval phases). Finally, the matches are printed using IPatternMatch.prettyPrint(). In the latter part of this document, this API is explained in detail.

RCP applications are registered through the org.eclipse.core.runtime.applications extension point. The plugin.xml file defines the extension.

<extension
         id="org.eclipse.viatra.query.application.app.generic"
         point="org.eclipse.core.runtime.applications">
      <application
            cardinality="singleton-global"
            thread="main"
            visible="true">
         <run
               class="org.eclipse.viatra.query.application.generic.GenericEclipseViatraQueryApplication">
         </run>
      </application>
   </extension>
   <extension
         id="org.eclipse.viatra.query.application.app.patternspecific"
         point="org.eclipse.core.runtime.applications">
      <application
            cardinality="singleton-global"
            thread="main"
            visible="true">
         <run
               class="org.eclipse.viatra.query.application.patternspecific.PatternSpecificEclipseViatraQueryApplication">
         </run>
      </application>
   </extension>

Finally, a product configuration is required in order to run this application as an Eclipse product, and to be able to export it into a standalone application that can be called from the console. Apart from adding the required plugins to the configuration, an org.eclipse.core.runtime.products extension is required as well (also found in plugin.xml):

 <extension
         id="viatra.query.generic"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.viatra.query.application.app.generic"
            name="Generic VIATRA Query Application">
         <property
               name="appName"
               value="Generic VIATRA Query Application">
         </property>
      </product>
   </extension>
   <extension
         id="viatra.query.specific"
         point="org.eclipse.core.runtime.products">
   	<product
            application="org.eclipse.viatra.query.application.app.patternspecific"
            name="PatternSpecific VIATRA Query Application">
         <property
               name="appName"
               value="PatternSpecific VIATRA Query Application">
         </property>
      </product>
	</extension>

If only the minimum required plugins are exported, the resulting eclipse folder is around 30 MB, which is quite small considering that an Eclipse Modeling distribution is around 300 MB.
Note that you may have to remove the platform-specific features that are for different platforms (e.g. Linux and MacOS X when using Windows).

For further help on RCP applications, we recommend to check out:

• Eclipse 3: http://www.vogella.com/articles/Eclipse3RCP/article.html
• Eclipse 4: http://www.vogella.com/articles/EclipseRCP/article.html

Using VIATRA Query in a Java application

Since VIATRA Query 0.8 it is possible to execute queries using without Eclipse applications, using the VIATRA Query Java API.

However, it this case manual registration steps are required:

1. All EMF metamodels needs to be registered (as in case of EMF models).
   • Example:

     Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap().put("ecore", new EcoreResourceFactoryImpl());

2. If the generic pattern API is used, the pattern language with Xtext needs to be registered as well.
   • Example:

     new EMFPatternLanguageStandaloneSetup().createInjectorAndDoEMFRegistration();

3. If you want to run Plug-in projects as plain Java applications in Eclipse, you may run into ClassNotFoundExceptions (e.g base.itc.ITcDataSource). In this case, simply add org.eclipse.viatra.query.runtime.base.itc to the list of dependencies.
   • This is caused by the way Eclipse prepares the Plug-in dependencies from direct dependencies and re-exported plugins, instead of the full transitive closure of plug-in dependencies.

A minimal example needs to be created (together with defined dependencies), but the headless application project also defines standard Java applications to execute queries (but dependencies are still managed via the PDE plug-in dependencies).

The following classes can be used as Java application: GenericEclipseApplication and PatternSpecificViatraQueryApplication. They work similarly to the Eclipse applications, but do the manual registration steps as required, and use file:/ URIs to open models instead of platform:/ URIs.

Running JUnit plug-in tests supported by VIATRA Query queries

TODO