Revision as of 12:11, 26 February 2016

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 headless Eclipse RCP 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:

• GenericEclipseIncQueryApplication and PatternSpecificEclipseIncQueryApplication: 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

Using IncQuery in a Java application

Since IncQuery 0.8 it is possible to execute queries using without Eclipse applications, using the IncQuery 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();

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 PatternSpecificIncQueryApplication. 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 EMF-IncQuery queries

TODO