Revision as of 14:11, 4 April 2013

Headless Execution Example

Overview

EMF-IncQuery 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 IncQuery 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 IncQuery project headlessQueries.incquery can be downloaded from: http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless

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.

Using IncQuery in a Java application

The headlessQueries.incquery bundle can be embedded into any Eclipse application through IncQuery's Java API. The org.eclipse.incquery.application bundle project demonstrates such usage.

The project includes several class files:

• GenericSimpleIncQueryApplication and PatternSpecificSimpleIncQueryApplication: by implementing the IApplication interface, these classes provide an RCP entrypoint 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.
• IncQueryHeadless: utility class with two public methods called executeGeneric() and executePatternsSpecific() that demonstrate the basic usage of IncQuery'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, IncQuery initialization and matchset 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.incquery.application.app.generic"
         point="org.eclipse.core.runtime.applications">
      <application
            cardinality="singleton-global"
            thread="main"
            visible="true">
         <run
               class="org.eclipse.incquery.application.generic.GenericSimpleIncQueryApplication">
         </run>
      </application>
   </extension>
   <extension
         id="org.eclipse.incquery.application.app.patternspecific"
         point="org.eclipse.core.runtime.applications">
      <application
            cardinality="singleton-global"
            thread="main"
            visible="true">
         <run
               class="org.eclipse.incquery.application.patternspecific.PatternSpecificSimpleIncQueryApplication">
         </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="incquery.generic"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.incquery.application.app.generic"
            name="Generic IncQuery Application">
         <property
               name="appName"
               value="Generic IncQuery Application">
         </property>
      </product>
   </extension>
   <extension
         id="incquery.specific"
         point="org.eclipse.core.runtime.products">
   	<product
            application="org.eclipse.incquery.application.app.patternspecific"
            name="PatternSpecific IncQuery Application">
         <property
               name="appName"
               value="PatternSpecific IncQuery 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

Running JUnit plug-in tests supported by EMF-IncQuery queries

TODO