Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "VIATRA/Query/UserDocumentation/HeadlessExecution"
m (Harmath.incquerylabs.com moved page EMFIncQuery/UserDocumentation/HeadlessExecution to VIATRA/Query/UserDocumentation/HeadlessExecution: Migration) |
(Update to VIATRA Query 1.2) |
||
Line 3: | Line 3: | ||
== Overview == | == 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.<br>First, the VIATRA Query project '''examples/headless''' can be downloaded from: http://git.eclipse.org/c/viatra/org.eclipse.viatra.git | |
The project contains simple patterns that match on Ecore models (i.e. .ecore files):<br> | The project contains simple patterns that match on Ecore models (i.e. .ecore files):<br> | ||
<source lang="java"> | <source lang="java"> | ||
− | package headless | + | package headless |
import "http://www.eclipse.org/emf/2002/Ecore" | import "http://www.eclipse.org/emf/2002/Ecore" | ||
Line 21: | Line 21: | ||
</source> | </source> | ||
− | Pattern '''eObject()''' will match on any EMF model. | + | Pattern '''eObject()''' will match on any EMF model object. |
− | == Using | + | == Using VIATRA Query in a headless Eclipse RCP application == |
− | The ''' | + | 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: | 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 | **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. | **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, | **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 '''create a matcher''' (based on a pattern definition) and | ||
**then '''retrieve the matches''' as a collection. | **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, | + | 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. | RCP applications are registered through the org.eclipse.core.runtime.applications extension point. The plugin.xml file defines the extension. | ||
Line 43: | Line 43: | ||
<source lang="xml"> | <source lang="xml"> | ||
<extension | <extension | ||
− | id="org.eclipse. | + | id="org.eclipse.viatra.query.application.app.generic" |
point="org.eclipse.core.runtime.applications"> | point="org.eclipse.core.runtime.applications"> | ||
<application | <application | ||
Line 50: | Line 50: | ||
visible="true"> | visible="true"> | ||
<run | <run | ||
− | class="org.eclipse.incquery.application.generic. | + | class="org.eclipse.incquery.application.generic.GenericSimpleViatraQueryApplication"> |
</run> | </run> | ||
</application> | </application> | ||
</extension> | </extension> | ||
<extension | <extension | ||
− | id="org.eclipse. | + | id="org.eclipse.viatra.query.application.app.patternspecific" |
point="org.eclipse.core.runtime.applications"> | point="org.eclipse.core.runtime.applications"> | ||
<application | <application | ||
Line 62: | Line 62: | ||
visible="true"> | visible="true"> | ||
<run | <run | ||
− | class="org.eclipse.incquery.application.patternspecific. | + | class="org.eclipse.incquery.application.patternspecific.PatternSpecificSimpleViatraQueryApplication"> |
</run> | </run> | ||
</application> | </application> | ||
Line 72: | Line 72: | ||
<source lang="xml"> | <source lang="xml"> | ||
<extension | <extension | ||
− | id=" | + | id="viatra.query.generic" |
point="org.eclipse.core.runtime.products"> | point="org.eclipse.core.runtime.products"> | ||
<product | <product | ||
− | application="org.eclipse. | + | application="org.eclipse.viatra.query.application.app.generic" |
− | name="Generic | + | name="Generic VIATRA Query Application"> |
<property | <property | ||
name="appName" | name="appName" | ||
− | value="Generic | + | value="Generic VIATRA Query Application"> |
</property> | </property> | ||
</product> | </product> | ||
</extension> | </extension> | ||
<extension | <extension | ||
− | id=" | + | id="viatra.query.specific" |
point="org.eclipse.core.runtime.products"> | point="org.eclipse.core.runtime.products"> | ||
<product | <product | ||
− | application="org.eclipse. | + | application="org.eclipse.viatra.query.application.app.patternspecific" |
− | name="PatternSpecific | + | name="PatternSpecific VIATRA Query Application"> |
<property | <property | ||
name="appName" | name="appName" | ||
− | value="PatternSpecific | + | value="PatternSpecific VIATRA Query Application"> |
</property> | </property> | ||
</product> | </product> | ||
Line 104: | Line 104: | ||
*Eclipse 4: http://www.vogella.com/articles/EclipseRCP/article.html | *Eclipse 4: http://www.vogella.com/articles/EclipseRCP/article.html | ||
− | == Using | + | == Using VIATRA Query in a Java application == |
− | Since | + | 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: | However, it this case manual registration steps are required: | ||
Line 116: | Line 116: | ||
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). | 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 ''' | + | 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 | + | = Running JUnit plug-in tests supported by VIATRA Query queries = |
TODO | TODO |
Revision as of 09:47, 21 March 2016
Contents
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 examples/headless can be downloaded from: http://git.eclipse.org/c/viatra/org.eclipse.viatra.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.incquery.application.generic.GenericSimpleViatraQueryApplication"> </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.incquery.application.patternspecific.PatternSpecificSimpleViatraQueryApplication"> </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:
- All EMF metamodels needs to be registered (as in case of EMF models).
- Example:
Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap().put("ecore", new EcoreResourceFactoryImpl());
- Example:
- If the generic pattern API is used, the pattern language with Xtext needs to be registered as well.
- Example:
new EMFPatternLanguageStandaloneSetup().createInjectorAndDoEMFRegistration();
- Example:
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