https://wiki.eclipse.org/api.php?action=feedcontributions&user=Ujhelyiz.mit.bme.hu&feedformat=atomEclipsepedia - User contributions [en]2024-03-19T03:36:11ZUser contributionsMediaWiki 1.26.4https://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes/Meeting20150616&diff=387439VIATRA/DeveloperMeetingMinutes/Meeting201506162015-06-23T12:56:44Z<p>Ujhelyiz.mit.bme.hu: Created page with "= Topics = * Automated error reporting from Mars for both IncQuery * First report: Xcore installation bug (fixed in master) * https://git.eclipse.org/r/49589 (Bator A’s work..."</p>
<hr />
<div>= Topics =<br />
* Automated error reporting from Mars for both IncQuery<br />
* First report: Xcore installation bug (fixed in master)<br />
* https://git.eclipse.org/r/49589 (Bator A’s work)<br />
* hot issues for EIQ 1.0-RC<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=469634 (Viewers)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=464120 (cyclic linking)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=469612 (Java model exception)<br />
<br />
= Minutes =<br />
* IncQuery<br />
**Release blocking bugs: viewers almost ready, cyclic linking postponed<br />
** Local search<br />
* VIATRA<br />
**MWE integration ready: https://git.eclipse.org/r/#/c/50176/</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes/Meeting20150609&diff=387438VIATRA/DeveloperMeetingMinutes/Meeting201506092015-06-23T12:55:37Z<p>Ujhelyiz.mit.bme.hu: Created page with "= Topics = * Automated error reporting from Mars for both IncQuery and VIATRA ** https://dev.eclipse.org/recommenders/committers/confess/#/projects/54c12458e4b09f7fc8453997 **..."</p>
<hr />
<div>= Topics =<br />
* Automated error reporting from Mars for both IncQuery and VIATRA<br />
** https://dev.eclipse.org/recommenders/committers/confess/#/projects/54c12458e4b09f7fc8453997<br />
** https://dev.eclipse.org/recommenders/committers/confess/#/projects/5570bb8ee4b0182467523064 <br />
* https://git.eclipse.org/r/49589 (Bator A’s work)<br />
* hot issues for EIQ 1.0-RC<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=469634 (Viewers)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=465814 (mem leak)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=464120 (cyclic linking)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=469612 (Java model exception)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=469563 (surrogate queries fail to load)<br />
** https://bugs.eclipse.org/bugs/show_bug.cgi?id=462767 (surrogate key for enum literals in dynamic EMF mode)<br />
<br />
= Minutes = <br />
* Error reporting set up<br />
* Testing: uses school example, not includable on eclipse.org<br />
* Memory leak: traceability objects were leaked in case of repeated getMatcher release; hopefully fixed<br />
* Viewers: problem with existing engine reused for viewers; custom EMFScope idea available at https://git.eclipse.org/r/#/c/49770/ ; Gábor and Csabi will talk about possible options, e.g. NavigationHelper#addRoot()<br />
* Java model exception: Xbase issue; idea: check what happens if pattern is only available from target platform; provide better error message if problematic<br />
* Surrogate registry issue: bug itself was fixed; lazy loading postponed to 1.1<br />
* Dynamic EMF enum literals<br />
* Possible fix being created by Gábor; non-trivial updated; there might be performance effects</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes/Meeting20150602&diff=387437VIATRA/DeveloperMeetingMinutes/Meeting201506022015-06-23T12:53:25Z<p>Ujhelyiz.mit.bme.hu: Created page with "= Topics = Release preparation Remaining bugs for release * EIQ: [https://www.google.com/url?q=https%3A%2F%2Fbugs.eclipse.org%2Fbugs%2Fbuglist.cgi%3Flist_id%3D11861924%26orde..."</p>
<hr />
<div>= Topics =<br />
<br />
Release preparation<br />
Remaining bugs for release<br />
* EIQ: [https://www.google.com/url?q=https%3A%2F%2Fbugs.eclipse.org%2Fbugs%2Fbuglist.cgi%3Flist_id%3D11861924%26order%3Dtarget_milestone%2520DESC%2Cresolution%2Cbug_status%2Cpriority%2Cassigned_to%2Cbug_id%26product%3DIncquery%26query_based_on%3D%26query_format%3Dadvanced%26target_milestone%3D1.0%2520M1%26target_milestone%3D1.0%2520M2%26target_milestone%3D1.0%2520M3%26target_milestone%3D1.0%2520RC&sa=D&sntz=1&usg=AFQjCNFZXGmW9dwVN6sRC3AziSg4dnPGfA Bugzilla query]<br />
* VIATRA: [https://www.google.com/url?q=https%3A%2F%2Fbugs.eclipse.org%2Fbugs%2Fbuglist.cgi%3Flist_id%3D11862069%26product%3DViatra%26query_format%3Dadvanced%26target_milestone%3D0.7.0%2520M1%26target_milestone%3D0.7.0%2520M2%26target_milestone%3D0.7.0%2520M3&sa=D&sntz=1&usg=AFQjCNFFfYqM9aXGgTVvdwgxs4MTOmEIJw Bugzilla query]<br />
<br />
<br />
= Minutes =<br />
<br />
== EIQ ==<br />
* New dependency introduced by a commit: org.apache.commons.lang -> IP log does not refer to this; for 1.0 this is too late; for 1.1 it can be added<br />
* Release administration done; release review is scheduled to end on 17th June<br />
* Remaining tickets seem reasonable<br />
* TODO: Everybody will look at the tickets assigned to them<br />
== VIATRA ==<br />
* Release administration done; release review is scheduled to end on 17th June<br />
* Release timeline for 0.8? -> to be decided<br />
* MWE transformation chain demo<br />
** Idea: add option to have named ports for channels</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes&diff=387434VIATRA/DeveloperMeetingMinutes2015-06-23T12:45:45Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= EMF IncQuery Developer Meeting Minutes =<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150616|Meeting Minutes 2015.06.16.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150609|Meeting Minutes 2015.06.09.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150602|Meeting Minutes 2015.06.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150526|Meeting Minutes 2015.05.26.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150519|Meeting Minutes 2015.05.19.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150512|Meeting Minutes 2015.05.12.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150505|Meeting Minutes 2015.05.05.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150428|Meeting Minutes 2015.04.28.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150421|Meeting Minutes 2015.04.21.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150414|Meeting Minutes 2015.04.14.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150407|Meeting Minutes 2015.04.07.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150324|Meeting Minutes 2015.03.24.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150317|Meeting Minutes 2015.03.17.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150310|Meeting Minutes 2015.03.10.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150303|Meeting Minutes 2015.03.03.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150224|Meeting Minutes 2015.02.24.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150206|Meeting Minutes 2015.02.06.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150123|Meeting Minutes 2015.01.23.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140129|Meeting Minutes 2014.01.29.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140122|Meeting Minutes 2014.01.22.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140115|Meeting Minutes 2014.01.15.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131211|Meeting Minutes 2013.12.11.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131113|Meeting Minutes 2013.11.13.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131106|Meeting Minutes 2013.11.06.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131016|Meeting Minutes 2013.10.16.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131009|Meeting Minutes 2013.10.09.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131002|Meeting Minutes 2013.10.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130925|Meeting Minutes 2013.09.25.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130702|Meeting Minutes 2013.07.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130611|Meeting Minutes 2013.06.11.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130604|Meeting Minutes 2013.06.04.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130528|Meeting Minutes 2013.05.28.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130521|Meeting Minutes 2013.05.21.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130507|Meeting Minutes 2013.05.07.]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes&diff=387433VIATRA/DeveloperMeetingMinutes2015-06-23T12:45:08Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= EMF IncQuery Developer Meeting Minutes =<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150526|Meeting Minutes 2015.06.16.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150526|Meeting Minutes 2015.06.09.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150526|Meeting Minutes 2015.06.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150526|Meeting Minutes 2015.05.26.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150519|Meeting Minutes 2015.05.19.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150512|Meeting Minutes 2015.05.12.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150505|Meeting Minutes 2015.05.05.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150428|Meeting Minutes 2015.04.28.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150421|Meeting Minutes 2015.04.21.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150414|Meeting Minutes 2015.04.14.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150407|Meeting Minutes 2015.04.07.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150324|Meeting Minutes 2015.03.24.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150317|Meeting Minutes 2015.03.17.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150310|Meeting Minutes 2015.03.10.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150303|Meeting Minutes 2015.03.03.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150224|Meeting Minutes 2015.02.24.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150206|Meeting Minutes 2015.02.06.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150123|Meeting Minutes 2015.01.23.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140129|Meeting Minutes 2014.01.29.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140122|Meeting Minutes 2014.01.22.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140115|Meeting Minutes 2014.01.15.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131211|Meeting Minutes 2013.12.11.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131113|Meeting Minutes 2013.11.13.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131106|Meeting Minutes 2013.11.06.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131016|Meeting Minutes 2013.10.16.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131009|Meeting Minutes 2013.10.09.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131002|Meeting Minutes 2013.10.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130925|Meeting Minutes 2013.09.25.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130702|Meeting Minutes 2013.07.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130611|Meeting Minutes 2013.06.11.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130604|Meeting Minutes 2013.06.04.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130528|Meeting Minutes 2013.05.28.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130521|Meeting Minutes 2013.05.21.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130507|Meeting Minutes 2013.05.07.]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Transformation/Transformation_API&diff=386737VIATRA/Transformation/Transformation API2015-06-09T18:57:16Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= VIATRA Transformation API =<br />
<br />
* Based on [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|EVM]]<br />
* Relies on Xtend features such as extension methods and closures to be <br />
* [[VIATRA/Transformation_Language|Language concepts]] (for requirements overview)<br />
* Documentation for API in {{Git|viatra|org.eclipse.viatra.git}}<br />
* CI update site: <nowiki>https://hudson.eclipse.org/viatra/job/viatra-master/lastSuccessfulBuild/artifact/releng/org.eclipse.viatra.update/target/repository/</nowiki><br />
<br />
== Batch Transformation API ==<br />
<br />
Three extension classes used for transformations:<br />
* BatchTransformation - hides IncQueryEngine and RuleEngine; manages group initialization of rules - instead of an extension method, this can also be used as a base class<br />
* TransformationStatements - control structure<br />
* ModelManipulation - generic model manipulation primitives; hides details of EditingDomains (if necessary); implementation not batch transformation specific<br />
<br />
=== Batch Transformation Rules ===<br />
<br />
* Special rule type<br />
** Precondition + action<br />
** Life cycle:<br />
*** Stateless<br />
**** rule does not maintain state whether an activation has fired or not<br />
**** Lifecycle: firing: active -> active<br />
*** Stateful<br />
**** rule maintains whether an an activation has fired or not<br />
**** Lifecycle: firing: active -> fired<br />
=== (Batch) Transformation Statements ===<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! fireOne<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires a single activation<br />
|-<br />
! fireAllCurrent<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires all current activations. If the firings change the set of activations, it won't change the set of fired activations.<br />
|-<br />
! fireWhilePossible<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires the activations one by one. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|-<br />
! fireUntil<br />
| Batch Transformation Rule, break condition, (opt: filter)<br />
| After firing the first activation, it checks whether the break condition became true; if yes, exits, if not, it restarts. It does not store the initial set of activations. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|}<br />
<br />
== Incremental Transformation API ==<br />
<br />
The incremental API aims at defining and executing model transformations in an event-driven manner. In this case, the preconditions of the single transformations are checked on every related model change in an incremental fashion (using EMF-IncQuery) and the actions are fired once the preconditions are fulfilled. Model changes are captured as events, hence the naming of the basic concepts below.<br />
<br />
* ''EventDrivenTransformation'' - Similarly to the ''BatchTransformation'', it hides the IncQueryEngine and RuleEngine and serves as the basic concept for this part of the API.<br />
* ''EventContext'' - We distinguish two types or contexts of events: point and interval. The former one is described with a single point of appearance on the timeline; the latter one is characterized by its appearance ''and'' disappearance on the timeline. It's up to the user to select whether a transformation is associated with an event of point or interval context. In the background, the event context is translated into an EVM activation life cycle, which can be overridden by the user if required. This concept slightly resembles the concept of batch transformation rules of ''stateless'' and ''stateful'' life cycle.<br />
<br />
=== The event-driven transformation rule (EventDrivenTransformationRule) ===<br />
In contrast with the batch mode, in incremental mode, there are no arbitrarily assembled local conflict sets; instead: every transformation rule is handled in a global conflict set. ''EventDrivenTransformationRuleFactory'' is a factory designed for instantiating the rules.<br />
<br />
=== The essential ideology behind the API structure ===<br />
When designing the API, we reused the concepts of the ''fluent interface'' and the ''builder pattern''. It heavily utilizes the capabilities of Xtend, resulting in a concise way for defining rules, transformations and transformation groups, as presented below.<br />
<br />
=== Example: model transformations for automaton simulation ===<br />
'''Defining the event-driven transformation rule'''<br />
<br />
This is the precondition for your transformation.<br />
<source lang="java"><br />
val createEnabledTransitionRule = ruleFactory.createRule(EnabledTransitionMatcher::querySpecification) [<br />
eventModelManager.strategy.fireTransition(t, et)<br />
]<br />
</source><br />
The above snippet assumes the ''EnabledTransition'' EMF-IncQuery pattern to be defined, which the ''EnabledTransitionMatcher'' has been generated from. The expression in the closure is the action and is totally up to you to define. (In this case, the manager class maintaining the model will fire a transition.) <br />
You can also provide a name for the rule as well as override the default event context (point).<br />
<br />
'''Optionally grouping the rules into rule groups'''<br />
<br />
This one is pretty straightforward; just enumerate your rules in a closure:<br />
<source lang="java"><br />
def getRules() {<br />
new EventDrivenTransformationRuleGroup(<br />
createEnabledTransitionRule,<br />
createFinishedStateMachineRule,<br />
createTokenInTrapStateRule<br />
)<br />
}<br />
</source><br />
Remember, there is only one global conflict set for these rules to get conflicted. It does not really matter whether you group your rules or not, although it can make the further parts of code more concise.<br />
<br />
'''Register the transformation rules'''<br />
<br />
Once you have your transformation rules, there are just a few steps to take in order to register the rules into the execution schema. Let's look at this snippet:<br />
<source lang="java"><br />
def registerRules() {<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).create()<br />
}<br />
</source><br />
The benefits of the fluent API approach are obvious here. Notice the mandatory ''create()'' method at the tail of the method chain as the essence of the builder pattern. This method chain will deal with the following:<br />
# it instantiates an EventDrivenTransformation;<br />
# the resource or resource set the transformations are executed upon is passed to the transformation (''forSource()'');<br />
# the transformation rules are registered (''addRules()'');<br />
# in the background, the default conflict resolver (arbitrary CR) is selected to deal with global conflicts.<br />
<br />
If you opt to use a custom conflict resolver, here's how you do it:<br />
<source lang="java"><br />
def registerRulesWithCustomPriorities() {<br />
val fixedPriorityResolver = ConflictResolvers.createFixedPriorityResolver();<br />
fixedPriorityResolver.setPriority(createEnabledTransitionRule.ruleSpecification, 100)<br />
fixedPriorityResolver.setPriority(createFinishedStateMachineRule.ruleSpecification, 50)<br />
fixedPriorityResolver.setPriority(createTokenInTrapStateRule.ruleSpecification, 0)<br />
<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(fixedPriorityResolver).create()<br />
}<br />
</source><br />
<br />
However, as a useful feature, the API is capable to construct a fixed priority resolver based on the ''order of the rules'' handed over to the EventDrivenTransformation. So the results of the above code could be just achieved with this one:<br />
<source lang="java"><br />
def registerRulesWithAutomatedPriorities() {<br />
val resolver = new RuleOrderBasedFixedPriorityResolver()<br />
resolver.setPrioritiesFromScratch(new ArrayList(rules.ruleSpecifications))<br />
<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).setConflictResolver(resolver).create()<br />
}<br />
</source><br />
<br />
== Model Manipulation Primitives ==<br />
<br />
Model manipulation primitives are implemented by instances of IModelManipulations interface. Currently, two implementations are available:<br />
<br />
# SimpleModelManipulations - uses plain EMF API<br />
# ModelManipulationsWithEditingDomain - uses EMF Edit commands on EditingDomain instances<br />
<br />
If some transformation needs specific primitives (e.g. transaction support), new instances can introduce extra methods as required.<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! create<br />
| Resource; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the root of the selected resource<br />
|-<br />
! createChild <br />
| EObject (container); EReference; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the selected reference; the reference must be of containment type<br />
|-<br />
! addTo<br />
| EObject (container); EStructuralFeature; Object<br />
| Adds an existing object to the corresponding container with a reference; if using a reference it must *not* be of containment type<br />
|-<br />
! remove<br />
| EObject<br />
| Removes the EObject from the model<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature; Object<br />
| Removes an object from the selected container; when using a containment EReference, also removes it from the resource set<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature<br />
| Removes all objects from a multivalued feature; when using a containment EReference, also removes them from the resource set<br />
|-<br />
! set<br />
| EObject (container); EStructuralFeature; Object<br />
| Sets the value of a single-valued feature<br />
|-<br />
! move<br />
| EObject(s), EObject (new container), EStructuralFeature<br />
| Moves elements to a new container, and removes them from an old one. 'Remark': The implementation here is specific, as it relies on features of the index.<br />
|}<br />
<br />
== Examples ==<br />
<br />
=== Petri nets to State charts ===<br />
An example transformation is available by implementing the Petri net to State Charts case of the Transformation Tool Contest 2013.<br />
<br />
* Case description: http://planet-sl.org/community/index.php?option=com_community&view=groups&task=viewgroup&groupid=26&Itemid=387&lang=en<br />
* Implementation: https://github.com/izsob/TTC13-PN2SC-EIQ (look for the branch ''viatra-api'')<br />
** The following snippets are taken from this repository<br />
<br />
==== Setting up a transformation ====<br />
<br />
<source lang="java"><br />
class Pn2ScJobs {<br />
<br />
/* Transformation-related extension API */<br />
extension BatchTransformationRuleFactory ruleFactory = new BatchTransformationRuleFactory<br />
extension BatchTransformation transformation<br />
extension BatchTransformationStatements statements<br />
extension IModelManipulations manipulation<br />
<br />
/* Makes available the Literals of the EPackage for the manipulation API */<br />
extension StatechartsPackage chartPackage = StatechartsPackage.eINSTANCE<br />
<br />
Statechart stateChart<br />
Resource resource<br />
<br />
new(Resource resource) {<br />
/Storing transformation-specific input elements<br />
this.resource = resource<br />
this.stateChart = resource.contents.head as Statechart<br />
<br />
/* Extensions are initialized as normal fields in Xtend */<br />
transformation = new BatchTransformation(resource.resourceSet)<br />
statements = new BatchTransformationStatements(transformation)<br />
manipulation = new SimpleModelManipulations(transformation.iqEngine)<br />
}<br />
<br />
...<br />
<br />
}<br />
</source><br />
<br />
==== Defining rules, rulegroups ====<br />
<br />
Rules can be created using the factory methods of the BatchTransformation class; its actions can be described by an Xtend closure.<br />
<br />
If required, it is possible to extend BatchTransformationRule manually - both implementations are interchangeable.<br />
<br />
<source lang="java"><br />
/**<br />
* Map a PetriNet place to a base state in the StateChart with an "or" container.<br />
*/<br />
val createMapPlaceRuleSpecification = createRule(PlaceMatcher::querySpecification) [<br />
// create base b with b.name=p.name; and the state or, where or.contains={b}<br />
var or = stateChartResource.create(OR) as OR<br />
var basic = or.createChild(compound_Contains, basic) as Basic<br />
basic.set(state_Name, p.name)///name = p.name<br />
// create trace from place to or<br />
createTrace(p, or)<br />
]<br />
<br />
/**<br />
* Map a PetriNet transition to a hyperedge state in the StateChart without an "or" container.<br />
*/<br />
val createMapTransitionRuleSpecification = createRule(TransitionMatcher::querySpecification) [<br />
// create hyperEdge h with h.name=t.name (without an or container)<br />
var hyperEdge = stateChartResource.create(hyperEdge) as HyperEdge<br />
hyperEdge.name = t.name<br />
// create trace from transition to hyperEdge<br />
createTrace(t, hyperEdge)<br />
]<br />
<br />
/**<br />
* Create "next" edges in the StateChart between elements connected in the PetriNet.<br />
*/<br />
val createNextStateRuleSpecification = createRule(NextStateMatcher::querySpecification) [<br />
state1.addTo(state_Next, state2)<br />
]<br />
<br />
/**<br />
* Get rules for performing initial mapping<br />
*/<br />
def getInitialisationRules() {<br />
new TransformationRuleGroup(<br />
createMapPlaceRuleSpecification,<br />
createMapTransitionRuleSpecification,<br />
createNextStateRuleSpecification<br />
)<br />
}<br />
</source><br />
<br />
==== Executing rules, rule groups ====<br />
The primitives ask for a rule and filter<br />
<br />
* A filter is expressed by a collection of name-value pairs (available names come from the precondition pattern)<br />
* Parameter names not mentioned are unconstrained<br />
<br />
<source lang="java"><br />
val moveChildrenRule = createRule(EquivContainsMatcher::querySpecification) [<br />
state.moveTo(newP, compound_Contains)<br />
]<br />
// add children elements to OR of the StateChart<br />
moveChildrenRule.forall("namedElement" -> q)<br />
</source><br />
<br />
The following snippet shows that primitives also work with rule groups with the exact same syntax. The idea here is that the engine decides which rule of the group to execute (based on the ConflictResolver).<br />
<br />
<source lang="java"><br />
def transformPn2Sc() {<br />
// place->OR mapping<br />
initialisationRules.fireWhilePossible<br />
// execute AND and OR rules<br />
andOrRules.fireWhilePossible<br />
// clean orphaned root ORs; and create StateChart root<br />
finalisationRules.fireWhilePossible<br />
}<br />
</source><br />
<br />
=== Program understanding (Java code to state charts) ===<br />
<br />
The most up-to-date example can be found here: https://github.com/ujhelyiz/viatra2-programunderstanding<br />
<br />
=== Petri net simulator ===<br />
A very simple, batch transformation program is available from here: https://github.com/ujhelyiz/viatra-petrinet-simulator<br />
<br />
== Further ideas to evaluate ==<br />
<br />
* "Strict" API vs "relaxed" API<br />
** Everything presented here is a strict API<br />
*** Useful for research goals (e.g. analysis)<br />
*** Might be too strict for Java/EMF programmers<br />
** It might make sense to support transformation with bring-your-own-code style<br />
*** Currently almost all elements are optional in API: statements and model manipulations commands need not to be used -> simple Java/Xtend replacements possible<br />
*** Some simple wrappers might be needed to create RecordingCommands, etc.<br />
*[[VIATRA/Transformation_API/MWE2_Integration|MWE2-based transformation chain integration]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/RETE_Visualizer&diff=384439VIATRA/Query/UserDocumentation/RETE Visualizer2015-05-21T19:56:52Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= Rete Visualizer =<br />
<br />
== Installation ==<br />
<br />
# Install both the '''EMF-IncQuery Rete Visualization''' and '''GEF4 Zest SDK''' from the extra update sites (e.g. http://download.eclipse.org/incquery/updates-extra/integration)<br />
## ''Important!'' Because of API changes in the GEF4 Zest, the version available from the GEF update sites might or might not work.<br />
<br />
== Usage ==<br />
<br />
# Go to '''Window''' | '''Show View''' | '''Other...''' and choose '''Rete Visualizer'''.<br />
# Load the instance model and the pattern in ''Query Explorer''.<br />
# Click on the pattern name to visualize it.<br />
# To change the visualized Rete net, unload the pattern and load with the green start button.<br />
# You may change the layout by clicking the downward pointing triangle and going to the '''Layout''' menu.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/DeveloperDocumentation/QueryEngineArchitecture&diff=384234VIATRA/Query/DeveloperDocumentation/QueryEngineArchitecture2015-05-19T17:47:28Z<p>Ujhelyiz.mit.bme.hu: Created page with "== IncQuery Engine Internals == === Overview === File:IncQueryEngine.png === Most important concepts === * '''IncQueryEngine''': the central element of the API. * '''In..."</p>
<hr />
<div>== IncQuery Engine Internals ==<br />
<br />
=== Overview ===<br />
[[File:IncQueryEngine.png]]<br />
<br />
=== Most important concepts ===<br />
<br />
* '''IncQueryEngine''': the central element of the API.<br />
* '''IncQueryScope''': selects the model the IncQueryEngine should work on. The project itself implements only EMFScope right now.<br />
* '''RuntimeContext''': wrapper class for the query backends to access the model. The access can be both indexed and non-indexed.<br />
* '''IQueryBackend''': an executor of graph pattern matches; it instantiates IResultProviders. Query Backends needs to be registered to the IncQueryEngine itself.<br />
** '''RetePatternMatcher''' is the fully incremental implementation of the IResultProvider interface.<br />
** '''LocalSearchMatcher''' is a local search based implementation of the IResultProvider interface.<br />
* The '''Matcher''' interface is the public matcher API: generated instances are type-safe.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:IncQueryEngine.png&diff=384230File:IncQueryEngine.png2015-05-19T17:40:41Z<p>Ujhelyiz.mit.bme.hu: The internal architecture of the IncQueryEngine (high level overview)</p>
<hr />
<div>The internal architecture of the IncQueryEngine (high level overview)</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query&diff=384229VIATRA/Query2015-05-19T17:39:56Z<p>Ujhelyiz.mit.bme.hu: /* Contributor's Guide */</p>
<hr />
<div>= EMF-IncQuery Wiki Documentation =<br />
<br />
For the query language, we reuse the concepts of graph patterns (which is a key concept in many graph transformation tools) as a concise and easy way to specify complex structural model queries. High runtime performance is achieved by adapting incremental graph pattern matching techniques based on the Rete algorithm.<br />
<br />
We believe the average programmer using EMF models will like EMF-IncQuery for the following reasons:<br />
<br />
* declarative queries can be evaluated over EMF without manually traversing the models,<br />
* complex interrelated constellations of EMF objects can be easily formulated as a graph pattern,<br />
** the language is expressive and provides powerful features such as negation or counting,<br />
** graph patterns are composable and reusable,<br />
** queries can be evaluated with great freedom, i.e. input and output parameters can be selected at run-time,<br />
** some frequently encountered shortcomings of EMF’s interfaces are addressed:<br />
** easy and efficient enumeration of all instances of a class regardless of location,<br />
** simple backwards navigation along all kinds of references (even without eOpposite)<br />
** finding objects based on attribute value,<br />
* the incremental query evaluation mechanism offers a significant performance boost when frequently querying complex structural patterns with a moderate amount of modifications in-between (e.g. during continuous validation),<br />
* from the declarative representation of queries, pattern matcher code is generated which can be distributed as Eclipse plug-ins with very few dependencies.<br />
<br />
<br />
== EMF-IncQuery User Documentation ==<br />
* Developing Incremental Model Queries using the EMF-IncQuery Tooling<br />
** [[EMFIncQuery/UserDocumentation/Installation|Installing EMF-IncQuery]]<br />
** [[EMFIncQuery/UserDocumentation/QueryLanguage|A Short Introduction to the Query Language]]<br />
** [[ EMFIncQuery/UserDocumentation/QueryDevelopment|Getting started with Query Development]]<br />
** [[EMFIncQuery/UserDocumentation/RETE_Visualizer|RETE Visualizer]]<br />
** [[EMFIncQuery/UserDocumentation/LocalSearch_DebuggerTooling|Local Search Debugger Tooling]]<br />
** [[EMFIncQuery/UserDocumentation/DebuggerTooling|EMF-IncQuery Debugger Tooling]] (since 0.8.0)<br />
** [[EMFIncQuery/UserDocumentation/SDK/QueryHotspotTesting|Finding query evaluation hotspots]] (since 1.0.0)<br />
* Using the EMF-IncQuery Runtime library<br />
** [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless (standalone) execution of EMF-IncQuery queries and unit tests]]<br />
** [[EMFIncQuery/UserDocumentation/API|API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]]<br />
** [[EMFIncQuery/UserDocumentation/API/RunOnce|Run once querying API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/BaseIndexer|IncQuery Base Indexer]]<br />
** [[EMFIncQuery/UserDocumentation/AdvancedPatterns|Advanced pattern language constructs]] <br />
* Integration Components<br />
** [[EMFIncQuery/UserDocumentation/Databinding|Databinding]]<br />
** [[EMFIncQuery/UserDocumentation/Validation|Validation Framework]]<br />
** [[EMFIncQuery/UserDocumentation/Query_Based_Features|Defining Query-based Features]]<br />
** [[EMFIncQuery/UserDocumentation/Surrogate_Queries|Surrogate queries for existing derived features]]<br />
** [[EMFIncQuery/UserDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
** [[EMFIncQuery/UMLSupport|UML Support]]<br />
* [[EMFIncQuery/UserDocumentation/Examples|Examples]]<br />
* [[EMFIncQuery/UserDocumentation/Build|EMF-IncQuery in CI Environments (Maven artifacts)]] (since 0.8.0)<br />
* Reporting bugs or requesting new features<br />
** [[EMFIncQuery/UserDocumentation/IssueTracking|Issue tracking]]<br />
<br />
== Contributor's Guide ==<br />
<br />
* Developer's Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/DevEnvironment|Setting up the Development Environment]]<br />
** [[EMFIncQuery/DeveloperDocumentation/BuildConfig|The EMF-IncQuery Build Configuration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IssueTracking|Issue Reporting and Management]]<br />
** [[EMFIncQuery/DeveloperDocumentation/FeatureSetAndTesting|Feature Set and Testing]]<br />
* Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/Model_connectors|Model Connectors]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
** [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|Event-driven Virtual Machine]]<br />
** [[EMFIncQuery/DeveloperDocumentation/Builder|Builder Architecture]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQueryXcore|Notes on IncQuery & Xcore integration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQueryEngineArchitecture|Overview of the IncQuery Engine Internals]]<br />
** [[EMFIncQuery/DeveloperDocumentation/QueryProcessing|Query Processing]]<br />
** [[EMFIncQuery/DeveloperDocumentation/LocalSearch|Local Search]]<br />
* Developer Meeting Minutes<br />
** [[EMFIncQuery/DeveloperMeetingMinutes|Meeting minutes]]<br />
<br />
== Releases ==<br />
* Version 0.7.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.7.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/MigrateTo0.7|Migration guide]]<br />
** Known issues affecting version 0.7.1 [[EMFIncQuery/Releases/KnownIssuesFor0.7.1|fixed in 0.7.2]]<br />
* Version 0.8.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.8.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.8|New and Noteworthy]]<br />
** [[EMFIncQuery/Releases/MigrateTo0.8|Migration guide]]<br />
** Known issues affecting version 0.8.1 [[EMFIncQuery/Releases/KnownIssuesFor0.8.1|fixed in 0.8.2]]<br />
* Version 0.9.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.9.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.9|New and Noteworthy]]<br />
[[Category:EmfIncQuery]]<br />
* Version 1.0.0<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy1.0|New and Noteworthy]]<br />
** [[EMFIncQuery/Releases/MigrateTo1.0|Migration guide]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Transformation/Transformation_API&diff=382421VIATRA/Transformation/Transformation API2015-04-21T11:27:57Z<p>Ujhelyiz.mit.bme.hu: /* Examples */</p>
<hr />
<div>= VIATRA Transformation API =<br />
<br />
* Based on [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|EVM]]<br />
* Relies on Xtend features such as extension methods and closures to be <br />
* [[VIATRA/Transformation_Language|Language concepts]] (for requirements overview)<br />
* Documentation for API in {{Git|viatra|org.eclipse.viatra.git}}<br />
* CI update site: <nowiki>https://hudson.eclipse.org/viatra/job/viatra-master/lastSuccessfulBuild/artifact/releng/org.eclipse.viatra.update/target/repository/</nowiki><br />
<br />
== Batch Transformation API ==<br />
<br />
Three extension classes used for transformations:<br />
* BatchTransformation - hides IncQueryEngine and RuleEngine; manages group initialization of rules - instead of an extension method, this can also be used as a base class<br />
* TransformationStatements - control structure<br />
* ModelManipulation - generic model manipulation primitives; hides details of EditingDomains (if necessary); implementation not batch transformation specific<br />
<br />
=== Batch Transformation Rules ===<br />
<br />
* Special rule type<br />
** Precondition + action<br />
** Life cycle:<br />
*** Stateless<br />
**** rule does not maintain state whether an activation has fired or not<br />
**** Lifecycle: firing: active -> active<br />
*** Stateful<br />
**** rule maintains whether an an activation has fired or not<br />
**** Lifecycle: firing: active -> fired<br />
=== (Batch) Transformation Statements ===<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! fireOne<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires a single activation<br />
|-<br />
! fireAllCurrent<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires all current activations. If the firings change the set of activations, it won't change the set of fired activations.<br />
|-<br />
! fireWhilePossible<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires the activations one by one. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|-<br />
! fireUntil<br />
| Batch Transformation Rule, break condition, (opt: filter)<br />
| After firing the first activation, it checks whether the break condition became true; if yes, exits, if not, it restarts. It does not store the initial set of activations. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|}<br />
<br />
== Incremental Transformation API ==<br />
<br />
The incremental API aims at defining and executing model transformations in an event-driven manner. In this case, the preconditions of the single transformations are checked on every related model change in an incremental fashion (using EMF-IncQuery) and the actions are fired once the preconditions are fulfilled. Model changes are captured as events, hence the naming of the basic concepts below.<br />
<br />
* ''EventDrivenTransformation'' - Similarly to the ''BatchTransformation'', it hides the IncQueryEngine and RuleEngine and serves as the basic concept for this part of the API.<br />
* ''EventContext'' - We distinguish two types or contexts of events: point and interval. The former one is described with a single point of appearance on the timeline; the latter one is characterized by its appearance ''and'' disappearance on the timeline. It's up to the user to select whether a transformation is associated with an event of point or interval context. In the background, the event context is translated into an EVM activation life cycle, which can be overridden by the user if required. This concept slightly resembles the concept of batch transformation rules of ''stateless'' and ''stateful'' life cycle.<br />
<br />
=== The event-driven transformation rule (EventDrivenTransformationRule) ===<br />
In contrast with the batch mode, in incremental mode, there are no arbitrarily assembled local conflict sets; instead: every transformation rule is handled in a global conflict set. ''EventDrivenTransformationRuleFactory'' is a factory designed for instantiating the rules.<br />
<br />
=== The essential ideology behind the API structure ===<br />
When designing the API, we reused the concepts of the ''fluent interface'' and the ''builder pattern''. It heavily utilizes the capabilities of Xtend, resulting in a concise way for defining rules, transformations and transformation groups, as presented below.<br />
<br />
=== Example: model transformations for automaton simulation ===<br />
'''Defining the event-driven transformation rule'''<br />
<br />
This is the precondition for your transformation.<br />
<source lang="java"><br />
val createEnabledTransitionRule = ruleFactory.createRule(EnabledTransitionMatcher::querySpecification) [<br />
eventModelManager.strategy.fireTransition(t, et)<br />
]<br />
</source><br />
The above snippet assumes the ''EnabledTransition'' EMF-IncQuery pattern to be defined, which the ''EnabledTransitionMatcher'' has been generated from. The expression in the closure is the action and is totally up to you to define. (In this case, the manager class maintaining the model will fire a transition.) <br />
You can also provide a name for the rule as well as override the default event context (point).<br />
<br />
'''Optionally grouping the rules into rule groups'''<br />
<br />
This one is pretty straightforward; just enumerate your rules in a closure:<br />
<source lang="java"><br />
def getRules() {<br />
new EventDrivenTransformationRuleGroup(<br />
createEnabledTransitionRule,<br />
createFinishedStateMachineRule,<br />
createTokenInTrapStateRule<br />
)<br />
}<br />
</source><br />
Remember, there is only one global conflict set for these rules to get conflicted. It does not really matter whether you group your rules or not, although it can make the further parts of code more concise.<br />
<br />
'''Register the transformation rules'''<br />
<br />
Once you have your transformation rules, there are just a few steps to take in order to register the rules into the execution schema. Let's look at this snippet:<br />
<source lang="java"><br />
def registerRules() {<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).create()<br />
}<br />
</source><br />
The benefits of the fluent API approach are obvious here. Notice the mandatory ''create()'' method at the tail of the method chain as the essence of the builder pattern. This method chain will deal with the following:<br />
# it instantiates an EventDrivenTransformation;<br />
# the resource or resource set the transformations are executed upon is passed to the transformation (''forSource()'');<br />
# the transformation rules are registered (''addRules()'');<br />
# in the background, the default conflict resolver (arbitrary CR) is selected to deal with global conflicts.<br />
<br />
If you opt to use a custom conflict resolver, here's how you do it:<br />
<source lang="java"><br />
def registerRulesWithCustomPriorities() {<br />
val fixedPriorityResolver = ConflictResolvers.createFixedPriorityResolver();<br />
fixedPriorityResolver.setPriority(createEnabledTransitionRule.ruleSpecification, 100)<br />
fixedPriorityResolver.setPriority(createFinishedStateMachineRule.ruleSpecification, 50)<br />
fixedPriorityResolver.setPriority(createTokenInTrapStateRule.ruleSpecification, 0)<br />
<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(fixedPriorityResolver).create()<br />
}<br />
</source><br />
<br />
However, as a useful feature, the API is capable to construct a fixed priority resolver based on the ''order of the rules'' handed over to the EventDrivenTransformation. So the results of the above code could be just achieved with this one:<br />
<source lang="java"><br />
def registerRulesWithAutomatedPriorities() {<br />
val resolver = new RuleOrderBasedFixedPriorityResolver()<br />
resolver.setPrioritiesFromScratch(new ArrayList(rules.ruleSpecifications))<br />
<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).setConflictResolver(resolver).create()<br />
}<br />
</source><br />
<br />
== Model Manipulation Primitives ==<br />
<br />
Model manipulation primitives are implemented by instances of IModelManipulations interface. Currently, two implementations are available:<br />
<br />
# SimpleModelManipulations - uses plain EMF API<br />
# ModelManipulationsWithEditingDomain - uses EMF Edit commands on EditingDomain instances<br />
<br />
If some transformation needs specific primitives (e.g. transaction support), new instances can introduce extra methods as required.<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! create<br />
| Resource; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the root of the selected resource<br />
|-<br />
! createChild <br />
| EObject (container); EReference; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the selected reference; the reference must be of containment type<br />
|-<br />
! addTo<br />
| EObject (container); EStructuralFeature; Object<br />
| Adds an existing object to the corresponding container with a reference; if using a reference it must *not* be of containment type<br />
|-<br />
! remove<br />
| EObject<br />
| Removes the EObject from the model<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature; Object<br />
| Removes an object from the selected container; when using a containment EReference, also removes it from the resource set<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature<br />
| Removes all objects from a multivalued feature; when using a containment EReference, also removes them from the resource set<br />
|-<br />
! set<br />
| EObject (container); EStructuralFeature; Object<br />
| Sets the value of a single-valued feature<br />
|-<br />
! move<br />
| EObject(s), EObject (new container), EStructuralFeature<br />
| Moves elements to a new container, and removes them from an old one. 'Remark': The implementation here is specific, as it relies on features of the index.<br />
|}<br />
<br />
== Examples ==<br />
<br />
=== Program understanding (Java code to state charts) ===<br />
<br />
The most up-to-date example can be found here: https://github.com/ujhelyiz/viatra2-programunderstanding<br />
<br />
=== Petri net simulator ===<br />
A very simple, batch transformation program is available from here: https://github.com/ujhelyiz/viatra-petrinet-simulator<br />
<br />
=== Petri nets to State charts ===<br />
A (not very well tested) example transformation is available by implementing the Petri net to State Charts case of the Transformation Tool Contest 2013.<br />
<br />
* Case description: http://planet-sl.org/community/index.php?option=com_community&view=groups&task=viewgroup&groupid=26&Itemid=387&lang=en<br />
* Implementation: https://github.com/izsob/TTC13-PN2SC-EIQ (look for the branch ''viatra-api'')<br />
** The following snippets are taken from this repository<br />
<br />
==== Setting up a transformation ====<br />
<br />
<source lang="java"><br />
class Pn2ScJobs {<br />
<br />
/* Transformation-related extension API */<br />
extension BatchTransformationRuleFactory ruleFactory = new BatchTransformationRuleFactory<br />
extension BatchTransformation transformation<br />
extension BatchTransformationStatements statements<br />
extension IModelManipulations manipulation<br />
<br />
/* Makes available the Literals of the EPackage for the manipulation API */<br />
extension StatechartsPackage chartPackage = StatechartsPackage.eINSTANCE<br />
<br />
Statechart stateChart<br />
Resource resource<br />
<br />
new(Resource resource) {<br />
/Storing transformation-specific input elements<br />
this.resource = resource<br />
this.stateChart = resource.contents.head as Statechart<br />
<br />
/* Extensions are initialized as normal fields in Xtend */<br />
transformation = new BatchTransformation(resource.resourceSet)<br />
statements = new BatchTransformationStatements(transformation)<br />
manipulation = new SimpleModelManipulations(transformation.iqEngine)<br />
}<br />
<br />
...<br />
<br />
}<br />
</source><br />
<br />
==== Defining rules, rulegroups ====<br />
<br />
Rules can be created using the factory methods of the BatchTransformation class; its actions can be described by an Xtend closure.<br />
<br />
If required, it is possible to extend BatchTransformationRule manually - both implementations are interchangeable.<br />
<br />
<source lang="java"><br />
/**<br />
* Map a PetriNet place to a base state in the StateChart with an "or" container.<br />
*/<br />
val createMapPlaceRuleSpecification = createRule(PlaceMatcher::querySpecification) [<br />
// create base b with b.name=p.name; and the state or, where or.contains={b}<br />
var or = stateChartResource.create(OR) as OR<br />
var basic = or.createChild(compound_Contains, basic) as Basic<br />
basic.set(state_Name, p.name)///name = p.name<br />
// create trace from place to or<br />
createTrace(p, or)<br />
]<br />
<br />
/**<br />
* Map a PetriNet transition to a hyperedge state in the StateChart without an "or" container.<br />
*/<br />
val createMapTransitionRuleSpecification = createRule(TransitionMatcher::querySpecification) [<br />
// create hyperEdge h with h.name=t.name (without an or container)<br />
var hyperEdge = stateChartResource.create(hyperEdge) as HyperEdge<br />
hyperEdge.name = t.name<br />
// create trace from transition to hyperEdge<br />
createTrace(t, hyperEdge)<br />
]<br />
<br />
/**<br />
* Create "next" edges in the StateChart between elements connected in the PetriNet.<br />
*/<br />
val createNextStateRuleSpecification = createRule(NextStateMatcher::querySpecification) [<br />
state1.addTo(state_Next, state2)<br />
]<br />
<br />
/**<br />
* Get rules for performing initial mapping<br />
*/<br />
def getInitialisationRules() {<br />
new TransformationRuleGroup(<br />
createMapPlaceRuleSpecification,<br />
createMapTransitionRuleSpecification,<br />
createNextStateRuleSpecification<br />
)<br />
}<br />
</source><br />
<br />
==== Executing rules, rule groups ====<br />
The primitives ask for a rule and filter<br />
<br />
* A filter is expressed by a collection of name-value pairs (available names come from the precondition pattern)<br />
* Parameter names not mentioned are unconstrained<br />
<br />
<source lang="java"><br />
val moveChildrenRule = createRule(EquivContainsMatcher::querySpecification) [<br />
state.moveTo(newP, compound_Contains)<br />
]<br />
// add children elements to OR of the StateChart<br />
moveChildrenRule.forall("namedElement" -> q)<br />
</source><br />
<br />
The following snippet shows that primitives also work with rule groups with the exact same syntax. The idea here is that the engine decides which rule of the group to execute (based on the ConflictResolver).<br />
<br />
<source lang="java"><br />
def transformPn2Sc() {<br />
// place->OR mapping<br />
initialisationRules.fireWhilePossible<br />
// execute AND and OR rules<br />
andOrRules.fireWhilePossible<br />
// clean orphaned root ORs; and create StateChart root<br />
finalisationRules.fireWhilePossible<br />
}<br />
</source><br />
<br />
== Further ideas to evaluate ==<br />
<br />
* "Strict" API vs "relaxed" API<br />
** Everything presented here is a strict API<br />
*** Useful for research goals (e.g. analysis)<br />
*** Might be too strict for Java/EMF programmers<br />
** It might make sense to support transformation with bring-your-own-code style<br />
*** Currently almost all elements are optional in API: statements and model manipulations commands need not to be used -> simple Java/Xtend replacements possible<br />
*** Some simple wrappers might be needed to create RecordingCommands, etc.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/GettingStarted&diff=380953VIATRA/Query/UserDocumentation/GettingStarted2015-03-30T16:34:25Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>=Installing EMF-IncQuery=<br />
<br />
== Dependencies ==<br />
EMF-IncQuery depends on recent version of Xtext/Xtend.<br />
<br />
{| class="wikitable"<br />
!<br />
! Xtext 2.3<br />
! Xtext 2.4<br />
! Xtext 2.5<br />
! Xtext 2.6<br />
! Xtext 2.7<br />
! Xtext 2.8<br />
|-<br />
! EMF-IncQuery 0.7<br />
|| Compatibility branch || Yes || No || No || No || No<br />
|-<br />
! EMF-IncQuery 0.8<br />
|| No || Runtime only || Runtime only* || Yes || Runtime only || Runtime only ||<br />
|-<br />
! EMF-IncQuery 0.9<br />
|| No || Runtime only || Runtime only || Runtime only || Yes || Runtime only ||<br />
|-<br />
! EMF-IncQuery 1.0<br />
|| No || Runtime only || Runtime only || Runtime only || Runtime only || Yes ||<br />
|}<br />
Remarks:<br />
* The codebase of EMF-IncQuery 0.8 is compatible with Xtext 2.5, but its editor components needs to be regenerated. To avoid confusion, the code base states it requires Xtext 2.6; but it can trivially be updated to work with 2.5 (after a regeneration of editor).<br />
<br />
== Installation ==<br />
The main update site provides both the EMF-IncQuery runtime and the query development extensions for Eclipse. It is recommended to install as few features directly as needed, rely on the p2 installer to download required features:<br />
* Select the ''EMF-IncQuery SDK'' feature<br />
* If you want to use IncQuery with Graphiti or GMF, select the features ''GMF Support for EMF-IncQuery'' or ''Graphiti Support for EMF-IncQuery'', respectively<br />
* If the corresponding Xtext version is not available directly from the main eclipse update site, consult the [https://www.eclipse.org/Xtext/download.html official Xtext download page].<br />
<br />
=== Additional features ===<br />
* [[EMFIncQuery/UserDocumentation/RETE_Visualizer|Rete visualizer]] - experimental as of the [[GEF/GEF4]] Zest dependency<br />
* Zest graph support for Viewers framework - experimental as of the [[GEF/GEF4]] Zest dependency<br />
<br />
Additionally, this update site contains the latest GEF4 Zest to ease the installation. Because of the frequent changes in GEF4 Zest, the graph viewer components are only tested with this bundled version of Zest - other versions may or may not work.<br />
<br />
= First steps =<br />
The built-in cheat sheet should help you with the first steps. We also maintain a [[EMFIncQuery/UserDocumentation/QueryLanguage | web-based tutorial]]. Additionally, you can check the School and BPMN introductory walkthrough examples to help you get started.<br />
<br />
== Examples ==<br />
We have a list of examples available in [[EMFIncQuery/UserDocumentation/Examples]].</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Addon/Validation&diff=380227VIATRA/Addon/Validation2015-03-18T23:15:17Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>=EMF-IncQuery Validation Framework=<br />
<br />
EMF-IncQuery provides facilities to create validation rules based on the pattern language of the framework.<br />
These rules can be evaluated on various EMF instance models and upon violations of constraints, markers are automatically created in the Eclipse Problems View.<br />
<br />
==Example use case==<br />
<br />
The following scenario describes and illustrates the way to use the framework for validation purposes (see also the [https://incquery.net/incquery/examples/bpmn BPMN example]):<br />
<br />
# Create an EMF-IncQuery project with some patterns<br />
# Annotate some pattern with the @Constraint annotation - these will be the constraints. In particular, these patterns will be treated as queries that find the violations of the contraint. [[Image:EMFIncQuery_Validation_1.png]]<br />
# Add the generated .validation project to your run configuration (along with the base EMF-IncQuery plug-in)<br />
# Initialize the validation framework on some instance model; use the UI context menu on an EMF editor to do so.<br />
# Upon constraint violation markers will be placed in the Problems view. Note that the markers are data-bound to corresponding model elements and the labels will be automatically refreshed (when the model changes). [[Image:EMFIncQuery_Validation_2.png]]<br />
<br />
==Annotations==<br />
<br />
The @Constraint annotation can be used to mark an eiq pattern as a validation rule. If the framework finds at least one pattern with such annotation, an additional .validation project will be generated. This project will be used by the validation framework later in your runtime Eclipse configuration.<br />
<br />
===Annotation parameters===<br />
<br />
* location: The location of constraint represents the pattern parameter (the object) the constraint violation needs to be attached to.<br />
* message: The message to display when the constraint violation is found. The message may refer the parameter variables between $ symbols, or their EMF features, such as in $Param1.name$.<br />
* severity: "warning" or "error"<br />
* targetEditorId: An Eclipse editor ID where the validation framework should register itself to the context menu. Use "*" as a wildcard if the constraint should be used always when validation is started.<br />
<br />
===Generated validation plug-in===<br />
<br />
The generated .validation project will create a subclass of <code>org.eclipse.incquery.validation.runtime.Constraint</code> for each one of the patterns annotated with @Constraint.<br />
<br />
==Example and useful resources==<br />
<br />
* Please see the [https://incquery.net/incquery/examples/bpmn BPMN example] which demonstrates the usage of the @Constraint annotation.<br />
* The <code>org.eclipse.incquery.validation.runtime.ConstraintAdapter</code> and <code>org.eclipse.incquery.validation.runtime.ConstraintViolation</code> classes demonstrate the usage of the generated validation code inside the validation framework.<br />
<br />
==ConstraintAdapter and ConstraintViolation highlights==<br />
<br />
The validation framework collects all of the Constraints that applies to the constraint extension point schema (defined under org.eclipse.incquery.validation.runtime/schema/constraint.exsd). These constraints are initialized on the loaded instance models and upon constraint violation an appropriate error marker is placed in the runtime Eclipse's Problems View.<br />
<br />
First for each collected constraint and instance model a ConstraintAdapter is created which will maintain the match set of the pattern (annotated with @Constraint); these matches are constraint violations, that the user needs to be informed about. For each match of the pattern a ConstraintViolation is instantiated, which is responsible for marker creation/update/deletion.<br />
<br />
The ConstraintViolation class uses data binding facilities to register the appropriate callback methods on the location objects of the Constraint, this will result in marker text update when an attribute of some location object is modified.<br />
<br />
=New validation framework in EMF-IncQuery 1.0.0=<br />
<br />
Based on the work of Bálint Lóránd, we have a new validation framework that provides a more generic API than simply creating Eclipse problem markers. This new framework has a validation specific API with concepts like constraints and violations, while also significantly increases the descriptive power of the @Constraint annotation by introducing keys and symmetric parameters.<br />
<br />
== Main concepts ==<br />
<br />
=== Constraint specification ===<br />
<br />
A constraint specification represents a well-formedness or structural validation rule that is specified with concepts from metamodels and can be evaluated over instance models.<br />
<br />
E.g. a constraint specification is "A terminated data port cannot be the end of a port connection", where "terminated", "data port", "port connection" and "connection end" are concepts in the metamodel.<br />
<br />
The constraint specification contains:<br />
* the converting mechanism for creating the location information for a violation<br />
* the format message that is used to create the message of a violation<br />
* the severity level (e.g. error, warning)<br />
<br />
When constraint specifications are represented by EMF-IncQuery patterns, the corresponding query specification is stored.<br />
<br />
=== Constraint ===<br />
<br />
We differentiate between '''Constraint Specification''' that represents the validation rule and '''Constraint''' that represents the instantiation of a constraint specification on a validation engine.<br />
<br />
Each constraint stores:<br />
* its specification<br />
* validation engine <br />
<br />
It provides capabilities for:<br />
* listing the set of violations<br />
* registering listeners for notifications on the changes in the violation set and other events related to the life cycle of the constraint.<br />
<br />
For constraints specified by EMF-IncQuery patterns, the matcher is stored.<br />
<br />
=== Violation ===<br />
<br />
A violation is set of model elements in an instance model that satisfy the specification of a constraint.<br />
<br />
E.g. for the above constraint, a violation is a port P which is terminated and a port connection PC with "PC.end = P".<br />
<br />
Each violation has:<br />
* a corresponding constraint<br />
* a location (one or more model elements that are relevant for the violation (e.g. the port and the port connection in the example)<br />
* a formatted message.<br />
<br />
The violation should provide capabilities for<br />
* registering listeners for notifications on life cycle events, e.g. a change in the message.<br />
<br />
For violation of constraints from EMF-IncQuery patterns, the match is also stored.<br />
<br />
=== Validation Engine ===<br />
<br />
A validation engine is responsible for managing the constraints existing in the scope of an EMF-IncQuery Engine (e.g. resource set) for a set of constraint specifications added to the validation engine.<br />
<br />
The validation engine provides capabilities for<br />
* adding constraint specifications<br />
* listing the set of constraints<br />
* registering listeners for notifications on the changes in the constraint set and other events related to the life cycle of the validation engine.<br />
<br />
=== Validation Manager ===<br />
<br />
The validation manager is singleton that serves as a single entry point for using the validation.<br />
<br />
that provides capabilities for<br />
* accessing the constraint specifications registered through extensions (see EMF-IncQuery @Constraint annotation)<br />
* initializing a new validation engine<br />
<br />
==Annotation parameters==<br />
<br />
* '''key''' (list of parameter names as strings): The keys of a constraint represent the parameters that together identify a given violation. Multiple matches of the same constraint pattern with the same parameter values for keys will be considered as a single violation. Non-key parameters can be accessed as tuples by the API. <br />
* '''message''' (format string): The message to display when the constraint violation is found. The message may refer the key variables between $ symbols, or their EMF features, such as in $keyParam1.name$.<br />
* '''severity''' (string): "info", "warning" or "error"<br />
* '''targetEditorId''' (string): An Eclipse editor ID where the validation framework should register itself to the context menu. Use "*" as a wildcard if the constraint should be used always when validation is started.<br />
* '''symmetric''' (possibly multiple list of parameter names as strings): Parameters listed as symmetric are considered to correspond to the same violation for matches where the values are in a different permutation. Symmetric parameters can be either keys or non-keys, mixing is not allowed.<br />
<br />
===Validation API===<br />
<br />
Once you specified your constraints with patterns and the @Constraint annotation, you can either use the marker based validation as before, or use the API to process violations yourself:<br />
<br />
<source lang="java"><br />
<br />
ResourceSet myModel; // already initialized<br />
Logger myLogger; // Log4J logger, use Logger.getLogger(this.class) if you need one<br />
IConstraintSpecification constraintSpec = new MyPatternNameConstraint0(); // generated for pattern called MyPatternName<br />
<br />
ValidationEngine validationEngine = new ValidationEngine(notifier, logger);<br />
IConstraint constraint = validationEngine.addConstraintSpecification(constraintSpecification);<br />
validationEngine.initialize();<br />
<br />
Collection<IViolation> violations = constraint.listViolations();<br />
for(IViolation violation : violations) {<br />
System.out.println(violation.getMessage());<br />
Map<String, Object> keyMap = violation.getKeyObjects()<br />
for(String key : keyMap.keySet()){<br />
System.out.println("Key " + key + " is " + keyMap.get(key));<br />
}<br />
}<br />
<br />
// you can filter violations<br />
Collection<IViolation> filteredViolations = constraint.listViolations(new IViolationFilter(){<br />
public boolean apply(IViolation violation){<br />
return violation.getMessage().contains("MyFilterWord");<br />
}<br />
});<br />
<br />
// you can add listeners on IConstraint to get notified on violation list changes<br />
constraint.addListener(new ConstraintListener(){<br />
public void violationAppeared(IViolation violation){<br />
System.out.println("Appeared: " + violation.getMessage());<br />
}<br />
public void violationDisappeared(IViolation violation){<br />
System.out.println("Disappeared: " + violation.getMessage());<br />
}<br />
});<br />
<br />
// or on IViolations to get notified of message and parameter changes<br />
violations.iterator().next().addListener(new ViolationListener(){<br />
public void violationEntryAppeared(IViolation violation, IEntry entry){<br />
System.out.println("Entry appeared: " + entry);<br />
}<br />
<br />
public void violationMessageUpdated(IViolation violation){<br />
System.out.println("Message updated: " + violation.getMessage());<br />
}<br />
<br />
public void violationEntryDisappeared(IViolation violation, IEntry entry){<br />
System.out.println("Entry disappeared: " + entry);<br />
}<br />
});<br />
<br />
// you can also remove constraint specifications from an engine<br />
validationEngine.removeConstraintSpecification(constraintSpecification);<br />
<br />
// and dispose it when no longer needed<br />
validationEngine.dispose();<br />
</source></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/API/Advanced&diff=379426VIATRA/Query/UserDocumentation/API/Advanced2015-03-06T10:00:52Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= Overview =<br />
<br />
This page overviews advanced use-cases for EMF-IncQuery. The topics cover <br />
<br />
*the '''Generic API''', to be used when the features supported by the generated API do not suffice (e.g. when working with dynamically defined patterns, or patterns whose handles are not known at compile time) <br />
*'''Advanced change processing APIs''', and '''advanced lifecycle management techniques''' to be used for performance-critical and/or resource-constrained applications <br />
*'''IncQuery Base''', the low-level query and indexer layer underneath EMF-IncQuery pattern matchers<br />
*'''logging in EMF-IncQuery''', which is provided by hierarchic Log4J loggers.<br />
<br />
== Running example ==<br />
<br />
All the code examples and explanations will be given in the context of the [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless]] example. The up-to-date sample source code to this page is found in Git here: http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless Most notably, <br />
<br />
*the patterns are found in [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/headlessQueries.incquery/src/headless/headlessQueries.eiq headlessQueries.eiq] <br />
*and the API usage samples are found in [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/org.eclipse.incquery.application/src/org/eclipse/incquery/application/common/IncQueryHeadless.java IncQueryHeadless.java] and [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/org.eclipse.incquery.application/src/org/eclipse/incquery/application/common/IncQueryHeadlessAdvanced.java IncQueryHeadlessAdvanced.java]<br />
<br />
== Javadoc ==<br />
<br />
The most up-to-date Javadocs for the EMF-IncQuery API can be found online at http://eclipse.org/incquery/javadoc/<br />
<br />
= The IncQuery Generic API =<br />
<br />
The "generic" API differs from the generated one in two key aspects: <br />
<br />
*it can be used to apply queries and use other IncQuery features '''without''' generating code and loading the resulting bundles into the running configuration. In other words, you just need to supply the EMF-based in-memory representation (an instance of the Pattern class) <br />
*the generic API is not "type safe" in the sense that the Java types of your pattern variables is not known and needs to be handled dynamically (e.g. by instanceof - typecase combos).<br />
<br />
== Initializing matchers and accessing results ==<br />
In EMF-IncQuery 0.8 the generic API has changed significantly. Most importantly, it has been moved into the patternlanguage.emf plug-in, and there is no UI dependency required anymore. For more details, see [[EMFIncQuery/Releases/MigrateTo0.8|the migration guide]]; for the old version of this content see [[EMFIncQuery/UserDocumentation/API/Advanced/Archive]]<br />
=== Sample code ===<br />
Using the Generic API:<br />
<source lang="java"><br />
public String executeDemo_GenericAPI_LoadFromEIQ(String modelPath, String patternFQN) {<br />
final StringBuilder results = new StringBuilder();<br />
Resource resource = loadModel(modelPath);<br />
if (resource != null) {<br />
try {<br />
// get all matches of the pattern<br />
// create an *unmanaged* engine to ensure that noone else is going<br />
// to use our engine<br />
AdvancedIncQueryEngine engine = AdvancedIncQueryEngine.createUnmanagedEngine(resource);<br />
// instantiate a pattern matcher through the registry, by only knowing its FQN<br />
// assuming that there is a pattern definition registered matching 'patternFQN'<br />
<br />
Pattern p = null;<br />
<br />
// Initializing Xtext-based resource parser<br />
// Do not use if EMF-IncQuery tooling is loaded!<br />
new EMFPatternLanguageStandaloneSetup().createInjectorAndDoEMFRegistration();<br />
<br />
//Loading pattern resource from file<br />
ResourceSet resourceSet = new ResourceSetImpl();<br />
URI fileURI = URI.createPlatformPluginURI("headlessQueries.incquery/src/headless/headlessQueries.eiq", false);<br />
Resource patternResource = resourceSet.getResource(fileURI, true);<br />
<br />
// navigate to the pattern definition that we want<br />
if (patternResource != null) {<br />
if (patternResource.getErrors().size() == 0 && patternResource.getContents().size() >= 1) {<br />
EObject topElement = patternResource.getContents().get(0);<br />
if (topElement instanceof PatternModel) {<br />
for (Pattern _p : ((PatternModel) topElement).getPatterns()) {<br />
if (patternFQN.equals(CorePatternLanguageHelper.getFullyQualifiedName(_p))) {<br />
p = _p; break;<br />
}<br />
}<br />
}<br />
}<br />
}<br />
if (p == null) {<br />
throw new RuntimeException(String.format("Pattern %s not found", patternFQN));<br />
}<br />
// A specification builder is used to translate patterns to query specifications<br />
SpecificationBuilder builder = new SpecificationBuilder();<br />
<br />
// attempt to retrieve a registered query specification <br />
IncQueryMatcher<? extends IPatternMatch> matcher = engine.getMatcher(builder.getOrCreateSpecification(p));<br />
<br />
if (matcher!=null) {<br />
Collection<? extends IPatternMatch> matches = matcher.getAllMatches();<br />
prettyPrintMatches(results, matches);<br />
}<br />
<br />
// wipe the engine<br />
engine.wipe();<br />
// after a wipe, new patterns can be rebuilt with much less overhead than <br />
// complete traversal (as the base indexes will be kept)<br />
<br />
// completely dispose of the engine once's it is not needed<br />
engine.dispose();<br />
resource.unload();<br />
} catch (IncQueryException e) {<br />
e.printStackTrace();<br />
results.append(e.getMessage());<br />
}<br />
} else {<br />
results.append("Resource not found");<br />
}<br />
return results.toString();<br />
}<br />
</source><br />
<br />
<br />
<br />
=== API interfaces ===<br />
<br />
*IPatternMatch [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IPatternMatch.html Javadoc] <br />
**reflection: pattern(), patternName() <br />
**getters and setters <br />
**utility functions (toArray, prettyPrint) <br />
*IncQueryMatcher [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IncQueryMatcher.html Javadoc] <br />
**reflection <br />
**get all matches <br />
**get single/arbitrary match <br />
**check for a match <br />
**number of matches <br />
**process matches <br />
**access change processing features <br />
**create a new Match for input binding <br />
**access projected value sets<br />
<br />
== The Pattern Registry and Matcher Factories ==<br />
<br />
TODO The IMatcherFactory interface [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IMatcherFactory.html Javadoc] <br />
<br />
*reflection <br />
*initialize the matcher<br />
<br />
<br> <br />
<br />
= Advanced query result set change processing =<br />
<br />
== Match update callbacks ==<br />
<br />
<source lang="java"><br />
private void changeProcessing_lowlevel(final StringBuilder results, IncQueryMatcher<? extends IPatternMatch> matcher) {<br />
// (+) these update callbacks are called whenever there is an actual change in the<br />
// result set of the pattern you are interested in. Hence, they are called fewer times<br />
// than the "afterUpdates" option, giving better performance.<br />
// (-) the downside is that the callbacks are *not* guaranteed to be called in a consistent<br />
// state (i.e. when the update propagation is settled), hence<br />
// * you must not invoke pattern matching and model manipulation _inside_ the callback method<br />
// * the callbacks might encounter "hazards", i.e. when an appearance is followed immediately by a disappearance.<br />
engine.addMatchUpdateListener(matcher, new IMatchUpdateListener<IPatternMatch>() {<br />
@Override<br />
public void notifyDisappearance(IPatternMatch match) {<br />
// left empty<br />
}<br />
@Override<br />
public void notifyAppearance(IPatternMatch match) {<br />
results.append("\tNew match found by changeset low level callback: " + match.prettyPrint()+"\n");<br />
}<br />
}, false);<br />
}<br />
</source><br><br />
<br />
== Using the EVM ==<br />
<br />
The [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|Event-driven VM]] can also be used for this purpose.<br />
See the section called "Efficiently reacting to pattern match set changes".<br />
<br />
= Advanced IncQuery Lifecycle management =<br />
<br />
== Managed vs. unmanaged IncQueryEngines ==<br />
<br />
== Disposing ==<br />
<br />
If you want to remove the matchers from the engine you can call the wipe() method on it. It discards any pattern matcher caches and forgets the known patterns. The base index built directly on the underlying EMF model, however, is kept in memory to allow reuse when new pattern matchers are built. If you don’t want to use it anymore call the dispose() instead, to completely disconnect and dismantle the engine. <br />
<br />
*wipe <br />
*dispose<br />
<br />
= IncQuery Base =<br />
<br />
EMF-IncQuery provides a light-weight indexer library called Base that aims to provide several useful (some would even argue critical) features for querying EMF models: <br />
<br />
*inverse navigation along EReferences <br />
*finding and incrementally tracking all model elements by attribute value/type (i.e. inverse navigation along EAttributes) <br />
*incrementally computing transitive reachability along given reference types (i.e. transitive closure of an EMF model) <br />
*getting and tracking all the (direct) instances of a given EClass<br />
<br />
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 as it can be used in a stand-alone way, without the rest of EMF-IncQuery. <br />
<br />
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. <br />
<br />
The detailed documentation is covered in [[EMFIncQuery/UserDocumentation/API/BaseIndexer]]<br />
<br />
== Extracting reachability paths from transitive closure ==<br />
<br />
TODO<br />
<br />
= Logging in EMF-IncQuery =<br />
<br />
EMF-IncQuery logs error messages and some trace information using log4j. If you need to debug your application and would like to see these messages, you can set the log level in different hierarchy levels.<br />
Since we use standard log4j, you can configure logging both with configuration files or through API calls.<br />
<br />
* All loggers are children of a top-level default logger, that can be accessed from IncQueryLoggingUtil.getDefaultLogger(), just call setLevel(Level.DEBUG) on the returned logger to see all messages (of course you can use other levels as well).<br />
* Each engine has it's own logger that is shared with the Base Index and the matchers as well. If you want to see all messages related to all engines, call IncQueryLoggingUtil.getLogger(IncQueryEngine.class) and set the level.<br />
* Some other classes also use their own loggers and the same approach is used, they get the loggers based on their class, so retrieving that logger and setting the level will work as well.<br />
<br />
== Configuration problems ==<br />
<br />
log4j uses a properties file as a configuration for its root logger. However, since this configuration is usually supplied by developers of applications, we do not package it in EMF-IncQuery.<br />
This means you may encounter the following on your console if no configuration was supplied:<br />
<br />
log4j:WARN No appenders could be found for logger (org.eclipse.incquery.runtime.util.IncQueryLoggingUtil).<br />
log4j:WARN Please initialize the log4j system properly.<br />
<br />
There are several cases where this can occur:<br />
* '''You have Xtext SDK installed''', which has a plugin fragment called org.eclipse.xtext.logging that supplies a log4j configuration. Make sure that the fragment is selected in your Runtime Configuration.<br />
* '''You are using the tooling of EMF-IncQuery without the Xtext SDK''', you will see the above warning, but since the patternlanguage.emf plugins also inject appenders to the loggers of EMF-IncQuery, log messages will be correctly displayed.<br />
* '''You are using only the runtime part of EMF-IncQuery''' that has no Xtext dependency. You have to provide your own properties file (standalone execution) or fragment (OSGi execution), see http://www.eclipsezone.com/eclipse/forums/t99588.html<br />
* Alternatively, if you just want to make sure that log messages appear in the console no matter what other configuration happens, you can call <code>IncQueryLoggingUtil.setupConsoleAppenderForDefaultLogger()</code> which will do exactly what its name says. Since appenders and log levels are separate, you will still have to set the log level on the loggers you want to see messages from.<br />
* If you wish to completely turn the logger of, call <code>IncQueryLoggingUtil.getDefaultLogger().setLevel(Level.OFF);</code>.<br />
<br />
= Using Filtered Input Models During Pattern Matching =<br />
<br />
In several cases it is beneficial to not include all Resources from a ResourceSet during pattern matching, but consider more than one. Such cases might include Xtext/Xbase languages or JaMoPP[http://www.jamopp.org/index.php/JaMoPP]-based instances that include resources representing the classes of the Java library.<br />
<br />
EMF-IncQuery includes some options to filter out some subtrees from being indexed both by the Base Indexer and the Rete networks, by providing a filter implementation to the IncQuery Engine. These options include the IBaseIndexResourceFilter and IBaseIndexObjectFilter instances that can be used to filter out entire resources or containment subtrees, respectively.<br />
<br />
Sample usage (by filtering out Java classes referred by JaMoPP):<br />
<br />
<source lang="java"><br />
ResourceSet resourceSet = ...; //Use a Resource Set as the root of the engine <br />
BaseIndexOptions options = new BaseIndexOptions();<br />
options.setResourceFilterConfiguration(new IBaseIndexResourceFilter() {<br />
<br />
@Override<br />
public boolean isResourceFiltered(Resource resource) {<br />
// PathMap URI scheme is used to refer to JDK classes<br />
return "pathmap".equals(resource.getURI().scheme());<br />
}<br />
});<br />
//Initializing engine with custom options<br />
AdvancedIncQueryEngine engine = AdvancedIncQueryEngine.createUnmanagedEngine(resourceSet, options);<br />
</source><br />
<br />
'''Important!''' there are some issues to be considered while using this API:<br />
* If a Resource or containment subtree is filtered out, it is filtered out entirely. It is not possible to re-add some lower-level contents.<br />
* There is a known issue with result matches that are only partially in the filtered area. Be careful with queried edges that are connecting filtered and non-filtered elements. See {{bug|398907}} for details.<br />
<br />
= Using alternative search algorithms =<br />
<br />
Since version 0.9, there is a possibility to refer to alternative search engines in addition to Rete-based incremental engines; version 1.0 includes a local search based search algorithm usable with the EMF-IncQuery matcher API.<br />
<br />
The most important steps to perform:<br />
* Add a dependency to the optional plug-in ''org.eclipse.incquery.runtime.localsearch'' <br />
* Execute the following call '''before''' initializing the EMF-IncQuery engine (it is safe to execute it multiple times; but will not work after initializing the engine):<br />
<source lang="java"><br />
QueryBackendRegistry.getInstance().<br />
registerQueryBackendFactory(LocalSearchBackend.class, new LocalSearchBackendFactory());</source><br />
* Explicitly ask for a local search based matcher when initializing the matcher instance:<br />
<source lang="java"><br />
IQuerySpecification<?> specification = ...;<br />
QueryEvaluationHint hint = new QueryEvaluationHint(LocalSearchBackend.class, new HashMap<String, Object>());<br />
AdvancedIncQueryEngine.from(engine).getMatcher(specification, hint);<br />
</source><br />
* After initialization, the existing pattern matcher API constructs can be used over the local search engine.<br />
<br />
== Known limitations ==<br />
* A local search matcher cannot provide change notifications on pattern matches. If asked, an UnsupportedOperationException is thrown.<br />
* For now, it is not possible to combine different pattern matching algorithms. Either the entire search must use Rete or Local search based algorithms.<br />
* Currently, local search always creates new plans from scratch, saving and reusing plans is not implemented yet.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Releases/Query/NewAndNoteWorthy1.0&diff=379255VIATRA/Releases/Query/NewAndNoteWorthy1.02015-03-04T08:31:21Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= New and Noteworthy - EMF-IncQuery 1.0.0 = <br />
<br />
== Enhanced support for UML models ==<br />
* Surrogate queries<br />
== Updated Validation Framework ==<br />
<br />
== Updated Viewers Framework ==</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Releases/Query/NewAndNoteWorthy1.0&diff=379254VIATRA/Releases/Query/NewAndNoteWorthy1.02015-03-04T08:31:07Z<p>Ujhelyiz.mit.bme.hu: Created page with "= New and Noteworthy - EMF-IncQuery 1.0.0 = == Enhanced support for UML models == * Surrogate queries == Updated Validation Framework == == Updated Viewers Framework =="</p>
<hr />
<div>= New and Noteworthy - EMF-IncQuery 1.0.0 = <br />
<br />
== Enhanced support for UML models ==<br />
* Surrogate queries<br />
== Updated Validation Framework ==<br />
<br />
== Updated Viewers Framework ==</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query&diff=379253VIATRA/Query2015-03-04T08:28:25Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= EMF-IncQuery Wiki Documentation =<br />
<br />
For the query language, we reuse the concepts of graph patterns (which is a key concept in many graph transformation tools) as a concise and easy way to specify complex structural model queries. High runtime performance is achieved by adapting incremental graph pattern matching techniques based on the Rete algorithm.<br />
<br />
We believe the average programmer using EMF models will like EMF-IncQuery for the following reasons:<br />
<br />
* declarative queries can be evaluated over EMF without manually traversing the models,<br />
* complex interrelated constellations of EMF objects can be easily formulated as a graph pattern,<br />
** the language is expressive and provides powerful features such as negation or counting,<br />
** graph patterns are composable and reusable,<br />
** queries can be evaluated with great freedom, i.e. input and output parameters can be selected at run-time,<br />
** some frequently encountered shortcomings of EMF’s interfaces are addressed:<br />
** easy and efficient enumeration of all instances of a class regardless of location,<br />
** simple backwards navigation along all kinds of references (even without eOpposite)<br />
** finding objects based on attribute value,<br />
* the incremental query evaluation mechanism offers a significant performance boost when frequently querying complex structural patterns with a moderate amount of modifications in-between (e.g. during continuous validation),<br />
* from the declarative representation of queries, pattern matcher code is generated which can be distributed as Eclipse plug-ins with very few dependencies.<br />
<br />
<br />
== EMF-IncQuery User Documentation ==<br />
* Developing Incremental Model Queries using the EMF-IncQuery Tooling<br />
** [[EMFIncQuery/UserDocumentation/Installation|Installing EMF-IncQuery]]<br />
** [[EMFIncQuery/UserDocumentation/QueryLanguage|A Short Introduction to the Query Language]]<br />
** [[ EMFIncQuery/UserDocumentation/QueryDevelopment|Getting started with Query Development]]<br />
** [[EMFIncQuery/UserDocumentation/RETE_Visualizer|RETE Visualizer]]<br />
** [[EMFIncQuery/UserDocumentation/DebuggerTooling|EMF-IncQuery Debugger Tooling]] (since 0.8.0)<br />
* Using the EMF-IncQuery Runtime library<br />
** [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless (standalone) execution of EMF-IncQuery queries and unit tests]]<br />
** [[EMFIncQuery/UserDocumentation/API|API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]]<br />
** [[EMFIncQuery/UserDocumentation/API/RunOnce|Run once querying API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/BaseIndexer|IncQuery Base Indexer]]<br />
** [[EMFIncQuery/UserDocumentation/AdvancedPatterns|Advanced pattern language constructs]] <br />
* Integration Components<br />
** [[EMFIncQuery/UserDocumentation/Databinding|Databinding]]<br />
** [[EMFIncQuery/UserDocumentation/Validation|Validation Framework]]<br />
** [[EMFIncQuery/UserDocumentation/Query_Based_Features|Defining Query-based Features]]<br />
** [[EMFIncQuery/UserDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
* [[EMFIncQuery/UserDocumentation/Examples|Examples]]<br />
* [[EMFIncQuery/UserDocumentation/Build|EMF-IncQuery in CI Environments (Maven artifacts)]] (since 0.8.0)<br />
* Reporting bugs or requesting new features<br />
** [[EMFIncQuery/UserDocumentation/IssueTracking|Issue tracking]]<br />
<br />
== Contributor's Guide ==<br />
<br />
* Developer's Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/DevEnvironment|Setting up the Development Environment]]<br />
** [[EMFIncQuery/DeveloperDocumentation/BuildConfig|The EMF-IncQuery Build Configuration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IssueTracking|Issue Reporting and Management]]<br />
* Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/Model_connectors|Model Connectors]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
** [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|Event-driven Virtual Machine]]<br />
** [[EMFIncQuery/DeveloperDocumentation/Builder|Builder Architecture]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQueryXcore|Notes on IncQuery & Xcore integration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/QueryProcessing|Query Processing]]<br />
* Developer Meeting Minutes<br />
** [[EMFIncQuery/DeveloperMeetingMinutes|Meeting minutes]]<br />
<br />
== Releases ==<br />
* Version 0.7.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.7.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/MigrateTo0.7|Migration guide]]<br />
** Known issues affecting version 0.7.1 [[EMFIncQuery/Releases/KnownIssuesFor0.7.1|fixed in 0.7.2]]<br />
* Version 0.8.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.8.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.8|New and Noteworthy]]<br />
** [[EMFIncQuery/Releases/MigrateTo0.8|Migration guide]]<br />
** Known issues affecting version 0.8.1 [[EMFIncQuery/Releases/KnownIssuesFor0.8.1|fixed in 0.8.2]]<br />
* Version 0.9.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.9.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.9|New and Noteworthy]]<br />
[[Category:EmfIncQuery]]<br />
* Version 1.0.0<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy1.0|New and Noteworthy]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Transformation/Transformation_API&diff=378626VIATRA/Transformation/Transformation API2015-02-18T19:56:11Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= VIATRA Transformation API =<br />
<br />
* Based on [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|EVM]]<br />
* Relies on Xtend features such as extension methods and closures to be <br />
* [[VIATRA/Transformation_Language|Language concepts]] (for requirements overview)<br />
* Documentation for API in {{Git|viatra|org.eclipse.viatra.git}}<br />
* CI update site: <nowiki>https://hudson.eclipse.org/viatra/job/viatra-master/lastSuccessfulBuild/artifact/releng/org.eclipse.viatra.update/target/repository/</nowiki><br />
<br />
== Batch Transformation API ==<br />
<br />
Three extension classes used for transformations:<br />
* BatchTransformation - hides IncQueryEngine and RuleEngine; manages group initialization of rules - instead of an extension method, this can also be used as a base class<br />
* TransformationStatements - control structure<br />
* ModelManipulation - generic model manipulation primitives; hides details of EditingDomains (if necessary); implementation not batch transformation specific<br />
<br />
=== Batch Transformation Rules ===<br />
<br />
* Special rule type<br />
** Precondition + action<br />
** Life cycle:<br />
*** Stateless<br />
**** rule does not maintain state whether an activation has fired or not<br />
**** Lifecycle: firing: active -> active<br />
*** Stateful<br />
**** rule maintains whether an an activation has fired or not<br />
**** Lifecycle: firing: active -> fired<br />
=== (Batch) Transformation Statements ===<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! fireOne<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires a single activation<br />
|-<br />
! fireAllCurrent<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires all current activations. If the firings change the set of activations, it won't change the set of fired activations.<br />
|-<br />
! fireWhilePossible<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires the activations one by one. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|-<br />
! fireUntil<br />
| Batch Transformation Rule, break condition, (opt: filter)<br />
| After firing the first activation, it checks whether the break condition became true; if yes, exits, if not, it restarts. It does not store the initial set of activations. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|}<br />
<br />
== Incremental Transformation API ==<br />
<br />
The incremental API aims at defining and executing model transformations in an event-driven manner. In this case, the preconditions of the single transformations are checked on every related model change in an incremental fashion (using EMF-IncQuery) and the actions are fired once the preconditions are fulfilled. Model changes are captured as events, hence the naming of the basic concepts below.<br />
<br />
* ''EventDrivenTransformation'' - Similarly to the ''BatchTransformation'', it hides the IncQueryEngine and RuleEngine and serves as the basic concept for this part of the API.<br />
* ''EventContext'' - We distinguish two types or contexts of events: point and interval. The former one is described with a single point of appearance on the timeline; the latter one is characterized by its appearance ''and'' disappearance on the timeline. It's up to the user to select whether a transformation is associated with an event of point or interval context. In the background, the event context is translated into an EVM activation life cycle, which can be overridden by the user if required. This concept slightly resembles the concept of batch transformation rules of ''stateless'' and ''stateful'' life cycle.<br />
<br />
=== The event-driven transformation rule (EventDrivenTransformationRule) ===<br />
In contrast with the batch mode, in incremental mode, there are no arbitrarily assembled local conflict sets; instead: every transformation rule is handled in a global conflict set. ''EventDrivenTransformationRuleFactory'' is a factory designed for instantiating the rules.<br />
<br />
=== The essential ideology behind the API structure ===<br />
When designing the API, we reused the concepts of the ''fluent interface'' and the ''builder pattern''. It heavily utilizes the capabilities of Xtend, resulting in a concise way for defining rules, transformations and transformation groups, as presented below.<br />
<br />
=== Example: model transformations for automaton simulation ===<br />
'''Defining the event-driven transformation rule'''<br />
<br />
This is the precondition for your transformation.<br />
<source lang="java"><br />
val createEnabledTransitionRule = ruleFactory.createRule(EnabledTransitionMatcher::querySpecification) [<br />
eventModelManager.strategy.fireTransition(t, et)<br />
]<br />
</source><br />
The above snippet assumes the ''EnabledTransition'' EMF-IncQuery pattern to be defined, which the ''EnabledTransitionMatcher'' has been generated from. The expression in the closure is the action and is totally up to you to define. (In this case, the manager class maintaining the model will fire a transition.) <br />
You can also provide a name for the rule as well as override the default event context (point).<br />
<br />
'''Optionally grouping the rules into rule groups'''<br />
<br />
This one is pretty straightforward; just enumerate your rules in a closure:<br />
<source lang="java"><br />
def getRules() {<br />
new EventDrivenTransformationRuleGroup(<br />
createEnabledTransitionRule,<br />
createFinishedStateMachineRule,<br />
createTokenInTrapStateRule<br />
)<br />
}<br />
</source><br />
Remember, there is only one global conflict set for these rules to get conflicted. It does not really matter whether you group your rules or not, although it can make the further parts of code more concise.<br />
<br />
'''Register the transformation rules'''<br />
<br />
Once you have your transformation rules, there are just a few steps to take in order to register the rules into the execution schema. Let's look at this snippet:<br />
<source lang="java"><br />
def registerRules() {<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).create()<br />
}<br />
</source><br />
The benefits of the fluent API approach are obvious here. Notice the mandatory ''create()'' method at the tail of the method chain as the essence of the builder pattern. This method chain will deal with the following:<br />
# it instantiates an EventDrivenTransformation;<br />
# the resource or resource set the transformations are executed upon is passed to the transformation (''forSource()'');<br />
# the transformation rules are registered (''addRules()'');<br />
# in the background, the default conflict resolver (arbitrary CR) is selected to deal with global conflicts.<br />
<br />
If you opt to use a custom conflict resolver, here's how you do it:<br />
<source lang="java"><br />
def registerRulesWithCustomPriorities() {<br />
val fixedPriorityResolver = ConflictResolvers.createFixedPriorityResolver();<br />
fixedPriorityResolver.setPriority(createEnabledTransitionRule.ruleSpecification, 100)<br />
fixedPriorityResolver.setPriority(createFinishedStateMachineRule.ruleSpecification, 50)<br />
fixedPriorityResolver.setPriority(createTokenInTrapStateRule.ruleSpecification, 0)<br />
<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(fixedPriorityResolver).create()<br />
}<br />
</source><br />
<br />
However, as a useful feature, the API is capable to construct a fixed priority resolver based on the ''order of the rules'' handed over to the EventDrivenTransformation. So the results of the above code could be just achieved with this one:<br />
<source lang="java"><br />
def registerRulesWithAutomatedPriorities() {<br />
EventDrivenTransformation.forSource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(GlobalConflictResolver.FIXED_PRIORITY_CONFLICT_RESOLVER).create()<br />
}<br />
</source><br />
<br />
== Model Manipulation Primitives ==<br />
<br />
Model manipulation primitives are implemented by instances of IModelManipulations interface. Currently, two implementations are available:<br />
<br />
# SimpleModelManipulations - uses plain EMF API<br />
# ModelManipulationsWithEditingDomain - uses EMF Edit commands on EditingDomain instances<br />
<br />
If some transformation needs specific primitives (e.g. transaction support), new instances can introduce extra methods as required.<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! create<br />
| Resource; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the root of the selected resource<br />
|-<br />
! createChild <br />
| EObject (container); EReference; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the selected reference; the reference must be of containment type<br />
|-<br />
! addTo<br />
| EObject (container); EStructuralFeature; Object<br />
| Adds an existing object to the corresponding container with a reference; if using a reference it must *not* be of containment type<br />
|-<br />
! remove<br />
| EObject<br />
| Removes the EObject from the model<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature; Object<br />
| Removes an object from the selected container; when using a containment EReference, also removes it from the resource set<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature<br />
| Removes all objects from a multivalued feature; when using a containment EReference, also removes them from the resource set<br />
|-<br />
! set<br />
| EObject (container); EStructuralFeature; Object<br />
| Sets the value of a single-valued feature<br />
|-<br />
! move<br />
| EObject(s), EObject (new container), EStructuralFeature<br />
| Moves elements to a new container, and removes them from an old one. 'Remark': The implementation here is specific, as it relies on features of the index.<br />
|}<br />
<br />
== Examples ==<br />
<br />
=== Program understanding (Java code to state charts) ===<br />
<br />
The most up-to-date example can be found here: https://github.com/ujhelyiz/viatra2-programunderstanding<br />
<br />
=== Petri nets to State charts ===<br />
A (not very well tested) example transformation is available by implementing the Petri net to State Charts case of the Transformation Tool Contest 2013.<br />
<br />
* Case description: http://planet-sl.org/community/index.php?option=com_community&view=groups&task=viewgroup&groupid=26&Itemid=387&lang=en<br />
* Implementation: https://github.com/izsob/TTC13-PN2SC-EIQ (look for the branch ''viatra-api'')<br />
** The following snippets are taken from this repository<br />
<br />
==== Setting up a transformation ====<br />
<br />
<source lang="java"><br />
class Pn2ScJobs {<br />
<br />
/* Transformation-related extension API */<br />
extension BatchTransformationRuleFactory ruleFactory = new BatchTransformationRuleFactory<br />
extension BatchTransformation transformation<br />
extension BatchTransformationStatements statements<br />
extension IModelManipulations manipulation<br />
<br />
/* Makes available the Literals of the EPackage for the manipulation API */<br />
extension StatechartsPackage chartPackage = StatechartsPackage.eINSTANCE<br />
<br />
Statechart stateChart<br />
Resource resource<br />
<br />
new(Resource resource) {<br />
/Storing transformation-specific input elements<br />
this.resource = resource<br />
this.stateChart = resource.contents.head as Statechart<br />
<br />
/* Extensions are initialized as normal fields in Xtend */<br />
transformation = new BatchTransformation(resource.resourceSet)<br />
statements = new BatchTransformationStatements(transformation)<br />
manipulation = new SimpleModelManipulations(transformation.iqEngine)<br />
}<br />
<br />
...<br />
<br />
}<br />
</source><br />
<br />
==== Defining rules, rulegroups ====<br />
<br />
Rules can be created using the factory methods of the BatchTransformation class; its actions can be described by an Xtend closure.<br />
<br />
If required, it is possible to extend BatchTransformationRule manually - both implementations are interchangeable.<br />
<br />
<source lang="java"><br />
/**<br />
* Map a PetriNet place to a base state in the StateChart with an "or" container.<br />
*/<br />
val createMapPlaceRuleSpecification = createRule(PlaceMatcher::querySpecification) [<br />
// create base b with b.name=p.name; and the state or, where or.contains={b}<br />
var or = stateChartResource.create(OR) as OR<br />
var basic = or.createChild(compound_Contains, basic) as Basic<br />
basic.set(state_Name, p.name)///name = p.name<br />
// create trace from place to or<br />
createTrace(p, or)<br />
]<br />
<br />
/**<br />
* Map a PetriNet transition to a hyperedge state in the StateChart without an "or" container.<br />
*/<br />
val createMapTransitionRuleSpecification = createRule(TransitionMatcher::querySpecification) [<br />
// create hyperEdge h with h.name=t.name (without an or container)<br />
var hyperEdge = stateChartResource.create(hyperEdge) as HyperEdge<br />
hyperEdge.name = t.name<br />
// create trace from transition to hyperEdge<br />
createTrace(t, hyperEdge)<br />
]<br />
<br />
/**<br />
* Create "next" edges in the StateChart between elements connected in the PetriNet.<br />
*/<br />
val createNextStateRuleSpecification = createRule(NextStateMatcher::querySpecification) [<br />
state1.addTo(state_Next, state2)<br />
]<br />
<br />
/**<br />
* Get rules for performing initial mapping<br />
*/<br />
def getInitialisationRules() {<br />
new TransformationRuleGroup(<br />
createMapPlaceRuleSpecification,<br />
createMapTransitionRuleSpecification,<br />
createNextStateRuleSpecification<br />
)<br />
}<br />
</source><br />
<br />
==== Executing rules, rule groups ====<br />
The primitives ask for a rule and filter<br />
<br />
* A filter is expressed by a collection of name-value pairs (available names come from the precondition pattern)<br />
* Parameter names not mentioned are unconstrained<br />
<br />
<source lang="java"><br />
val moveChildrenRule = createRule(EquivContainsMatcher::querySpecification) [<br />
state.moveTo(newP, compound_Contains)<br />
]<br />
// add children elements to OR of the StateChart<br />
moveChildrenRule.forall("namedElement" -> q)<br />
</source><br />
<br />
The following snippet shows that primitives also work with rule groups with the exact same syntax. The idea here is that the engine decides which rule of the group to execute (based on the ConflictResolver).<br />
<br />
<source lang="java"><br />
def transformPn2Sc() {<br />
// place->OR mapping<br />
initialisationRules.fireWhilePossible<br />
// execute AND and OR rules<br />
andOrRules.fireWhilePossible<br />
// clean orphaned root ORs; and create StateChart root<br />
finalisationRules.fireWhilePossible<br />
}<br />
</source><br />
<br />
<br />
<br />
== Further ideas to evaluate ==<br />
<br />
* "Strict" API vs "relaxed" API<br />
** Everything presented here is a strict API<br />
*** Useful for research goals (e.g. analysis)<br />
*** Might be too strict for Java/EMF programmers<br />
** It might make sense to support transformation with bring-your-own-code style<br />
*** Currently almost all elements are optional in API: statements and model manipulations commands need not to be used -> simple Java/Xtend replacements possible<br />
*** Some simple wrappers might be needed to create RecordingCommands, etc.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA&diff=377990VIATRA2015-02-09T14:35:49Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== Modules ==<br />
*[[VIATRA/Transformation_API|Transformation API]]<br />
*[[VIATRA/DSE|DSE]]<br />
*[[VIATRA/CEP|CEP]]<br />
<br />
== Related content ==<br />
*[[VIATRA/Branding|Branding]]<br />
<br />
== Important links ==<br />
*Mailing list: [mailto:viatra-dev@eclipse.org viatra-dev@eclipse.org].<br />
*[https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Viatra Bugzilla]<br />
**Found a bug? Submit it [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Viatra here]!<br />
<br />
== Archive ==<br />
<br />
The documentation of the old, VPM-based project is available from [[VIATRA2]].</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Transformation/Transformation_API&diff=377989VIATRA/Transformation/Transformation API2015-02-09T14:32:56Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= VIATRA Transformation API =<br />
<br />
* Based on [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|EVM]]<br />
* Relies on Xtend features such as extension methods and closures to be <br />
* [[VIATRA/Transformation_Language|Language concepts]] (for requirements overview)<br />
* Documentation for API in {{Git|viatra2|org.eclipse.viatra2.emf.git}}<br />
* CI update site: <nowiki>https://hudson.eclipse.org/viatra/job/viatra-master/lastSuccessfulBuild/artifact/releng/org.eclipse.viatra.update/target/repository/</nowiki><br />
<br />
== Batch Transformation API ==<br />
<br />
Three extension classes used for transformations:<br />
* BatchTransformation - hides IncQueryEngine and RuleEngine; manages group initialization of rules - instead of an extension method, this can also be used as a base class<br />
* TransformationStatements - control structure<br />
* ModelManipulation - generic model manipulation primitives; hides details of EditingDomains (if necessary); implementation not batch transformation specific<br />
<br />
=== Batch Transformation Rules ===<br />
<br />
* Special rule type<br />
** Precondition + action<br />
** Life cycle:<br />
*** Stateless<br />
**** rule does not maintain state whether an activation has fired or not<br />
**** Lifecycle: firing: active -> active<br />
*** Stateful<br />
**** rule maintains whether an an activation has fired or not<br />
**** Lifecycle: firing: active -> fired<br />
=== (Batch) Transformation Statements ===<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! fireOne<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires a single activation<br />
|-<br />
! fireAllCurrent<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires all current activations. If the firings change the set of activations, it won't change the set of fired activations.<br />
|-<br />
! fireWhilePossible<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires the activations one by one. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|-<br />
! fireUntil<br />
| Batch Transformation Rule, break condition, (opt: filter)<br />
| After firing the first activation, it checks whether the break condition became true; if yes, exits, if not, it restarts. It does not store the initial set of activations. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|}<br />
<br />
== Incremental Transformation API ==<br />
<br />
The incremental API aims at defining and executing model transformations in an event-driven manner. In this case, the preconditions of the single transformations are checked on every related model change in an incremental fashion (using EMF-IncQuery) and the actions are fired once the preconditions are fulfilled. Model changes are captured as events, hence the naming of the basic concepts below.<br />
<br />
* ''EventDrivenTransformation'' - Similarly to the ''BatchTransformation'', it hides the IncQueryEngine and RuleEngine and serves as the basic concept for this part of the API.<br />
* ''EventContext'' - We distinguish two types or contexts of events: point and interval. The former one is described with a single point of appearance on the timeline; the latter one is characterized by its appearance ''and'' disappearance on the timeline. It's up to the user to select whether a transformation is associated with an event of point or interval context. In the background, the event context is translated into an EVM activation life cycle, which can be overridden by the user if required. This concept slightly resembles the concept of batch transformation rules of ''stateless'' and ''stateful'' life cycle.<br />
<br />
=== The event-driven transformation rule (EventDrivenTransformationRule) ===<br />
In contrast with the batch mode, in incremental mode, there are no arbitrarily assembled local conflict sets; instead: every transformation rule is handled in a global conflict set. ''EventDrivenTransformationRuleFactory'' is a factory designed for instantiating the rules.<br />
<br />
=== The essential ideology behind the API structure ===<br />
When designing the API, we reused the concepts of the ''fluent interface'' and the ''builder pattern''. It heavily utilizes the capabilities of Xtend, resulting in a concise way for defining rules, transformations and transformation groups, as presented below.<br />
<br />
=== Example: model transformations for automaton simulation ===<br />
'''Defining the event-driven transformation rule'''<br />
<br />
This is the precondition for your transformation.<br />
<source lang="java"><br />
val createEnabledTransitionRule = ruleFactory.createRule(EnabledTransitionMatcher::querySpecification) [<br />
eventModelManager.strategy.fireTransition(t, et)<br />
]<br />
</source><br />
The above snippet assumes the ''EnabledTransition'' EMF-IncQuery pattern to be defined, which the ''EnabledTransitionMatcher'' has been generated from. The expression in the closure is the action and is totally up to you to define. (In this case, the manager class maintaining the model will fire a transition.) <br />
You can also provide a name for the rule as well as override the default event context (point).<br />
<br />
'''Optionally grouping the rules into rule groups'''<br />
<br />
This one is pretty straightforward; just enumerate your rules in a closure:<br />
<source lang="java"><br />
def getRules() {<br />
new EventDrivenTransformationRuleGroup(<br />
createEnabledTransitionRule,<br />
createFinishedStateMachineRule,<br />
createTokenInTrapStateRule<br />
)<br />
}<br />
</source><br />
Remember, there is only one global conflict set for these rules to get conflicted. It does not really matter whether you group your rules or not, although it can make the further parts of code more concise.<br />
<br />
'''Register the transformation rules'''<br />
<br />
Once you have your transformation rules, there are just a few steps to take in order to register the rules into the execution schema. Let's look at this snippet:<br />
<source lang="java"><br />
def registerRules() {<br />
EventDrivenTransformation.forResource(eventModelManager.resourceSet).addRules(rules).create()<br />
}<br />
</source><br />
The benefits of the fluent API approach are obvious here. Notice the mandatory ''create()'' method at the tail of the method chain as the essence of the builder pattern. This method chain will deal with the following:<br />
# it instantiates an EventDrivenTransformation;<br />
# the resource the transformations are executed upon is passed to the transformation (''forResource()'');<br />
# the transformation rules are registered (''addRules()'');<br />
# in the background, the default conflict resolver (arbitrary CR) is selected to deal with global conflicts.<br />
<br />
If you opt to use a custom conflict resolver, here's how you do it:<br />
<source lang="java"><br />
def registerRulesWithCustomPriorities() {<br />
val fixedPriorityResolver = ConflictResolvers.createFixedPriorityResolver();<br />
fixedPriorityResolver.setPriority(createEnabledTransitionRule.ruleSpecification, 100)<br />
fixedPriorityResolver.setPriority(createFinishedStateMachineRule.ruleSpecification, 50)<br />
fixedPriorityResolver.setPriority(createTokenInTrapStateRule.ruleSpecification, 0)<br />
<br />
EventDrivenTransformation.forResource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(fixedPriorityResolver).create()<br />
}<br />
</source><br />
<br />
However, as a useful feature, the API is capable to construct a fixed priority resolver based on the ''order of the rules'' handed over to the EventDrivenTransformation. So the results of the above code could be just achieved with this one:<br />
<source lang="java"><br />
def registerRulesWithAutomatedPriorities() {<br />
EventDrivenTransformation.forResource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(GlobalConflictResolver.FIXED_PRIORITY_CONFLICT_RESOLVER).create()<br />
}<br />
</source><br />
<br />
== Model Manipulation Primitives ==<br />
<br />
Model manipulation primitives are implemented by instances of IModelManipulations interface. Currently, two implementations are available:<br />
<br />
# SimpleModelManipulations - uses plain EMF API<br />
# ModelManipulationsWithEditingDomain - uses EMF Edit commands on EditingDomain instances<br />
<br />
If some transformation needs specific primitives (e.g. transaction support), new instances can introduce extra methods as required.<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! create<br />
| Resource; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the root of the selected resource<br />
|-<br />
! createChild <br />
| EObject (container); EReference; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the selected reference; the reference must be of containment type<br />
|-<br />
! addTo<br />
| EObject (container); EStructuralFeature; Object<br />
| Adds an existing object to the corresponding container with a reference; if using a reference it must *not* be of containment type<br />
|-<br />
! remove<br />
| EObject<br />
| Removes the EObject from the model<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature; Object<br />
| Removes an object from the selected container; when using a containment EReference, also removes it from the resource set<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature<br />
| Removes all objects from a multivalued feature; when using a containment EReference, also removes them from the resource set<br />
|-<br />
! set<br />
| EObject (container); EStructuralFeature; Object<br />
| Sets the value of a single-valued feature<br />
|-<br />
! move<br />
| EObject(s), EObject (new container), EStructuralFeature<br />
| Moves elements to a new container, and removes them from an old one. 'Remark': The implementation here is specific, as it relies on features of the index.<br />
|}<br />
<br />
== Examples ==<br />
<br />
=== Program understanding (Java code to state charts) ===<br />
<br />
The most up-to-date example can be found here: https://github.com/ujhelyiz/viatra2-programunderstanding<br />
<br />
=== Petri nets to State charts ===<br />
A (not very well tested) example transformation is available by implementing the Petri net to State Charts case of the Transformation Tool Contest 2013.<br />
<br />
* Case description: http://planet-sl.org/community/index.php?option=com_community&view=groups&task=viewgroup&groupid=26&Itemid=387&lang=en<br />
* Implementation: https://github.com/izsob/TTC13-PN2SC-EIQ (look for the branch ''viatra-api'')<br />
** The following snippets are taken from this repository<br />
<br />
==== Setting up a transformation ====<br />
<br />
<source lang="java"><br />
class Pn2ScJobs {<br />
<br />
/* Transformation-related extension API */<br />
extension BatchTransformationRuleFactory ruleFactory = new BatchTransformationRuleFactory<br />
extension BatchTransformation transformation<br />
extension TransformationStatements statements<br />
extension IModelManipulations manipulation<br />
<br />
/* Makes available the Literals of the EPackage for the manipulation API */<br />
extension StatechartsPackage chartPackage = StatechartsPackage.eINSTANCE<br />
<br />
Statechart stateChart<br />
Resource resource<br />
<br />
new(Resource resource) {<br />
/Storing transformation-specific input elements<br />
this.resource = resource<br />
this.stateChart = resource.contents.head as Statechart<br />
<br />
/* Extensions are initialized as normal fields in Xtend */<br />
transformation = new BatchTransformation(resource.resourceSet)<br />
statements = new TransformationStatements(transformation)<br />
manipulation = new SimpleModelManipulations(transformation.iqEngine)<br />
}<br />
<br />
...<br />
<br />
}<br />
</source><br />
<br />
==== Defining rules, rulegroups ====<br />
<br />
Rules can be created using the factory methods of the BatchTransformation class; its actions can be described by an Xtend closure.<br />
<br />
If required, it is possible to extend BatchTransformationRule manually - both implementations are interchangeable.<br />
<br />
<source lang="java"><br />
/**<br />
* Map a PetriNet place to a base state in the StateChart with an "or" container.<br />
*/<br />
val createMapPlaceRuleSpecification = createRule(PlaceMatcher::querySpecification) [<br />
// create base b with b.name=p.name; and the state or, where or.contains={b}<br />
var or = stateChartResource.create(OR) as OR<br />
var basic = or.createChild(compound_Contains, basic) as Basic<br />
basic.set(state_Name, p.name)///name = p.name<br />
// create trace from place to or<br />
createTrace(p, or)<br />
]<br />
<br />
/**<br />
* Map a PetriNet transition to a hyperedge state in the StateChart without an "or" container.<br />
*/<br />
val createMapTransitionRuleSpecification = createRule(TransitionMatcher::querySpecification) [<br />
// create hyperEdge h with h.name=t.name (without an or container)<br />
var hyperEdge = stateChartResource.create(hyperEdge) as HyperEdge<br />
hyperEdge.name = t.name<br />
// create trace from transition to hyperEdge<br />
createTrace(t, hyperEdge)<br />
]<br />
<br />
/**<br />
* Create "next" edges in the StateChart between elements connected in the PetriNet.<br />
*/<br />
val createNextStateRuleSpecification = createRule(NextStateMatcher::querySpecification) [<br />
state1.addTo(state_Next, state2)<br />
]<br />
<br />
/**<br />
* Get rules for performing initial mapping<br />
*/<br />
def getInitialisationRules() {<br />
new TransformationRuleGroup(<br />
createMapPlaceRuleSpecification,<br />
createMapTransitionRuleSpecification,<br />
createNextStateRuleSpecification<br />
)<br />
}<br />
</source><br />
<br />
==== Executing rules, rule groups ====<br />
The primitives ask for a rule and filter<br />
<br />
* A filter is expressed by a collection of name-value pairs (available names come from the precondition pattern)<br />
* Parameter names not mentioned are unconstrained<br />
<br />
<source lang="java"><br />
val moveChildrenRule = createRule(EquivContainsMatcher::querySpecification) [<br />
state.moveTo(newP, compound_Contains)<br />
]<br />
// add children elements to OR of the StateChart<br />
moveChildrenRule.forall("namedElement" -> q)<br />
</source><br />
<br />
The following snippet shows that primitives also work with rule groups with the exact same syntax. The idea here is that the engine decides which rule of the group to execute (based on the ConflictResolver).<br />
<br />
<source lang="java"><br />
def transformPn2Sc() {<br />
// place->OR mapping<br />
initialisationRules.fireWhilePossible<br />
// execute AND and OR rules<br />
andOrRules.fireWhilePossible<br />
// clean orphaned root ORs; and create StateChart root<br />
finalisationRules.fireWhilePossible<br />
}<br />
</source><br />
<br />
<br />
<br />
== Further ideas to evaluate ==<br />
<br />
* "Strict" API vs "relaxed" API<br />
** Everything presented here is a strict API<br />
*** Useful for research goals (e.g. analysis)<br />
*** Might be too strict for Java/EMF programmers<br />
** It might make sense to support transformation with bring-your-own-code style<br />
*** Currently almost all elements are optional in API: statements and model manipulations commands need not to be used -> simple Java/Xtend replacements possible<br />
*** Some simple wrappers might be needed to create RecordingCommands, etc.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA&diff=377988VIATRA2015-02-09T14:30:15Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== Modules ==<br />
*[[VIATRA/Transformation_API|Transformation API]]<br />
*[[VIATRA/DSE|DSE]]<br />
*[[VIATRA/CEP|CEP]]<br />
<br />
== Related content ==<br />
*[[VIATRA/Branding|Branding]]<br />
<br />
== Important links ==<br />
*Mailing list: [mailto:viatra-dev@eclipse.org viatra-dev@eclipse.org].<br />
*[https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Viatra Bugzilla]<br />
**Found a bug? Submit it [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Viatra here]!</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Transformation/Transformation_Language&diff=377985VIATRA/Transformation/Transformation Language2015-02-09T14:29:33Z<p>Ujhelyiz.mit.bme.hu: Ujhelyiz.mit.bme.hu moved page VIATRA2/EMF/Transformation Language to VIATRA/Transformation Language</p>
<hr />
<div>== Transformation language over EMF Models ==<br />
<br />
Design draft page <br />
<br />
This page describes a new language for describing models transformation, that builds on the experiences with the original [[VIATRA2/Transformation Language|VIATRA2 Transformation Control Language (VTCL)]] and its spinoff, the pattern-based query language of [[EMFIncQuery|EMF-IncQuery]]. It builds on the same concepts as the VTCL language, and directly re-uses the IncQuery pattern language for pattern definitions. <br />
<br />
== History ==<br />
<br />
Main VTCL language elements <br />
<br />
*'''pattern''': for defining constraints and conditions; multiple possibly pattern matchers available<br> <br />
*'''gtrule''': graph transformation rule describe elementary model manipulation steps, either as two graph patterns or a graph pattern and some imperative control (usually add/remove/update operations!)<br> <br />
*'''asmrule''': imperative control structures<br> <br />
**'''asm function''': globally available maps keyed by tuples<br><br />
<br />
New ideas not entirely supported by the existing language <br />
<br />
*Alternative traversal methods, e.g. probabilistic simulation or design space exploration <br />
**Worked around by extending/replacing the interpreter <br />
*Native EMF support <br />
**Importer/exporter was used <br />
*High-level support for event-driven transformations <br />
**Preliminary support was introduced via triggers<br />
<br />
== Design ideas ==<br />
<br />
=== Graph pattern matching ===<br />
<br />
*Graph pattern syntax and semantics re-used from EMF-IncQuery<br />
<br />
==== Batch transformations ====<br />
<br />
*''boolean operation'' -&gt; check whether at least one match exists <br />
*Select ''one match'' for processing <br />
**Unboxing to single variables needed -&gt; look for compatibility with EMFIncQuery Match processors <br />
**Which one to return: unspecified or random or first/last/nth via some ordering <br />
*Select ''all matches'' for processing <br />
**Unboxing similarly needed <br />
**Ordering and concurrent modification? <br />
**<br><br />
<br />
==== Event-driven mode ====<br />
<br />
*Defining what to do when a match <br />
**appears <br />
**disappears <br />
**is updated <br />
*Control elements to wait for some conditions? <br />
*Reuse of [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|EMF-IncQuery EVM]] <br />
*Question: how to register event-driven rules, possible strategies <br />
**Fully event-driven transformation - every rule registered <br />
**Imperative style: only manual registration <br />
**Something in-between<br />
<br />
=== The imperative language ===<br />
<br />
*essentially based on XBase <br />
*interaction with IncQuery and other features of our own <br />
**maybe we do not even need special syntax for rule invocation, etc.., if we manage to make the API itself simple enough <br />
**one possible simplification: the engine should be already available in the context of this imperative code, so it should be possible to omit <br />
**similarly, try to make IQBase features concisely available <br />
*EMF-specific syntactic sugar for model manipulation (reusable in non-imperative parts?) <br />
**concise access to EPackage elements if they are imported (we need EPackage imports for the query definition part anyway) <br />
**concise object instantiation <br />
***idiom for creating object and initializing fields <br />
***idiom for "create this new object and put it into this ''containment'' reference list so that it becomes part of the model immediately" <br />
***these two should be combinable... ideally we should have something like EMF subtree literals (see also VTML) <br />
**make sure that putting elements into containment lists will translate as NavigationHelper.cheapMoveTo() for the performance benefit<br />
**see if e.g. Epsilon Object Language has good ideas<br />
<br />
=== Extensibility ===<br />
<br />
*Changable control flow (e.g. different interpreter/generated code strategies) <br />
*Insertion of custom Java code (at least as black box rules) <br />
*Other domain support (VPM, triple stores)</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA2/EMF/Transformation_Language&diff=377986VIATRA2/EMF/Transformation Language2015-02-09T14:29:33Z<p>Ujhelyiz.mit.bme.hu: Ujhelyiz.mit.bme.hu moved page VIATRA2/EMF/Transformation Language to VIATRA/Transformation Language</p>
<hr />
<div>#REDIRECT [[VIATRA/Transformation Language]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/EMF/Transformation_API&diff=377984VIATRA/EMF/Transformation API2015-02-09T14:29:04Z<p>Ujhelyiz.mit.bme.hu: Ujhelyiz.mit.bme.hu moved page VIATRA/EMF/Transformation API to VIATRA/Transformation API</p>
<hr />
<div>#REDIRECT [[VIATRA/Transformation API]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Transformation/Transformation_API&diff=377983VIATRA/Transformation/Transformation API2015-02-09T14:29:03Z<p>Ujhelyiz.mit.bme.hu: Ujhelyiz.mit.bme.hu moved page VIATRA/EMF/Transformation API to VIATRA/Transformation API</p>
<hr />
<div>= VIATRA2 EMF Transformation API =<br />
<br />
* Based on [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|EVM]]<br />
* Relies on Xtend features such as extension methods and closures to be <br />
* [[VIATRA2/EMF/Transformation_Language|Language concepts]] (for requirements overview)<br />
* Documentation for API in {{Git|viatra2|org.eclipse.viatra2.emf.git}}<br />
* CI update site: https://hudson.eclipse.org/viatra/job/viatra2-emf-master/lastSuccessfulBuild/artifact/releng/org.eclipse.viatra2.emf.update/target/repository/<br />
<br />
== Batch Transformation API ==<br />
<br />
Three extension classes used for transformations:<br />
* BatchTransformation - hides IncQueryEngine and RuleEngine; manages group initialization of rules - instead of an extension method, this can also be used as a base class<br />
* TransformationStatements - control structure<br />
* ModelManipulation - generic model manipulation primitives; hides details of EditingDomains (if necessary); implementation not batch transformation specific<br />
<br />
=== Batch Transformation Rules ===<br />
<br />
* Special rule type<br />
** Precondition + action<br />
** Life cycle:<br />
*** Stateless<br />
**** rule does not maintain state whether an activation has fired or not<br />
**** Lifecycle: firing: active -> active<br />
*** Stateful<br />
**** rule maintains whether an an activation has fired or not<br />
**** Lifecycle: firing: active -> fired<br />
=== (Batch) Transformation Statements ===<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! fireOne<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires a single activation<br />
|-<br />
! fireAllCurrent<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires all current activations. If the firings change the set of activations, it won't change the set of fired activations.<br />
|-<br />
! fireWhilePossible<br />
| Batch Transformation Rule, (opt: filter)<br />
| Fires the activations one by one. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|-<br />
! fireUntil<br />
| Batch Transformation Rule, break condition, (opt: filter)<br />
| After firing the first activation, it checks whether the break condition became true; if yes, exits, if not, it restarts. It does not store the initial set of activations. Useful for iterate-choose scenarios. Break conditions are implemented using Match Predicates - functions that receive Match instances as parameters.<br />
|}<br />
<br />
== Incremental Transformation API ==<br />
<br />
The incremental API aims at defining and executing model transformations in an event-driven manner. In this case, the preconditions of the single transformations are checked on every related model change in an incremental fashion (using EMF-IncQuery) and the actions are fired once the preconditions are fulfilled. Model changes are captured as events, hence the naming of the basic concepts below.<br />
<br />
* ''EventDrivenTransformation'' - Similarly to the ''BatchTransformation'', it hides the IncQueryEngine and RuleEngine and serves as the basic concept for this part of the API.<br />
* ''EventContext'' - We distinguish two types or contexts of events: point and interval. The former one is described with a single point of appearance on the timeline; the latter one is characterized by its appearance ''and'' disappearance on the timeline. It's up to the user to select whether a transformation is associated with an event of point or interval context. In the background, the event context is translated into an EVM activation life cycle, which can be overridden by the user if required. This concept slightly resembles the concept of batch transformation rules of ''stateless'' and ''stateful'' life cycle.<br />
<br />
=== The event-driven transformation rule (EventDrivenTransformationRule) ===<br />
In contrast with the batch mode, in incremental mode, there are no arbitrarily assembled local conflict sets; instead: every transformation rule is handled in a global conflict set. ''EventDrivenTransformationRuleFactory'' is a factory designed for instantiating the rules.<br />
<br />
=== The essential ideology behind the API structure ===<br />
When designing the API, we reused the concepts of the ''fluent interface'' and the ''builder pattern''. It heavily utilizes the capabilities of Xtend, resulting in a concise way for defining rules, transformations and transformation groups, as presented below.<br />
<br />
=== Example: model transformations for automaton simulation ===<br />
'''Defining the event-driven transformation rule'''<br />
<br />
This is the precondition for your transformation.<br />
<source lang="java"><br />
val createEnabledTransitionRule = ruleFactory.createRule(EnabledTransitionMatcher::querySpecification) [<br />
eventModelManager.strategy.fireTransition(t, et)<br />
]<br />
</source><br />
The above snippet assumes the ''EnabledTransition'' EMF-IncQuery pattern to be defined, which the ''EnabledTransitionMatcher'' has been generated from. The expression in the closure is the action and is totally up to you to define. (In this case, the manager class maintaining the model will fire a transition.) <br />
You can also provide a name for the rule as well as override the default event context (point).<br />
<br />
'''Optionally grouping the rules into rule groups'''<br />
<br />
This one is pretty straightforward; just enumerate your rules in a closure:<br />
<source lang="java"><br />
def getRules() {<br />
new EventDrivenTransformationRuleGroup(<br />
createEnabledTransitionRule,<br />
createFinishedStateMachineRule,<br />
createTokenInTrapStateRule<br />
)<br />
}<br />
</source><br />
Remember, there is only one global conflict set for these rules to get conflicted. It does not really matter whether you group your rules or not, although it can make the further parts of code more concise.<br />
<br />
'''Register the transformation rules'''<br />
<br />
Once you have your transformation rules, there are just a few steps to take in order to register the rules into the execution schema. Let's look at this snippet:<br />
<source lang="java"><br />
def registerRules() {<br />
EventDrivenTransformation.forResource(eventModelManager.resourceSet).addRules(rules).create()<br />
}<br />
</source><br />
The benefits of the fluent API approach are obvious here. Notice the mandatory ''create()'' method at the tail of the method chain as the essence of the builder pattern. This method chain will deal with the following:<br />
# it instantiates an EventDrivenTransformation;<br />
# the resource the transformations are executed upon is passed to the transformation (''forResource()'');<br />
# the transformation rules are registered (''addRules()'');<br />
# in the background, the default conflict resolver (arbitrary CR) is selected to deal with global conflicts.<br />
<br />
If you opt to use a custom conflict resolver, here's how you do it:<br />
<source lang="java"><br />
def registerRulesWithCustomPriorities() {<br />
val fixedPriorityResolver = ConflictResolvers.createFixedPriorityResolver();<br />
fixedPriorityResolver.setPriority(createEnabledTransitionRule.ruleSpecification, 100)<br />
fixedPriorityResolver.setPriority(createFinishedStateMachineRule.ruleSpecification, 50)<br />
fixedPriorityResolver.setPriority(createTokenInTrapStateRule.ruleSpecification, 0)<br />
<br />
EventDrivenTransformation.forResource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(fixedPriorityResolver).create()<br />
}<br />
</source><br />
<br />
However, as a useful feature, the API is capable to construct a fixed priority resolver based on the ''order of the rules'' handed over to the EventDrivenTransformation. So the results of the above code could be just achieved with this one:<br />
<source lang="java"><br />
def registerRulesWithAutomatedPriorities() {<br />
EventDrivenTransformation.forResource(eventModelManager.resourceSet).addRules(rules).<br />
setConflictResolver(GlobalConflictResolver.FIXED_PRIORITY_CONFLICT_RESOLVER).create()<br />
}<br />
</source><br />
<br />
== Model Manipulation Primitives ==<br />
<br />
Model manipulation primitives are implemented by instances of IModelManipulations interface. Currently, two implementations are available:<br />
<br />
# SimpleModelManipulations - uses plain EMF API<br />
# ModelManipulationsWithEditingDomain - uses EMF Edit commands on EditingDomain instances<br />
<br />
If some transformation needs specific primitives (e.g. transaction support), new instances can introduce extra methods as required.<br />
<br />
{|<br />
! Name<br />
! Parameters<br />
! Description<br />
|-<br />
! create<br />
| Resource; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the root of the selected resource<br />
|-<br />
! createChild <br />
| EObject (container); EReference; EClass<br />
| Creates an object with the corresponding EClass type, and puts it into the selected reference; the reference must be of containment type<br />
|-<br />
! addTo<br />
| EObject (container); EStructuralFeature; Object<br />
| Adds an existing object to the corresponding container with a reference; if using a reference it must *not* be of containment type<br />
|-<br />
! remove<br />
| EObject<br />
| Removes the EObject from the model<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature; Object<br />
| Removes an object from the selected container; when using a containment EReference, also removes it from the resource set<br />
|-<br />
! remove<br />
| EObject (container); EStructuralFeature<br />
| Removes all objects from a multivalued feature; when using a containment EReference, also removes them from the resource set<br />
|-<br />
! set<br />
| EObject (container); EStructuralFeature; Object<br />
| Sets the value of a single-valued feature<br />
|-<br />
! move<br />
| EObject(s), EObject (new container), EStructuralFeature<br />
| Moves elements to a new container, and removes them from an old one. 'Remark': The implementation here is specific, as it relies on features of the index.<br />
|}<br />
<br />
== Examples ==<br />
<br />
=== Program understanding (Java code to state charts) ===<br />
<br />
The most up-to-date example can be found here: https://github.com/ujhelyiz/viatra2-programunderstanding<br />
<br />
=== Petri nets to State charts ===<br />
A (not very well tested) example transformation is available by implementing the Petri net to State Charts case of the Transformation Tool Contest 2013.<br />
<br />
* Case description: http://planet-sl.org/community/index.php?option=com_community&view=groups&task=viewgroup&groupid=26&Itemid=387&lang=en<br />
* Implementation: https://github.com/izsob/TTC13-PN2SC-EIQ (look for the branch ''viatra-api'')<br />
** The following snippets are taken from this repository<br />
<br />
==== Setting up a transformation ====<br />
<br />
<source lang="java"><br />
class Pn2ScJobs {<br />
<br />
/* Transformation-related extension API */<br />
extension BatchTransformationRuleFactory ruleFactory = new BatchTransformationRuleFactory<br />
extension BatchTransformation transformation<br />
extension TransformationStatements statements<br />
extension IModelManipulations manipulation<br />
<br />
/* Makes available the Literals of the EPackage for the manipulation API */<br />
extension StatechartsPackage chartPackage = StatechartsPackage.eINSTANCE<br />
<br />
Statechart stateChart<br />
Resource resource<br />
<br />
new(Resource resource) {<br />
/Storing transformation-specific input elements<br />
this.resource = resource<br />
this.stateChart = resource.contents.head as Statechart<br />
<br />
/* Extensions are initialized as normal fields in Xtend */<br />
transformation = new BatchTransformation(resource.resourceSet)<br />
statements = new TransformationStatements(transformation)<br />
manipulation = new SimpleModelManipulations(transformation.iqEngine)<br />
}<br />
<br />
...<br />
<br />
}<br />
</source><br />
<br />
==== Defining rules, rulegroups ====<br />
<br />
Rules can be created using the factory methods of the BatchTransformation class; its actions can be described by an Xtend closure.<br />
<br />
If required, it is possible to extend BatchTransformationRule manually - both implementations are interchangeable.<br />
<br />
<source lang="java"><br />
/**<br />
* Map a PetriNet place to a base state in the StateChart with an "or" container.<br />
*/<br />
val createMapPlaceRuleSpecification = createRule(PlaceMatcher::querySpecification) [<br />
// create base b with b.name=p.name; and the state or, where or.contains={b}<br />
var or = stateChartResource.create(OR) as OR<br />
var basic = or.createChild(compound_Contains, basic) as Basic<br />
basic.set(state_Name, p.name)///name = p.name<br />
// create trace from place to or<br />
createTrace(p, or)<br />
]<br />
<br />
/**<br />
* Map a PetriNet transition to a hyperedge state in the StateChart without an "or" container.<br />
*/<br />
val createMapTransitionRuleSpecification = createRule(TransitionMatcher::querySpecification) [<br />
// create hyperEdge h with h.name=t.name (without an or container)<br />
var hyperEdge = stateChartResource.create(hyperEdge) as HyperEdge<br />
hyperEdge.name = t.name<br />
// create trace from transition to hyperEdge<br />
createTrace(t, hyperEdge)<br />
]<br />
<br />
/**<br />
* Create "next" edges in the StateChart between elements connected in the PetriNet.<br />
*/<br />
val createNextStateRuleSpecification = createRule(NextStateMatcher::querySpecification) [<br />
state1.addTo(state_Next, state2)<br />
]<br />
<br />
/**<br />
* Get rules for performing initial mapping<br />
*/<br />
def getInitialisationRules() {<br />
new TransformationRuleGroup(<br />
createMapPlaceRuleSpecification,<br />
createMapTransitionRuleSpecification,<br />
createNextStateRuleSpecification<br />
)<br />
}<br />
</source><br />
<br />
==== Executing rules, rule groups ====<br />
The primitives ask for a rule and filter<br />
<br />
* A filter is expressed by a collection of name-value pairs (available names come from the precondition pattern)<br />
* Parameter names not mentioned are unconstrained<br />
<br />
<source lang="java"><br />
val moveChildrenRule = createRule(EquivContainsMatcher::querySpecification) [<br />
state.moveTo(newP, compound_Contains)<br />
]<br />
// add children elements to OR of the StateChart<br />
moveChildrenRule.forall("namedElement" -> q)<br />
</source><br />
<br />
The following snippet shows that primitives also work with rule groups with the exact same syntax. The idea here is that the engine decides which rule of the group to execute (based on the ConflictResolver).<br />
<br />
<source lang="java"><br />
def transformPn2Sc() {<br />
// place->OR mapping<br />
initialisationRules.fireWhilePossible<br />
// execute AND and OR rules<br />
andOrRules.fireWhilePossible<br />
// clean orphaned root ORs; and create StateChart root<br />
finalisationRules.fireWhilePossible<br />
}<br />
</source><br />
<br />
<br />
<br />
== Further ideas to evaluate ==<br />
<br />
* "Strict" API vs "relaxed" API<br />
** Everything presented here is a strict API<br />
*** Useful for research goals (e.g. analysis)<br />
*** Might be too strict for Java/EMF programmers<br />
** It might make sense to support transformation with bring-your-own-code style<br />
*** Currently almost all elements are optional in API: statements and model manipulations commands need not to be used -> simple Java/Xtend replacements possible<br />
*** Some simple wrappers might be needed to create RecordingCommands, etc.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA2/VIATRA3&diff=377982VIATRA2/VIATRA32015-02-09T14:28:17Z<p>Ujhelyiz.mit.bme.hu: Cleaning up this page</p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/GettingStarted&diff=377806VIATRA/Query/UserDocumentation/GettingStarted2015-02-06T21:05:03Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>=Installing EMF-IncQuery=<br />
<br />
== Dependencies ==<br />
EMF-IncQuery depends on recent version of Xtext/Xtend.<br />
<br />
{| class="wikitable"<br />
!<br />
! Xtext 2.3<br />
! Xtext 2.4<br />
! Xtext 2.5<br />
! Xtext 2.6<br />
! Xtext 2.7<br />
! Xtext 2.8<br />
|-<br />
! EMF-IncQuery 0.7<br />
|| Compatibility branch || Yes || No || No || No || No<br />
|-<br />
! EMF-IncQuery 0.8<br />
|| No || Runtime only || Runtime only* || Yes || Runtime only || Runtime only ||<br />
|-<br />
! EMF-IncQuery 0.9<br />
|| No || Runtime only || Runtime only || Runtime only || Yes || Runtime only ||<br />
|-<br />
! EMF-IncQuery 1.0*<br />
|| No || Runtime only || Runtime only || Runtime only || Yes || Runtime only ||<br />
|}<br />
Remarks:<br />
* The codebase of EMF-IncQuery 0.8 is compatible with Xtext 2.5, but its editor components needs to be regenerated. To avoid confusion, the code base states it requires Xtext 2.6; but it can trivially be updated to work with 2.5 (after a regeneration of editor).<br />
* EMF-IncQuery 1.0 is planned to be compatible with the Xtext release included in Mars release train, currently planned for 2.8. However, currently (2015.02.06) it works with the same dependency as IncQuery 0.9.<br />
<br />
== Installation ==<br />
The main update site provides both the EMF-IncQuery runtime and the query development extensions for Eclipse. It is recommended to install as few features directly as needed, rely on the p2 installer to download required features:<br />
* Select the ''EMF-IncQuery SDK'' feature<br />
* If you want to use IncQuery with Graphiti or GMF, select the features ''GMF Support for EMF-IncQuery'' or ''Graphiti Support for EMF-IncQuery'', respectively<br />
<br />
=== Additional features ===<br />
* [[EMFIncQuery/UserDocumentation/RETE_Visualizer|Rete visualizer]] - experimental as of the [[GEF/GEF4]] Zest dependency<br />
* Zest graph support for Viewers framework - experimental as of the [[GEF/GEF4]] Zest dependency<br />
<br />
Additionally, this update site contains the latest GEF4 Zest to ease the installation. Because of the frequent changes in GEF4 Zest, the graph viewer components are only tested with this bundled version of Zest - other versions may or may not work.<br />
<br />
= First steps =<br />
The built-in cheat sheet should help you with the first steps. We also maintain a [[EMFIncQuery/UserDocumentation/QueryLanguage | web-based tutorial]]. Additionally, you can check the School and BPMN introductory walkthrough examples to help you get started.<br />
<br />
== Examples ==<br />
We have a list of examples available in [[EMFIncQuery/UserDocumentation/Examples]].</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query&diff=377805VIATRA/Query2015-02-06T21:00:14Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= EMF-IncQuery Wiki Documentation =<br />
<br />
For the query language, we reuse the concepts of graph patterns (which is a key concept in many graph transformation tools) as a concise and easy way to specify complex structural model queries. High runtime performance is achieved by adapting incremental graph pattern matching techniques based on the Rete algorithm.<br />
<br />
We believe the average programmer using EMF models will like EMF-IncQuery for the following reasons:<br />
<br />
* declarative queries can be evaluated over EMF without manually traversing the models,<br />
* complex interrelated constellations of EMF objects can be easily formulated as a graph pattern,<br />
** the language is expressive and provides powerful features such as negation or counting,<br />
** graph patterns are composable and reusable,<br />
** queries can be evaluated with great freedom, i.e. input and output parameters can be selected at run-time,<br />
** some frequently encountered shortcomings of EMF’s interfaces are addressed:<br />
** easy and efficient enumeration of all instances of a class regardless of location,<br />
** simple backwards navigation along all kinds of references (even without eOpposite)<br />
** finding objects based on attribute value,<br />
* the incremental query evaluation mechanism offers a significant performance boost when frequently querying complex structural patterns with a moderate amount of modifications in-between (e.g. during continuous validation),<br />
* from the declarative representation of queries, pattern matcher code is generated which can be distributed as Eclipse plug-ins with very few dependencies.<br />
<br />
<br />
== EMF-IncQuery User Documentation ==<br />
* Developing Incremental Model Queries using the EMF-IncQuery Tooling<br />
** [[EMFIncQuery/UserDocumentation/Installation|Installing EMF-IncQuery]]<br />
** [[EMFIncQuery/UserDocumentation/QueryLanguage|A Short Introduction to the Query Language]]<br />
** [[ EMFIncQuery/UserDocumentation/QueryDevelopment|Getting started with Query Development]]<br />
** [[EMFIncQuery/UserDocumentation/RETE_Visualizer|RETE Visualizer]]<br />
** [[EMFIncQuery/UserDocumentation/DebuggerTooling|EMF-IncQuery Debugger Tooling]] (since 0.8.0)<br />
* Using the EMF-IncQuery Runtime library<br />
** [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless (standalone) execution of EMF-IncQuery queries and unit tests]]<br />
** [[EMFIncQuery/UserDocumentation/API|API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]]<br />
** [[EMFIncQuery/UserDocumentation/API/RunOnce|Run once querying API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/BaseIndexer|IncQuery Base Indexer]]<br />
** [[EMFIncQuery/UserDocumentation/AdvancedPatterns|Advanced pattern language constructs]] <br />
* Integration Components<br />
** [[EMFIncQuery/UserDocumentation/Databinding|Databinding]]<br />
** [[EMFIncQuery/UserDocumentation/Validation|Validation Framework]]<br />
** [[EMFIncQuery/UserDocumentation/Query_Based_Features|Defining Query-based Features]]<br />
** [[EMFIncQuery/UserDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
* [[EMFIncQuery/UserDocumentation/Examples|Examples]]<br />
* [[EMFIncQuery/UserDocumentation/Build|EMF-IncQuery in CI Environments (Maven artifacts)]] (since 0.8.0)<br />
* Reporting bugs or requesting new features<br />
** [[EMFIncQuery/UserDocumentation/IssueTracking|Issue tracking]]<br />
<br />
== Contributor's Guide ==<br />
<br />
* Developer's Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/DevEnvironment|Setting up the Development Environment]]<br />
** [[EMFIncQuery/DeveloperDocumentation/BuildConfig|The EMF-IncQuery Build Configuration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IssueTracking|Issue Reporting and Management]]<br />
* Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/Model_connectors|Model Connectors]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
** [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|Event-driven Virtual Machine]]<br />
** [[EMFIncQuery/DeveloperDocumentation/Builder|Builder Architecture]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQueryXcore|Notes on IncQuery & Xcore integration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/QueryProcessing|Query Processing]]<br />
* Developer Meeting Minutes<br />
** [[EMFIncQuery/DeveloperMeetingMinutes|Meeting minutes]]<br />
<br />
== Releases ==<br />
* Version 0.7.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.7.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/MigrateTo0.7|Migration guide]]<br />
** Known issues affecting version 0.7.1 [[EMFIncQuery/Releases/KnownIssuesFor0.7.1|fixed in 0.7.2]]<br />
* Version 0.8.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.8.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.8|New and Noteworthy]]<br />
** [[EMFIncQuery/Releases/MigrateTo0.8|Migration guide]]<br />
** Known issues affecting version 0.8.1 [[EMFIncQuery/Releases/KnownIssuesFor0.8.1|fixed in 0.8.2]]<br />
* Version 0.9.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.9.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.9|New and Noteworthy]]<br />
[[Category:EmfIncQuery]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Releases/Query/NewAndNoteWorthy0.9&diff=377804VIATRA/Releases/Query/NewAndNoteWorthy0.92015-02-06T20:54:51Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== New and Noteworthy - EMF-IncQuery 0.9.0 ==<br />
<br />
=== Updated to Xtext 2.7 ===<br />
EMF-IncQuery 0.9 was developed and tested with Xtext 2.7. The runtime still works without Xtext installed, but the tooling requires Xtext 2.7 (available from the Luna update site since SR1).<br />
<br />
=== Generalized API for non-EMF query scopes ===<br />
Starting with version 0.9, it possible to instantiate an IncQueryEngine over non-EMF models and formulate queries appropriate against that kind of model. This required some minor changes to the API.<br />
<br />
* An IncQueryEngine can now be instantiated for a scope of query evaluation defined by the newly introduced ''org.eclipse.incquery.runtime.api.scope.IncQueryScope'' interface. For querying over EMF models, use the ''org.eclipse.incquery.runtime.emf.EMFScope'' class, which encompasses an EMF model root (ResourceSet, Resource or containing EObject) as well as the EMF-specific BaseIndexOptions (such as dynamic mode or wildcard mode).<br />
* Query specification declare the type of scope they can be evaluated on by the ''getPreferredScopeClass()'' method. For example, EMF model queries can only be evaluated on EMF models. <br />
* The ''getBaseIndex()'' method on the IncQuery engine returns a non-EMF-specific interface of the base model index. To use EMF-specific features, refer to ''org.eclipse.incquery.runtime.emf.EMFScope.extractUnderlyingEMFIndex()''.<br />
<br />
=== Warnings for recursive pattern calls ===<br />
The use of recursive pattern calls is problematic in EMF-IncQuery: when used incorrectly, its usage may result in incorrectly updated match sets after deletion. Furthermore, using recursion in a negative pattern composition or match counter cannot be evaluated at all.<br />
<br />
In version 0.9.0 a new validator was added to the language that warns when using recursive calls (for the usual cases it is better to use the transitive closure support), and issues an error when used with pattern composition.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=EMFIncQuery/DeveloperDocumentation/DevEnvironment&diff=377076EMFIncQuery/DeveloperDocumentation/DevEnvironment2015-01-28T13:59:39Z<p>Ujhelyiz.mit.bme.hu: /* Editor Settings */</p>
<hr />
<div>== Prerequisites ==<br />
<br />
*Eclipse Modeling Tools 3.7, 3.8, 4.2 or 4.3 distribution <br />
**Other Eclipse distributions might work as well, but this contains EMF-related plug-ins <br />
**Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.3 Kepler and 4.4 Luna) <br />
*Xtext SDK 2.7<br />
**Xtext update site<nowiki> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ </nowiki><br />
**Currently Xtext 2.6 and 2.8 does not work<br />
**This also requires a current version of EMF (2.10)<br />
*[[Xcore|Xcore SDK]] 1.2.1 (1.2.0 does not work)<br />
*EGit (and JGit) - required components for downloading source from Git <br />
**Available from Eclipse Juno update site: <nowiki>http://download.eclipse.org/releases/juno </nowiki><br />
<br />
== Editor Settings ==<br />
<br />
Code style: slightly modified built-in Eclipse style <br />
<br />
* line width: 120 characters both for code and comments <br />
* using spaces for indentation<br />
<br />
Downloadable style available from [[Image:IncQueryFormatter.xml.zip]]<br />
<br />
Comment templates:<br />
* Copyright header for each Java file<br />
* Leaving override annotations out<br />
<br />
Downloadable template available from [[File:Eiq-jdt-templates.xml.zip]]<br />
<br />
== Downloading IncQuery source projects from Git ==<br />
<br />
The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url. <br />
<br />
After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace. <br />
<br />
For details, see the [http://wiki.eclipse.org/EGit/User_Guide Eclipse EGit help] and the [http://www.vogella.com/articles/EGit/article.html Git tutorial from Lars Vogel]. <br />
<br />
Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address. <br />
<br />
== Generating the Editor Components ==<br />
<br />
The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is '''not committed into Git'''; they are to generated in the workspace after cloning and after changes of the grammar or workflow files. <br />
<br />
* The src-gen folders contain code generated by the Xtext code generation workflows. <br />
* The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.<br />
<br />
=== Xtext code generation workflows ===<br />
<br />
The following projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension):<br />
<br />
* ''org.eclipse.incquery.patternlanguage''<br />
* ''org.eclipse.incquery.patternlanguage.emf''<br />
* ''org.eclipse.incquery.tooling.generator.model''<br />
<br />
All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows by selecting ''Run as/MWE2 Workflow'' from the context menu of the .mwe2 file in the corresponding project. In case of the tooling.generator.model project, you may be required to create the folder ''src-gen'' manually the first time. <br />
<br />
All workflow files require about 30-60 seconds to run - be patient.<br />
<br />
'''Important''': In case of future language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.<br><br />
<br />
'''Important''': The workflow of the patternlanguage.emf project might require a large amount of heap/permgen memory. If such issues occur, add extra memory to the workflow using the Run configurations dialog.<br />
<br />
=== Optional dependencies ===<br />
<br />
Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the [[GEF/GEF4|GEF4]] version. Alternatively you can just close the projects depending on them (as they are non-essential). <br />
<br />
As the GEF4 Zest component is under heavy refactoring, the extra update site of EMF-IncQuery also contains a Zest version known working with the current version.<br />
<br />
[[Category:EmfIncQuery]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:Eiq-jdt-templates.xml.zip&diff=377075File:Eiq-jdt-templates.xml.zip2015-01-28T13:58:29Z<p>Ujhelyiz.mit.bme.hu: JDT comment settings for the EMF-IncQuery project.</p>
<hr />
<div>JDT comment settings for the EMF-IncQuery project.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes/Meeting20150123&diff=376915VIATRA/DeveloperMeetingMinutes/Meeting201501232015-01-23T14:50:07Z<p>Ujhelyiz.mit.bme.hu: Created page with "= Meeting Minutes 2015. 01. 23 = == Participants == * Gábor Bergmann * Márton Búr * Csaba Debreceni * Dénes Harmath * Zoltán Ujhelyi == Topics == === Release preparati..."</p>
<hr />
<div>= Meeting Minutes 2015. 01. 23 =<br />
<br />
== Participants ==<br />
* Gábor Bergmann<br />
* Márton Búr<br />
* Csaba Debreceni<br />
* Dénes Harmath<br />
* Zoltán Ujhelyi<br />
<br />
== Topics ==<br />
<br />
=== Release preparation for version 0.9 ===<br />
* Gábor, Zoltán: release preparations going<br />
* Next week is dedicated for testing<br />
* Reviewing API tools: end-user API is more or less stable, internal API (e.g. code generator, engine api for pattern matchers) has big changes. The API tools framework is not well-suited for pre-1.0 versions.<br />
<br />
=== Ongoing tasks ===<br />
* Csaba: viewers refactor updated to latest master version; there is an issue of a missing notification. Code available at https://git.eclipse.org/r/33180<br />
* Dénes: Rete visualizer initialized using the recipe structures of the IncQuery engines; initial version available from https://git.eclipse.org/r/40212<br />
* Márton, Zoli: new engine API should work with local search; some issues needs to be fixed, it will be an ongoing effort</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/DeveloperMeetingMinutes&diff=376914VIATRA/DeveloperMeetingMinutes2015-01-23T14:41:41Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= EMF IncQuery Developer Meeting Minutes =<br />
<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20150123|Meeting Minutes 2015.01.23.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140129|Meeting Minutes 2014.01.29.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140122|Meeting Minutes 2014.01.22.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20140115|Meeting Minutes 2014.01.15.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131211|Meeting Minutes 2013.12.11.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131113|Meeting Minutes 2013.11.13.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131106|Meeting Minutes 2013.11.06.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131016|Meeting Minutes 2013.10.16.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131009|Meeting Minutes 2013.10.09.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20131002|Meeting Minutes 2013.10.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130925|Meeting Minutes 2013.09.25.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130702|Meeting Minutes 2013.07.02.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130611|Meeting Minutes 2013.06.11.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130604|Meeting Minutes 2013.06.04.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130528|Meeting Minutes 2013.05.28.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130521|Meeting Minutes 2013.05.21.]]<br />
* [[EMFIncQuery/DeveloperMeetingMinutes/Meeting20130507|Meeting Minutes 2013.05.07.]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=EMFIncQuery/DeveloperDocumentation/DevEnvironment&diff=376279EMFIncQuery/DeveloperDocumentation/DevEnvironment2015-01-13T13:25:45Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== Prerequisites ==<br />
<br />
*Eclipse Modeling Tools 3.7, 3.8, 4.2 or 4.3 distribution <br />
**Other Eclipse distributions might work as well, but this contains EMF-related plug-ins <br />
**Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.3 Kepler and 4.4 Luna) <br />
*Xtext SDK 2.7<br />
**Xtext update site<nowiki> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ </nowiki><br />
**Currently Xtext 2.6 and 2.8 does not work<br />
**This also requires a current version of EMF (2.10)<br />
*[[Xcore|Xcore SDK]] 1.2.1 (1.2.0 does not work)<br />
*EGit (and JGit) - required components for downloading source from Git <br />
**Available from Eclipse Juno update site: <nowiki>http://download.eclipse.org/releases/juno </nowiki><br />
<br />
== Editor Settings ==<br />
<br />
Code style: slightly modified built-in Eclipse style <br />
<br />
*line width: 120 characters both for code and comments <br />
*using spaces for indentation<br />
<br />
Downloadable style available from [[Image:IncQueryFormatter.xml.zip]] <br />
<br />
== Downloading IncQuery source projects from Git ==<br />
<br />
The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url. <br />
<br />
After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace. <br />
<br />
For details, see the [http://wiki.eclipse.org/EGit/User_Guide Eclipse EGit help] and the [http://www.vogella.com/articles/EGit/article.html Git tutorial from Lars Vogel]. <br />
<br />
Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address. <br />
<br />
== Generating the Editor Components ==<br />
<br />
The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is '''not committed into Git'''; they are to generated in the workspace after cloning and after changes of the grammar or workflow files. <br />
<br />
*The src-gen folders contain code generated by the Xtext code generation workflows. <br />
*The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.<br />
<br />
=== Xtext code generation workflows ===<br />
<br />
The org.eclipse.incquery.patternlanguage, org.eclipse.incquery.patternlanguage.emf and org.eclipse.incquery.tooling.generator.model projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension). All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows by selecting ''Run as/MWE2 Workflow'' from the context menu of the .mwe2 file in the corresponding project. In case of the tooling.generator.model project, you may be required to create the folder "src-gen" manually the first time. <br />
<br />
All workflow files require about 30-60 seconds to run - be patient.<br />
<br />
'''Important''': In case of future language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.<br><br />
<br />
'''Important''': The workflow of the patternlanguage.emf project might require a large amount of heap/permgen memory. If such issues occur, add extra memory to the workflow using the Run configurations dialog.<br />
<br />
=== Optional dependencies ===<br />
<br />
Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the [[GEF/GEF4|GEF4]] version. Alternatively you can just close the projects depending on them (as they are non-essential). <br />
<br />
As the GEF4 Zest component is under heavy refactoring, the extra update site of EMF-IncQuery also contains a Zest version known working with the current version.<br />
<br />
[[Category:EmfIncQuery]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/UserDocumentation/Build&diff=374824VIATRA/UserDocumentation/Build2014-12-09T13:21:26Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= Maven integration =<br />
<br />
Version 0.8.0 of EMF-IncQuery supports building IncQuery projects in a Maven-based builds by generating the pattern matcher code from the eiq files.<br />
<br />
Known limitations:<br />
* {{bug|434794}} - Code generation for integration components (e.g. validation framework, derived features) is not supported.<br />
* {{bug|443715}} - Maven compiler does not work if EMF code is in the same project as the queries. <br />
* The EMF-IncQuery project is not available from Maven Central.<br />
* There is no maven archetype support: it is not possible to generate an eclipse-less project automatically, that works with IncQuery. However, manually created projects can be built with the existing compiler.<br />
<br />
== Repository ==<br />
Maven components are available from the Eclipse maven repository with the following url: https://repo.eclipse.org/content/groups/emf-incquery/<br />
<br />
It includes both snapshot and release versions.<br />
<br />
The following three maven-projects should be used:<br />
# '''org.eclipse.incquery:incquery-runtime''' - dependency for the IncQuery runtime, without support for generic API<br />
# '''org.eclipse.incquery:incquery-patternlanguage''' - dependency for the IncQuery with support for generic API (requires many more dependencies - only use if required)<br />
# '''org.eclipse.incquery:incquery-maven-plugin''' - maven code generator<br />
<br />
== incquery-maven-plugin ==<br />
<br />
The maven plugin requires information from the used EMF packages and additionally the EMF packages should be able loaded as well. For this reason, it is important to add references to EPackages and Genmodels together with the corresponding dependencies.<br />
<br />
Example generator (based on [https://github.com/ujhelyiz/EMF-IncQuery-Examples/blob/master/school/school.incquery/pom.xml school example]):<br />
<br />
<source lang="xml"><br />
<!-- Using maven-clean-plugin to remove previously generated code --><br />
<plugin><br />
<groupId>org.apache.maven.plugins</groupId><br />
<artifactId>maven-clean-plugin</artifactId><br />
<version>2.5</version><br />
<executions><br />
<execution><br />
<phase>clean</phase><br />
<goals><br />
<goal>clean</goal><br />
</goals><br />
<configuration><br />
<filesets><br />
<fileset><br />
<!-- Generated code folder --><br />
<directory>src-gen</directory><br />
<includes><br />
<include>**/*</include><br />
</includes><br />
</fileset><br />
</filesets><br />
</configuration><br />
</execution><br />
</executions><br />
</plugin><br />
<!-- Setting up generator --><br />
<plugin><br />
<groupId>org.eclipse.incquery</groupId><br />
<artifactId>incquery-maven-plugin</artifactId><br />
<version>0.8.0</version><br />
<!-- Binding execution to the code generation lifecycle phase --><br />
<executions><br />
<execution><br />
<goals><br />
<goal>generate</goal><br />
</goals><br />
</execution><br />
</executions><br />
<configuration><br />
<!-- Output directory - required --><br />
<outputDirectory>src-gen</outputDirectory><br />
<metamodels><br />
<metamodel><br />
<!-- Java class for the EMF EPackage --><br />
<packageClass>school.SchoolPackage</packageClass><br />
<!-- genmodel file used for generating the EMF model classes --><br />
<genmodelUri>../school/model/school.genmodel</genmodelUri><br />
</metamodel><br />
</metamodels><br />
</configuration><br />
<dependencies><br />
<!-- Dependency required for the school project (that contains the generated EPackage) --><br />
<dependency><br />
<groupId>org.eclipse.incquery</groupId><br />
<artifactId>school</artifactId><br />
<version>0.8.0</version><br />
</dependency><br />
</dependencies><br />
</plugin><br />
<br />
</source></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/CEP/Roadmap&diff=372651VIATRA/CEP/Roadmap2014-10-23T17:45:53Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>VIATRA CEP Roadmap for Q4 2014 and Q1 2015<br />
<br />
Last revised October 23, 2014<br />
<br />
Please send comments about this draft plan to the [mailto:viatra-dev@eclipse.org viatra-dev@eclipse.org] developer mailing list.<br />
<br />
For the currently active bugs, see [https://bugs.eclipse.org/bugs/buglist.cgi?component=CEP&list_id=10337517&product=Viatra&resolution=--- the related page in the Bugzilla].<br />
<br />
== First release ==<br />
There is no scheduled date for the first official release of the restarted VIATRA project, but it is expected to go in Q2/Q3 of 2015. In the context of the CEP extension, we follow the checkpoints below.<br />
<br />
=== Checkpoint 1: DSL stabilization ===<br />
*Fixes, but '''no enhancements''' for the DSL<br />
**Typical issues: inconsistent code generation from patterns, shortcomings of the IDE while designing patterns, IncQuery integration<br />
*Targeted date: 2014/Q4 -- December 18<br />
<br />
=== Checkpoint 2: Supporting services ===<br />
*Generated factories, interfaces should be revised in order to enable more efficient and component-oriented reuse of the event model<br />
**Typical issues: too much coding required for putting the engine to work (common use-cases should be considered), GUI support (e.g. wizards) are not working with E4.4, project builder, automatic dependency management, unit and integration test packages<br />
*Targeted date: 2015/Q1 -- January 31<br />
<br />
=== Checkpoint 3: DSL enhancements ===<br />
*Targeted date: 2015/Q1 -- February 28<br />
<br />
=== Checkpoint 4: Documentation ===<br />
*Examples with wiki pages and source code, maybe a users manual or tech report (already got one half-done)<br />
*Targeted date: 2015/Q1 -- March 31</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/GettingStarted&diff=371524VIATRA/Query/UserDocumentation/GettingStarted2014-10-06T13:09:20Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>=Installing EMF-IncQuery=<br />
<br />
== Dependencies ==<br />
EMF-IncQuery depends on recent version of Xtext/Xtend.<br />
<br />
{| class="wikitable"<br />
!<br />
! Xtext 2.3<br />
! Xtext 2.4<br />
! Xtext 2.5<br />
! Xtext 2.6<br />
! Xtext 2.7<br />
|-<br />
! EMF-IncQuery 0.7<br />
|| Compatibility branch || Yes || No || No || No<br />
|-<br />
! EMF-IncQuery 0.8<br />
|| No || Runtime only || Runtime only* || Yes || Runtime only ||<br />
|}<br />
Remarks:<br />
* The codebase of EMF-IncQuery 0.8 is compatible with Xtext 2.5, but its editor components needs to be regenerated. To avoid confusion, the code base states it requires Xtext 2.6; but it can trivially be updated to work with 2.5 (after a regeneration of editor).<br />
<br />
== Installation ==<br />
The main update site provides both the EMF-IncQuery runtime and the query development extensions for Eclipse. It is recommended to install as few features directly as needed, rely on the p2 installer to download required features:<br />
* Select the ''EMF-IncQuery SDK'' feature<br />
* If you want to use IncQuery with Graphiti or GMF, select the features ''GMF Support for EMF-IncQuery'' or ''Graphiti Support for EMF-IncQuery'', respectively<br />
<br />
=== Additional features ===<br />
* [[EMFIncQuery/UserDocumentation/RETE_Visualizer|Rete visualizer]] - experimental as of the [[GEF/GEF4]] Zest dependency<br />
* Zest graph support for Viewers framework - experimental as of the [[GEF/GEF4]] Zest dependency<br />
<br />
Additionally, this update site contains the latest GEF4 Zest to ease the installation. Because of the frequent changes in GEF4 Zest, the graph viewer components are only tested with this bundled version of Zest - other versions may or may not work.<br />
<br />
= First steps =<br />
The built-in cheat sheet should help you with the first steps. We also maintain a [[EMFIncQuery/UserDocumentation/QueryLanguage | web-based tutorial]]. Additionally, you can check the School and BPMN introductory walkthrough examples to help you get started.<br />
<br />
== Examples ==<br />
We have a list of examples available in [[EMFIncQuery/UserDocumentation/Examples]].</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=EMFIncQuery/DeveloperDocumentation/DevEnvironment&diff=371346EMFIncQuery/DeveloperDocumentation/DevEnvironment2014-10-01T15:34:11Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== Prerequisites ==<br />
<br />
*Eclipse Modeling Tools 3.7, 3.8, 4.2 or 4.3 distribution <br />
**Other Eclipse distributions might work as well, but this contains EMF-related plug-ins <br />
**Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.3 Kepler and 4.4 Luna) <br />
*Xtext SDK 2.6<br />
**Xtext update site<nowiki> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ </nowiki><br />
**Currently Xtext 2.7 does not work<br />
**This also requires a current version of EMF (2.10)<br />
*[[Xcore|Xcore SDK]] 1.2<br />
*EGit (and JGit) - required components for downloading source from Git <br />
**Available from Eclipse Juno update site: <nowiki>http://download.eclipse.org/releases/juno </nowiki><br />
<br />
== Editor Settings ==<br />
<br />
Code style: slightly modified built-in Eclipse style <br />
<br />
*line width: 120 characters both for code and comments <br />
*using spaces for indentation<br />
<br />
Downloadable style available from [[Image:IncQueryFormatter.xml.zip]] <br />
<br />
== Downloading IncQuery source projects from Git ==<br />
<br />
The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url. <br />
<br />
After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace. <br />
<br />
For details, see the [http://wiki.eclipse.org/EGit/User_Guide Eclipse EGit help] and the [http://www.vogella.com/articles/EGit/article.html Git tutorial from Lars Vogel]. <br />
<br />
Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address. <br />
<br />
== Generating the Editor Components ==<br />
<br />
The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is '''not committed into Git'''; they are to generated in the workspace after cloning and after changes of the grammar or workflow files. <br />
<br />
*The src-gen folders contain code generated by the Xtext code generation workflows. <br />
*The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.<br />
<br />
=== Xtext code generation workflows ===<br />
<br />
The org.eclipse.incquery.patternlanguage, org.eclipse.incquery.patternlanguage.emf and org.eclipse.incquery.tooling.generator.model projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension). All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows by selecting ''Run as/MWE2 Workflow'' from the context menu of the .mwe2 file in the corresponding project. In case of the tooling.generator.model project, you may be required to create the folder "src-gen" manually the first time. <br />
<br />
All workflow files require about 30-60 seconds to run - be patient.<br />
<br />
'''Important''': In case of future language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.<br><br />
<br />
'''Important''': The workflow of the patternlanguage.emf project might require a large amount of heap/permgen memory. If such issues occur, add extra memory to the workflow using the Run configurations dialog.<br />
<br />
=== Optional dependencies ===<br />
<br />
Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the [[GEF/GEF4|GEF4]] version. Alternatively you can just close the projects depending on them (as they are non-essential). <br />
<br />
As the GEF4 Zest component is under heavy refactoring, the extra update site of EMF-IncQuery also contains a Zest version known working with the current version.<br />
<br />
[[Category:EmfIncQuery]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query&diff=371278VIATRA/Query2014-10-01T09:05:44Z<p>Ujhelyiz.mit.bme.hu: /* EMF-IncQuery User Documentation */</p>
<hr />
<div>= EMF-IncQuery Wiki Documentation =<br />
<br />
For the query language, we reuse the concepts of graph patterns (which is a key concept in many graph transformation tools) as a concise and easy way to specify complex structural model queries. High runtime performance is achieved by adapting incremental graph pattern matching techniques based on the Rete algorithm.<br />
<br />
We believe the average programmer using EMF models will like EMF-IncQuery for the following reasons:<br />
<br />
* declarative queries can be evaluated over EMF without manually traversing the models,<br />
* complex interrelated constellations of EMF objects can be easily formulated as a graph pattern,<br />
** the language is expressive and provides powerful features such as negation or counting,<br />
** graph patterns are composable and reusable,<br />
** queries can be evaluated with great freedom, i.e. input and output parameters can be selected at run-time,<br />
** some frequently encountered shortcomings of EMF’s interfaces are addressed:<br />
** easy and efficient enumeration of all instances of a class regardless of location,<br />
** simple backwards navigation along all kinds of references (even without eOpposite)<br />
** finding objects based on attribute value,<br />
* the incremental query evaluation mechanism offers a significant performance boost when frequently querying complex structural patterns with a moderate amount of modifications in-between (e.g. during continuous validation),<br />
* from the declarative representation of queries, pattern matcher code is generated which can be distributed as Eclipse plug-ins with very few dependencies.<br />
<br />
<br />
== EMF-IncQuery User Documentation ==<br />
* Developing Incremental Model Queries using the EMF-IncQuery Tooling<br />
** [[EMFIncQuery/UserDocumentation/Installation|Installing EMF-IncQuery]]<br />
** [[EMFIncQuery/UserDocumentation/QueryLanguage|A Short Introduction to the Query Language]]<br />
** [[ EMFIncQuery/UserDocumentation/QueryDevelopment|Getting started with Query Development]]<br />
** [[EMFIncQuery/UserDocumentation/RETE_Visualizer|RETE Visualizer]]<br />
** [[EMFIncQuery/UserDocumentation/DebuggerTooling|EMF-IncQuery Debugger Tooling]] (since 0.8.0)<br />
* Using the EMF-IncQuery Runtime library<br />
** [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless (standalone) execution of EMF-IncQuery queries and unit tests]]<br />
** [[EMFIncQuery/UserDocumentation/API|API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]]<br />
** [[EMFIncQuery/UserDocumentation/API/RunOnce|Run once querying API documentation]]<br />
** [[EMFIncQuery/UserDocumentation/API/BaseIndexer|IncQuery Base Indexer]]<br />
** [[EMFIncQuery/UserDocumentation/AdvancedPatterns|Advanced pattern language constructs]] <br />
* Integration Components<br />
** [[EMFIncQuery/UserDocumentation/Databinding|Databinding]]<br />
** [[EMFIncQuery/UserDocumentation/Validation|Validation Framework]]<br />
** [[EMFIncQuery/UserDocumentation/Query_Based_Features|Defining Query-based Features]]<br />
** [[EMFIncQuery/UserDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
* [[EMFIncQuery/UserDocumentation/Examples|Examples]]<br />
* [[EMFIncQuery/UserDocumentation/Build|EMF-IncQuery in CI Environments]] (since 0.8.0)<br />
* Reporting bugs or requesting new features<br />
** [[EMFIncQuery/UserDocumentation/IssueTracking|Issue tracking]]<br />
<br />
== Contributors Guide ==<br />
<br />
* Developer's Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/DevEnvironment|Setting up the Development Environment]]<br />
** [[EMFIncQuery/DeveloperDocumentation/BuildConfig|The EMF-IncQuery Build Configuration]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IssueTracking|Issue Reporting and Management]]<br />
* Documentation<br />
** [[EMFIncQuery/DeveloperDocumentation/Model_connectors|Model Connectors]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQuery_Viewers|IncQuery Viewers]]<br />
** [[EMFIncQuery/DeveloperDocumentation/EventDrivenVM|Event-driven Virtual Machine]]<br />
** [[EMFIncQuery/DeveloperDocumentation/Builder|Builder Architecture]]<br />
** [[EMFIncQuery/DeveloperDocumentation/IncQueryXcore|Notes on IncQuery & Xcore integration]]<br />
* Developer Meeting Minutes<br />
** [[EMFIncQuery/DeveloperMeetingMinutes|Meeting minutes]]<br />
<br />
== Releases ==<br />
* Version 0.7.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.7.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/MigrateTo0.7|Migration guide]]<br />
** Known issues affecting version 0.7.1 [[EMFIncQuery/Releases/KnownIssuesFor0.7.1|fixed in 0.7.2]]<br />
* Version 0.8.0 ([https://www.eclipse.org/incquery/javadoc/releases/0.8.0/ Javadoc])<br />
** [[EMFIncQuery/Releases/NewAndNoteWorthy0.8|New and Noteworthy]]<br />
** [[EMFIncQuery/Releases/MigrateTo0.8|Migration guide]]<br />
<br />
[[Category:EmfIncQuery]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/QueryDevelopment&diff=371277VIATRA/Query/UserDocumentation/QueryDevelopment2014-10-01T09:05:08Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>= Overview =<br />
<br />
EMF-IncQuery provides an intuitive user interface to create, edit and debug queries. It assists users with various wizards, supports the editing of query definitions (patterns) in an Xtext-based editor and also provides query debugging features with the Query Explorer view.<br />
<br />
== The main components: ==<br />
[[File:EMFIncQuery-wizards.png]]<br />
<br />
* '''Wizards''': there are wizards available to create EMF-IncQuery project, generator model and queries. These wizards are available under the EMF-IncQuery category when creating new resources (see the picture above)<br />
* '''Query editor''': the Xtext-based editor can be used to create EMF-IncQuery queries. The editor provides many features to ease the development, such as automatic code completion, validation, etc.<br />
* '''Query Explorer''': this view can be used to apply queries on various EMF instance models. The Query Explorer can interact with EMF-based editors such as the generated tree editor, and even with GMF and Graphiti editors. Advanced querying use cases, like pattern match set filtering and detail observation is also available with the Query Explorer. The following picture presents the Pattern Editor and the Query Explorer view.<br />
[[File:EMFIncQuery-queryexplorer.png]]<br />
<br />
== Getting Started ==<br />
=== Create a new EMF-IncQuery project ===<br />
<br />
An EMF-IncQuery project is a special Eclipse plug-in project that registers the EMF-IncQuery builders to generate code from query definitions. To create a new EMF-IncQuery project, select the ''EMF-IncQuery'' project wizard from the ''New item'' wizards in Eclipse.<br />
<br />
=== Create and edit EMF-IncQuery query definitions ===<br />
<br />
The wizard first guides you through the creation of the query container (package) which is similar to the creation of a Java class. The second page helps you create an initial pattern within your new .eiq file. Here you can name your pattern, select the packages that you want to use in your patterns and add pattern parameters with type specification. After finishing with the wizard a new .eiq file will be created with the pattern specified on the second page.<br />
<br />
[[File:EMFIncQuery-new-eiq-file.png]]<br />
<br />
It is best to start with the built-in pattern template (available as a code completion feature). The details of the EMF-IncQuery Query Language are discussed on [[EMFIncQuery/UserDocumentation/QueryLanguage|the language documentation page]].<br />
<br />
=== Executing and debugging queries ===<br />
<br />
The Query Explorer View can be used to execute and debug the queries on EMF instance models. The main features of the Query Explorer view are:<br />
<br />
* You can load your queries into the Query Explorer by pressing the green button on the top right corner of the view. In order to apply queries to a concrete instance model, the queries have to be loaded.<br />
* EMF instance models can be loaded from EMF-based editors such as the generated or reflective EMF tree editors, GMF and Graphiti editors. There are two alternatives when loading such models:<br />
** You can load the whole ResourceSet which is being edited by the editor (this is the default when pressing the green button)<br />
** You can load the Resource of the selected element within the editor which can be done with the appropriate element from the view menu of the green button. <br />
* If at least one query and instance model is loaded, the middle section of the Query Explorer will present the match sets in a tree structure. The top level element corresponds to an editor-instance model pair (because the same instance model can be loaded from different editors and the reversed way is also possible). The elements under the top level elements correspond to the queries and the low-level elements represent the match set of the given query. Note that the contents of the tree viewer are automatically updated upon changes occurring in the match sets of the pattern.<br />
* The Pattern Registry on the left shows the loaded patterns according to the package hierarchy. It distinguishes them by their source, either coming from a generated EMF-IncQuery project from the host workspace or manually loaded ones from the runtime Eclipse. You can select and deselect single patterns or groups of patterns inside the Pattern Registry which will result the loading and unloading of queries for every instance model loaded into the Query Explorer. You can also change the way of package presentation (flat or hierarchical) in the view menu of the Query Explorer.<br />
* Details and filter section on the right side of the view: the view of this content is based on the selection inside the tree viewer. If you select a pattern then you can specify filters on the pattern parameters (this use case is discussed later in this document). However, if you select a single match, you can observe the values of the pattern parameters which are data bound to the appropriate model elements thus automatically refreshed upon match changing. The latter use case can be influenced with the @ObservableValue annotation, which is described in depth on the [[EMFIncQuery/UserDocumentation/Databinding|Data binding documentation page]].<br />
* Almost all elements in the view provides Show Location (in the context menu) functionality which connects the element with its source. For example, if you click the Show Location on a match of a pattern, the appropriate elements will be selected in the editor which is associated to the EMF instance model. Additionally, if you click Show location on a pattern inside the Pattern Registry it will show you the pattern definition in your .eiq file.<br />
* Patterns and instance models can be unloaded from the Query Explorer by clicking Unload model in the context menu. Additionally, if you close the editor of an instance model that is loaded into the Query Explorer, it will automatically unload it.<br />
* Note that, modifying the contents of a .eiq file - that was loaded earlier to the Query Explorer - automatically triggers re-loading of the patterns.<br />
<br />
== Advanced use cases ==<br />
=== Changing the results shown in the Query Explorer ===<br />
<br />
The IncQuery Query Language allows to use annotations for pattern definitions to fine-tune the behavior of a query. The following annotations are supported by the Query Explorer:<br />
<br />
* @ObservableValue: Defines observable values for the pattern's parameters. Although it is basically used to generate accessors for such values to use in databinding contexts, the Query Explorer also presents these values in the Details pane. See the [[EMFIncQuery/UserDocumentation/Databinding|data binding page]] for detailed usage.<br />
* @QueryExplorer: The annotation can be used to define the presentation of the pattern and its match set in the Query Explorer. The annotations defines the following parameters<br />
** checked (Boolean): sets whether the pattern should be displayed in the Query Explorer automatically. If not set, patterns from the workspace are shown; patterns installed into the host are not.<br />
** message (String): the message to be displayed for a specific match, for example "The busiest teacher $T.name$ taught the most sociable student $S.name$ in $Y.startingDate$"- from the school example. Between the '$' marks one can refer to attributes of pattern parameters that will be substituted with the concrete values during runtime.<br />
** @OrderBy: Annotate a pattern with OrderBy to define ordering between matches displayed in the Query Explorer.<br />
<br />
See the hover help (provided by the query editor) for more details on annotations.<br />
=== Parameterized queries ===<br />
<br />
In the Query Explorer you can define filters for the registered patterns. This specification is, however, instance model and pattern-specific (does not apply for the same pattern under different instance model). The aim of this facility is to narrow down the match sets of specific patterns when debugging. The following steps are required to specify a filter:<br />
<br />
* Load an instance model and some queries into the Query Explorer.<br />
* Select a pattern in the tree viewer. The details/filters view will be initialized for filtering.<br />
* You can set filters for each one of the pattern parameters by clicking on the button on the right side of the text input.<br />
* The content of the input field cannot be modified by hand for complex types - they can be selected from the popup window and only model elements from the given instance model is allowed to select. For primitive types, the value can be input directly and it is validated according to the type of the parameter.<br />
<br />
See the following picture for an example filtering from the school example.<br />
[[File:EMFIncQuery-filtering.png]]<br />
=== Wildcard mode ===<br />
<br />
Settable on the EMF-IncQuery preference settings page: in wildcard mode, every aspect of the EMF model is automatically indexed, as opposed to only indexing model elements and features relevant to the currently registered patterns; thus patterns can be registered and unregistered without re-traversing the model. This is typically useful during query development. Turn off wildcard mode to decrease the memory usage while working with very large models.<br />
<br />
[[ File:EMFIncQuery-wildcard-preferences.png ]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:EMFIncQuery-wildcard-preferences.png&diff=371276File:EMFIncQuery-wildcard-preferences.png2014-10-01T09:04:58Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:EMFIncQuery-filtering.png&diff=371275File:EMFIncQuery-filtering.png2014-10-01T09:04:23Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:EMFIncQuery-new-eiq-file.png&diff=371274File:EMFIncQuery-new-eiq-file.png2014-10-01T09:03:28Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:EMFIncQuery-queryexplorer.png&diff=371273File:EMFIncQuery-queryexplorer.png2014-10-01T09:02:03Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:EMFIncQuery-wizards.png&diff=371271File:EMFIncQuery-wizards.png2014-10-01T08:59:53Z<p>Ujhelyiz.mit.bme.hu: Ujhelyiz.mit.bme.hu moved page File:Wizards.png to File:EMFIncQuery-wizards.png</p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:Wizards.png&diff=371272File:Wizards.png2014-10-01T08:59:53Z<p>Ujhelyiz.mit.bme.hu: Ujhelyiz.mit.bme.hu moved page File:Wizards.png to File:EMFIncQuery-wizards.png</p>
<hr />
<div>#REDIRECT [[File:EMFIncQuery-wizards.png]]</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=File:EMFIncQuery-wizards.png&diff=371270File:EMFIncQuery-wizards.png2014-10-01T08:59:09Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div></div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/QueryDevelopment&diff=371269VIATRA/Query/UserDocumentation/QueryDevelopment2014-10-01T08:56:59Z<p>Ujhelyiz.mit.bme.hu: Created page with "= Overview = EMF-IncQuery provides an intuitive user interface to create, edit and debug queries. It assists users with various wizards, supports the editing of query definit..."</p>
<hr />
<div>= Overview =<br />
<br />
EMF-IncQuery provides an intuitive user interface to create, edit and debug queries. It assists users with various wizards, supports the editing of query definitions (patterns) in an Xtext-based editor and also provides query debugging features with the Query Explorer view.<br />
<br />
== The main components: ==<br />
<br />
* '''Wizards''': there are wizards available to create EMF-IncQuery project, generator model and queries. These wizards are available under the EMF-IncQuery category when creating new resources (see the picture below)<br />
* '''Query editor''': the Xtext-based editor can be used to create EMF-IncQuery queries. The editor provides many features to ease the development, such as automatic code completion, validation, etc.<br />
* '''Query Explorer''': this view can be used to apply queries on various EMF instance models. The Query Explorer can interact with EMF-based editors such as the generated tree editor, and even with GMF and Graphiti editors. Advanced querying use cases, like pattern match set filtering and detail observation is also available with the Query Explorer. The following picture presents the Pattern Editor and the Query Explorer view.<br />
<br />
== Getting Started ==<br />
=== Create a new EMF-IncQuery project ===<br />
<br />
An EMF-IncQuery project is a special Eclipse plug-in project that registers the EMF-IncQuery builders to generate code from query definitions. To create a new EMF-IncQuery project, select the ''EMF-IncQuery'' project wizard from the ''New item'' wizards in Eclipse.<br />
<br />
=== Create and edit EMF-IncQuery query definitions ===<br />
<br />
The wizard first guides you through the creation of the query container (package) which is similar to the creation of a Java class. The second page helps you create an initial pattern within your new .eiq file. Here you can name your pattern, select the packages that you want to use in your patterns and add pattern parameters with type specification. After finishing with the wizard a new .eiq file will be created with the pattern specified on the second page.<br />
<br />
It is best to start with the built-in pattern template (available as a code completion feature). The details of the EMF-IncQuery Query Language are discussed on [[EMFIncQuery/UserDocumentation/QueryLanguage|the language documentation page]].<br />
<br />
=== Executing and debugging queries ===<br />
<br />
The Query Explorer View can be used to execute and debug the queries on EMF instance models. The main features of the Query Explorer view are:<br />
<br />
* You can load your queries into the Query Explorer by pressing the green button on the top right corner of the view. In order to apply queries to a concrete instance model, the queries have to be loaded.<br />
* EMF instance models can be loaded from EMF-based editors such as the generated or reflective EMF tree editors, GMF and Graphiti editors. There are two alternatives when loading such models:<br />
** You can load the whole ResourceSet which is being edited by the editor (this is the default when pressing the green button)<br />
** You can load the Resource of the selected element within the editor which can be done with the appropriate element from the view menu of the green button. <br />
* If at least one query and instance model is loaded, the middle section of the Query Explorer will present the match sets in a tree structure. The top level element corresponds to an editor-instance model pair (because the same instance model can be loaded from different editors and the reversed way is also possible). The elements under the top level elements correspond to the queries and the low-level elements represent the match set of the given query. Note that the contents of the tree viewer are automatically updated upon changes occurring in the match sets of the pattern.<br />
* The Pattern Registry on the left shows the loaded patterns according to the package hierarchy. It distinguishes them by their source, either coming from a generated EMF-IncQuery project from the host workspace or manually loaded ones from the runtime Eclipse. You can select and deselect single patterns or groups of patterns inside the Pattern Registry which will result the loading and unloading of queries for every instance model loaded into the Query Explorer. You can also change the way of package presentation (flat or hierarchical) in the view menu of the Query Explorer.<br />
* Details and filter section on the right side of the view: the view of this content is based on the selection inside the tree viewer. If you select a pattern then you can specify filters on the pattern parameters (this use case is discussed later in this document). However, if you select a single match, you can observe the values of the pattern parameters which are data bound to the appropriate model elements thus automatically refreshed upon match changing. The latter use case can be influenced with the @ObservableValue annotation, which is described in depth on the [[EMFIncQuery/UserDocumentation/Databinding|Data binding documentation page]].<br />
* Almost all elements in the view provides Show Location (in the context menu) functionality which connects the element with its source. For example, if you click the Show Location on a match of a pattern, the appropriate elements will be selected in the editor which is associated to the EMF instance model. Additionally, if you click Show location on a pattern inside the Pattern Registry it will show you the pattern definition in your .eiq file.<br />
* Patterns and instance models can be unloaded from the Query Explorer by clicking Unload model in the context menu. Additionally, if you close the editor of an instance model that is loaded into the Query Explorer, it will automatically unload it.<br />
* Note that, modifying the contents of a .eiq file - that was loaded earlier to the Query Explorer - automatically triggers re-loading of the patterns.<br />
<br />
== Advanced use cases ==<br />
=== Changing the results shown in the Query Explorer ===<br />
<br />
The IncQuery Query Language allows to use annotations for pattern definitions to fine-tune the behavior of a query. The following annotations are supported by the Query Explorer:<br />
<br />
* @ObservableValue: Defines observable values for the pattern's parameters. Although it is basically used to generate accessors for such values to use in databinding contexts, the Query Explorer also presents these values in the Details pane. See the [[EMFIncQuery/UserDocumentation/Databinding|data binding page]] for detailed usage.<br />
* @QueryExplorer: The annotation can be used to define the presentation of the pattern and its match set in the Query Explorer. The annotations defines the following parameters<br />
** checked (Boolean): sets whether the pattern should be displayed in the Query Explorer automatically. If not set, patterns from the workspace are shown; patterns installed into the host are not.<br />
** message (String): the message to be displayed for a specific match, for example "The busiest teacher $T.name$ taught the most sociable student $S.name$ in $Y.startingDate$"- from the school example. Between the '$' marks one can refer to attributes of pattern parameters that will be substituted with the concrete values during runtime.<br />
** @OrderBy: Annotate a pattern with OrderBy to define ordering between matches displayed in the Query Explorer.<br />
<br />
See the hover help (provided by the query editor) for more details on annotations.<br />
=== Parameterized queries ===<br />
<br />
In the Query Explorer you can define filters for the registered patterns. This specification is, however, instance model and pattern-specific (does not apply for the same pattern under different instance model). The aim of this facility is to narrow down the match sets of specific patterns when debugging. The following steps are required to specify a filter:<br />
<br />
* Load an instance model and some queries into the Query Explorer.<br />
* Select a pattern in the tree viewer. The details/filters view will be initialized for filtering.<br />
* You can set filters for each one of the pattern parameters by clicking on the button on the right side of the text input.<br />
* The content of the input field cannot be modified by hand for complex types - they can be selected from the popup window and only model elements from the given instance model is allowed to select. For primitive types, the value can be input directly and it is validated according to the type of the parameter.<br />
<br />
See the following picture for an example filtering from the school example.<br />
<br />
=== Wildcard mode ===<br />
<br />
Settable on the EMF-IncQuery preference settings page: in wildcard mode, every aspect of the EMF model is automatically indexed, as opposed to only indexing model elements and features relevant to the currently registered patterns; thus patterns can be registered and unregistered without re-traversing the model. This is typically useful during query development. Turn off wildcard mode to decrease the memory usage while working with very large models.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=VIATRA/Query/UserDocumentation/API&diff=370272VIATRA/Query/UserDocumentation/API2014-09-12T14:24:24Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== Overview ==<br />
<br />
This page presents the basics of EMF-IncQuery's Java API. It supersedes the following contents of the original documentation on IncQuery.net: <br />
<br />
*http://incquery.net/incquery/new/examples/application (Headless example) <br />
*http://incquery.net/incquery/documentation/api (Pattern Matcher API documentation) <br />
*http://incquery.net/incquery/new/examples/school#Generated_code_overview (The latter part of the School example)<br />
<br />
The contents only over the basic use-cases. For advanced features, see [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]]. <br />
<br />
=== Running example ===<br />
<br />
All the code examples and explanations will be given in the context of the [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless]] example. The up-to-date sample source code to this page is found in Git here: http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless Most notably, <br />
<br />
*the patterns are found in [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/headlessQueries.incquery/src/headless/headlessQueries.eiq headlessQueries.eiq] <br />
*and the API usage samples are found in [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/org.eclipse.incquery.application/src/org/eclipse/incquery/application/common/IncQueryHeadless.java IncQueryHeadless.java]<br />
<br />
=== Javadoc ===<br />
<br />
The most up-to-date Javadocs for the EMF-IncQuery API can be found online at http://eclipse.org/incquery/javadoc/ <br />
<br />
== EMF-IncQuery Java API ==<br />
<br />
The most typical way of using the EMF-IncQuery API is to make use of the generated code that is found in the "src-gen" folder of your EMF-IncQuery project. This generated code provides easy and typesafe access to most of EMF-IncQuery's features from Java code. The only important thing to keep in mind is that the generated code is available only when your EMF-IncQuery project is loaded into the Eclipse runtime, i.e. for working with the generated code for development purposes you'll need to use Eclipse Application launch configurations. <br />
<br />
EMF-IncQuery also supports a "dynamic", generic API that allows to make use of patterns without relying on the generated code. The generic API shares functionality with the base classes of the "generated" API, and for most scenarios there is no performance difference between the two. A notable exception for this rule of thumb are '''check() expressions''', where the generated code that is invoked through the generated API will execute the Java code instead of interpreting Xbase. <br />
<br />
In this wiki, we will present a simple introduction to the basics of the "generated" API, to introduce features that will help you to integrate EMF-IncQuery queries into your Java application. The [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]] page discusses the usage of the dynamic and generic APIs. <br />
<br />
=== Most important classes and their relationships ===<br />
<br />
For every pattern definition, the EMF-IncQuery tooling generates a '''Match''', a '''Matcher''', into a Java package that corresponds to the package of the pattern definition, constituting the public API that is intended for client code usage. In addition, some helper classes are generated into the ".uitl" subpackage: <br />
<br />
*if check expressions are present in your pattern definition, several '''Evaluator''' classes are also generated. <br />
*a '''MatchProcessor''' class is generated to aid match set traversal. <br />
*Finally, a '''QuerySpecification''' helper class is also generated that supports advanced lifecycle management (which is not necessary in most cases).<br />
<br />
In order to fully understand the capabilities of these classes, it is a good idea to read through the [[EMFIncQuery/UserDocumentation/API/Advanced#The_IncQuery_Generic_API|Generic API]] section of the [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API features]] page. <br />
<br />
==== Match ====<br />
<br />
A '''Match object''' represents a single match of the pattern, i.e. a tuple of objects whose members point to corresponding elements of the instance model (or scalar values) that the pattern is matched against. It is essentially a Data Transfer Object that is used to extract query result information from EMF-IncQuery, with an SQL analogy you could think of it as one "row" of the result set of a query. The generated fields correspond to the pattern header parameters. <br />
<br />
You can also use '''Match''' objects to specify fixed input parameters to a query (while other fields can be left unspecified) - analogously to a "prepared" SQL statement that accepts input parameter bindings. In this case, the input Match will act as a filter (mask) and the results of you queries will also be instances of this class (where parameters already have the values given in the input). See TODO below for further details. <br />
<br />
The code example below shows the '''EClassNamesMatch''' class generated for the '''eClassNames''' pattern of the running example. The generated class implements the interface [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IPatternMatch.html IPatternMatch] and extends the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/impl/BasePatternMatch.html BasePatternMatch] internal implementation class. <br />
<br />
<source lang="java"><br />
public abstract class EClassNamesMatch implements IPatternMatch {<br />
/**<br />
* members and constructor<br />
*/<br />
private EClass fC;<br />
private String fN;<br />
private static String[] parameterNames = {"C", "N"};<br />
private EClassNamesMatch(EClass pC, String pN) {}<br />
/** getters and setters **/<br />
public Object get(String parameterName) { }<br />
public EClass getC() {}<br />
public String getN() {}<br />
public boolean set(String parameterName, Object newValue) {}<br />
public void setC(EClass pC) {}<br />
public void setN(String pN) {}<br />
/** utility functions **/<br />
public String patternName() {}<br />
public String[] parameterNames() {}<br />
public Object[] toArray() {}<br />
public String prettyPrint() {}<br />
<br />
public int hashCode() {}<br />
public boolean equals(Object obj) {}<br />
/** access to the internal EMF-based representation, as a sort of "reflection" **/<br />
public Pattern pattern() {}<br />
/** Mutable inner subclass so that matches can be "setted" - for parameter passing **/<br />
static final class Mutable extends EClassNamesMatch {}<br />
}<br />
</source> <br />
<br />
==== Matcher ====<br />
<br />
The '''Matcher''' is the main entry point of the EMF-IncQuery API, with pattern-specific query methods. It provides access to the three key features of EMF-IncQuery: <br />
<br />
*First of all it provides means to '''initialize a pattern matcher''' for a given EMF instance model which can either be a Resource, a ResourceSet, or an EObject (in this latter case, the scope of the matching will be the containment tree under the passed EObject). We recommend the use of ResourceSets if possible to avoid cross-reference related issues. <br />
*After the initialization of the engine, the Matcher provides '''getter methods to retrieve the contents of the match set'''. For easy iteration over the match set it provides a convenience method (forEachMatch) as well, as this is the most frequent use case in our observation. Of course it contains other handy features (e.g.: countMatches, hasMatch) to help integration. <br />
*Finally, it provides means to efficiently '''track the changes in the match set''' in an event-driven fashion.<br />
<br />
The example generated source code below demonstrates the '''EClassNamesMatcher''' class generated for the '''eClassNames''' pattern from the running example. The matcher class implements the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IncQueryMatcher.html IncQueryMatcher] generic interface, and its implementation code extends the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/impl/BaseGeneratedMatcher.html BaseGeneratedMatcher] internal class, inheriting several useful methods. In the listing below, we show some methods that are not actually part of generated code, but conform to the interface&nbsp;!IncQueryMatcher and are accessible through interitance from&nbsp;!BaseGeneratedMatcher. <source lang="java"><br />
public class EClassNamesMatcher implements IncQueryMatcher<EClassNamesMatch> {<br />
/** initializer methods **/<br />
public EClassNamesMatcher(IncQueryEngine engine) throws IncQueryException {}<br />
<br />
/** access to match set **/<br />
public Collection<EClassNamesMatch> getAllMatches(); // inherited<br />
public Collection<EClassNamesMatch> getAllMatches(EClass pC, final String pN) {}<br />
public EClassNamesMatch getOneArbitraryMatch(); // inherited<br />
public EClassNamesMatch getOneArbitraryMatch(EClass pC, String pN) {}<br />
public boolean hasMatch(); // inherited<br />
public boolean hasMatch(EClass pC, String pN) {}<br />
public int countMatches(); // inherited<br />
public int countMatches(EClass pC, String pN) {}<br />
<br />
/** Retrieve the set of values that occur in matches for C or N.**/<br />
public Set<EClass> getAllValuesOfC() {}<br />
public Set<EClass> getAllValuesOfC(EClassNamesMatch partialMatch) {}<br />
public Set<EClass> getAllValuesOfC(String pN) {}<br />
public Set<String> getAllValuesOfN() {}<br />
public Set<String> getAllValuesOfN(EClassNamesMatch partialMatch) {}<br />
public Set<String> getAllValuesOfN(EClass pC) {}<br />
<br />
/** iterate over matches using a lambda **/<br />
public void forEachMatch(IMatchProcessor<? super EClassNamesMatch> processor); // inherited<br />
public void forEachMatch(EClass pC, String pN, IMatchProcessor<? super EClassNamesMatch> processor) {}<br />
public void forOneArbitraryMatch(IMatchProcessor<? super EClassNamesMatch> processor); // inherited<br />
public boolean forOneArbitraryMatch(EClass pC, String pN, IMatchProcessor<? super EClassNamesMatch> processor) {}<br />
<br />
/** Returns a new (partial) Match object for the matcher. <br />
* This can be used e.g. to call the matcher with a partial match. **/<br />
public EClassNamesMatch newMatch(EClass pC, String pN) {}<br />
}<br />
</source> <br />
<br />
<br> <br />
<br />
==== Helper classes ====<br />
<br />
*'''MatchProcessor'''<br />
<br />
The Matcher provides a function to iterate over the match set and invoke the process() method of the IMatchProcessor interface with every match. You can think of this as a "lambda" to ease typical query result processing tasks. To this end, an abstract processor class is generated, which you can override to implement the logic you would like to use. The abstract class unpacks the match variables so it can be used directly in the process() method. <br />
<br />
The source code example below implements the [http://eclipse.org/incquery/javadoc/milestones/m2/org/eclipse/incquery/runtime/api/IMatchProcessor.html IMatchProcessor] interface. <source lang="java"><br />
/**<br />
* A match processor tailored for the headless.eClassNames pattern.<br />
*/<br />
public abstract class EClassNamesProcessor implements IMatchProcessor<EClassNamesMatch> {<br />
/**<br />
* Defines the action that is to be executed on each match.<br />
*/<br />
public abstract void process(final EClass C, final String N);<br />
}<br />
</source> <br />
<br />
*'''Evaluator''': If your pattern contains check expressions an evaluator java code is generated from it. It is used by the engine during a query to evaluate the expression’s result. In most cases you don’t need to deal with these classes. <br />
*'''QuerySpecification''': A pattern-specific specification that can instantiate a Matcher class in a type-safe way. You can get an instance of it via the Matcher class’s specification() method. The recommended way to instantiate a Matcher is with an '''IncQueryEngine'''. In both cases if the pattern is already registered (with the same root in the case of the Notifier method) then only a lightweight reference is created which points to the existing engine.<br />
<br />
The code sample extends the [http://eclipse.org/incquery/javadoc/milestones/m3/org/eclipse/incquery/runtime/api/impl/BaseGeneratedQuerySpecification.html BaseGeneratedQuerySpecification] class. <source lang="java"><br />
/**<br />
* A pattern-specific query specification that can instantiate EClassNamesMatcher in a type-safe way.<br />
*/<br />
public final class EClassNamesQuerySpecification extends BaseGeneratedQuerySpecification<EClassNamesMatcher> {<br />
/** @return the singleton instance of the query specification **/<br />
public static EClassNamesQuerySpecification instance() throws IncQueryException {}<br />
}<br />
</source> <br />
<br />
=== Lifecycle management ===<br />
<br />
In EMF-IncQuery, all pattern matching (query evaluation) is carried out in '''IncQueryEngine''' instances that are accessed through the user-friendly generated classes of the public API. The '''IncQueryEngine''' associated to your patterns can be accessed and managed through the '''EngineManager''' singleton class, to track and manipulate their lifecycles. By default, for each instance model root (Resource, ResourceSet or EObject tree) a single, managed '''IncQueryEngine''' is created, which is shared by all objects that access EMF-IncQuery's features through the generated API. The '''IncQueryEngine''' is attached to an EMF model root (Notifier of concrete type '''Resource''', '''ResourceSet''' or '''EObject''') and '''it is retained on the heap as long as the model itself is there'''. It will listen on EMF update notifications stemming from the given model in order to maintain live results. If you release all references to the model (e.g. unload the resource), the '''IncQueryEngine''' can also be garbage collected (as long as there are no other inbound references on it). <br />
<br />
In all, for most (basic) scenarios, the following workflow should be followed: <br />
<br />
*initialize/load the model <br />
*initialize your '''IncQueryEngine''' instance <br />
*initialize pattern matchers, or groups of pattern matchers and use them <br />
*if you release the model and your '''IncQueryEngine''' instance, all resources will be freed by the garbage collector.<br />
<br />
For advanced scenarios (if you wish to manage lifecycles at a more finegrained level), you have the option of creating '''unmanaged''' IncQueryEngines and dispose of them independently of your instance model. For most use-cases though, we recommend the use of managed engines, this is the default and optimized behavior, as these engines can share common indices and caches to save memory and CPU time. The '''EngineManager''' ensures that there will be no duplicated engine for the same model root (Notifier) object. Creating an unmanaged engine will give you certain additional benefits, however additional considerations should be applied. See [[EMFIncQuery/UserDocumentation/API/Advanced#.23Advanced_IncQuery_Lifecycle_management|Advanced lifecycle management]] for details. <br />
<br />
=== Typical programming patterns ===<br />
<br />
In the followings, we provide short source code samples (with some explanations) that cover the most important use-cases supported by the EMF-IncQuery API. <br />
<br />
===== Loading an instance model and executing a query =====<br />
<br />
<source lang="java"><br />
<br />
// get all matches of the pattern<br />
// initialization<br />
// phase 1: (managed) IncQueryEngine<br />
IncQueryEngine engine = IncQueryEngine.on(resource /* or resourceSet */); <br />
// phase 2: the matcher itself<br />
EObjectMatcher matcher = EObjectMatcher.on(engine);<br />
// get all matches of the pattern<br />
Collection<EObjectMatch> matches = matcher.getAllMatches();<br />
// process matches, produce some output<br />
StringBuilder results = new StringBuilder();<br />
prettyPrintMatches(results, matches);<br />
</source> <br />
<br />
===== Using the MatchProcessor =====<br />
<br />
With the MatchProcessor you can iterate over the matches of a pattern quite easily: <source lang="java"><br />
matcher2.forEachMatch(new EClassNamesProcessor() {<br />
@Override<br />
public void process(EClass c, String n) {<br />
results.append("\tEClass: " + c.toString() + "\n");<br />
}<br />
}); <br />
</source> <br />
<br />
===== Matching with partially bound input parameters and using result set projections =====<br />
<br />
An important aspect of EMF-IncQuery queries is that they are '''bidirectional''' in the sense that they accept input bindings, to filter/project the result set with a given input constraint. The following example illustrates the usage of the match processor with an input binding that restricts the result set to the cases where the second parameter (the name of the EClass) takes the value "A": <source lang="java"><br />
matcher2.forEachMatch( matcher2.newMatch(null, "A") , new EClassNamesProcessor() {<br />
@Override<br />
public void process(EClass c, String n) {<br />
results.append("\tEClass with name A: " + c.toString() + "\n");<br />
}<br />
}); <br />
<br />
// alternatively:<br />
matcher2.forEachMatch(null, "A" , new EClassNamesProcessor() {<br />
@Override<br />
public void process(EClass c, String n) {<br />
results.append("\tEClass with name A: " + c.toString() + "\n");<br />
}<br />
});<br />
</source> The input bindings may be used for all match result set methods. <br />
<br />
Additionally, the '''getAllValuesOf...''' methods allow you to perform projections of the result set to one of the parameters: <source lang="java"><br />
// projections<br />
for (EClass ec: matcher2.getAllValuesOfc(matcher2.newMatch(null,"A")))<br />
{<br />
results.append("\tEClass with name A: " + ec.toString() + "\n");<br />
}<br />
</source> <br />
<br />
===== Initialization of pattern groups =====<br />
<br />
Using pattern groups is important for performance. By default, EMF-IncQuery performs a traversal of the instance model when a matcher is accessed through the '''IncQueryEngine''' for the first time. If you wish to use several pattern matchers, it is a good idea to make use of the generated pattern group class and prepare the IncQueryEngine to perform a combined traversal (with minimal additional overhead) so that any additional Matcher initializations avoid re-traversals. <br />
<br />
<source lang="java"><br />
// phase 1: (managed) IncQueryEngine<br />
IncQueryEngine engine = IncQueryEngine.on(resource);<br />
// phase 2: the group of pattern matchers<br />
HeadlessQueries patternGroup = HeadlessQueries.instance();<br />
patternGroup.prepare(engine);<br />
// from here on everything is the same<br />
EObjectMatcher matcher = EObjectMatcher.on(engine);<br />
// get all matches of the pattern<br />
Collection<EObjectMatch> matches = matcher.getAllMatches();<br />
prettyPrintMatches(results, matches);<br />
// ... //<br />
// matching with partially bound input parameters<br />
// because EClassNamesMatcher is included in the patterngroup, *no new traversal* will be done here<br />
EClassNamesMatcher matcher2 = EClassNamesMatcher.on(engine);<br />
</source> <br />
<br />
===== Tracking changes in match sets efficiently =====<br />
<br />
There are some usecases where you don’t want to follow every change of a pattern’s match, just gather them together and process them when you’re ready. EMF-IncQuery provides several means of doing this (see the [[EMFIncQuery/UserDocumentation/API/Advanced#Advanced_query_result_set_change_processing|Advanced query result set change processing]] page for details), but we recommend using JFace databinding for basic purposes. To this end, the '''IncQueryObservables''' utility class can transform the result set of your matcher into an observable list or set that can be tracked and even data bound easily. <br />
<br />
For headless (or non-UI thread) execution, please use the simple [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/org.eclipse.incquery.application/src/org/eclipse/incquery/application/common/DefaultRealm.java DefaultRealm] implementation provided in the example (and invoke it on the appropriate thread). <br />
<br />
<source lang="java"><br />
// (+) changes can also be tracked using JFace Databinding<br />
// this approach provides good performance, as the observable callbacks are guaranteed to be called<br />
// in a consistent state, and only when there is a relevant change; anything<br />
// can be written into the callback method<br />
// (-) * the databinding API introduces additional dependencies<br />
// * is does not support generics, hence typesafe programming is not possible<br />
// * a "Realm" needs to be set up for headless execution<br />
DefaultRealm realm = new DefaultRealm(); // this is necessary for headless execution (or when you<br />
// wish to execute outside of the UI thread. make sure to invoke it on the appropriate thread!<br />
IObservableSet set = IncQueryObservables.observeMatchesAsSet(matcher);<br />
set.addSetChangeListener(new ISetChangeListener() {<br />
@Override<br />
public void handleSetChange(SetChangeEvent event) {<br />
for (Object _o : event.diff.getAdditions()) {<br />
if (_o instanceof EPackageMatch) {<br />
results.append("\tNew EPackage found by changeset databinding: " + ((EPackageMatch)_o).getP().getName()+"\n");<br />
}<br />
}<br />
});<br />
</source> <br />
<br />
With this facility, it is easy to build an Eclipse UI on top of abstract views of your model. Additionally, two further features you may find useful are:<br />
*[[EMFIncQuery/UserDocumentation/Databinding|IncQuery Databinding]] provides means to define observable values on pattern matches that can be used for displaying individual results in JFace viewers<br />
*A complementary feature is provided by [[EMFIncQuery/UserDocumentation/IncQuery Viewers|IncQuery Viewers]], which provides additional, higher level and easy-to-use generative features to further ease this task (and also add very powerful visualization capabilities to developing queries).<br />
<br />
== Advanced capabilities ==<br />
<br />
In addition to the basic features discussed above, EMF-IncQuery provides several additional advanced features of interest: <br />
<br />
*the Generic API to dynamically instantiate and execute patterns from code, without code generation <br />
*advanced query result change processing and lifecycle management features for performance-critical and/or resource constrained applications <br />
*IncQuery Base, a light-weight standalone base indexer library that provides incremental evaluation for core queries such as "get all instances", "get inverse reference targets", as well as incremental transitive closure.<br />
<br />
These topics are discussed in detail on the [[EMFIncQuery/UserDocumentation/API/Advanced|Advanced API topics]] page.</div>Ujhelyiz.mit.bme.huhttps://wiki.eclipse.org/index.php?title=EMFIncQuery/DeveloperDocumentation/DevEnvironment&diff=368410EMFIncQuery/DeveloperDocumentation/DevEnvironment2014-08-05T13:50:52Z<p>Ujhelyiz.mit.bme.hu: </p>
<hr />
<div>== Prerequisites ==<br />
<br />
*Eclipse Modeling Tools 3.7, 3.8, 4.2 or 4.3 distribution <br />
**Other Eclipse distributions might work as well, but this contains EMF-related plug-ins <br />
**Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.3 Kepler and 4.4 Luna) <br />
*Xtext SDK 2.7<br />
**Xtext update site<nowiki> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ </nowiki><br />
**This also requires a current version of EMF (2.10)<br />
*[[Xcore|Xcore SDK]] 1.2<br />
*EGit (and JGit) - required components for downloading source from Git <br />
**Available from Eclipse Juno update site: <nowiki>http://download.eclipse.org/releases/juno </nowiki><br />
<br />
== Editor Settings ==<br />
<br />
Code style: slightly modified built-in Eclipse style <br />
<br />
*line width: 120 characters both for code and comments <br />
*using spaces for indentation<br />
<br />
Downloadable style available from [[Image:IncQueryFormatter.xml.zip]] <br />
<br />
== Downloading IncQuery source projects from Git ==<br />
<br />
The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url. <br />
<br />
After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace. <br />
<br />
For details, see the [http://wiki.eclipse.org/EGit/User_Guide Eclipse EGit help] and the [http://www.vogella.com/articles/EGit/article.html Git tutorial from Lars Vogel]. <br />
<br />
Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address. <br />
<br />
== Generating the Editor Components ==<br />
<br />
The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is '''not committed into Git'''; they are to generated in the workspace after cloning and after changes of the grammar or workflow files. <br />
<br />
*The src-gen folders contain code generated by the Xtext code generation workflows. <br />
*The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.<br />
<br />
=== Xtext code generation workflows ===<br />
<br />
The org.eclipse.incquery.patternlanguage, org.eclipse.incquery.patternlanguage.emf and org.eclipse.incquery.tooling.generator.model projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension). All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows by selecting ''Run as/MWE2 Workflow'' from the context menu of the .mwe2 file in the corresponding project. In case of the tooling.generator.model project, you may be required to create the folder "src-gen" manually the first time. <br />
<br />
All workflow files require about 30-60 seconds to run - be patient.<br />
<br />
'''Important''': In case of future language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.<br><br />
<br />
'''Important''': The workflow of the patternlanguage.emf project might require a large amount of heap/permgen memory. If such issues occur, add extra memory to the workflow using the Run configurations dialog.<br />
<br />
=== Optional dependencies ===<br />
<br />
Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the [[GEF/GEF4|GEF4]] version. Alternatively you can just close the projects depending on them (as they are non-essential). <br />
<br />
As the GEF4 Zest component is under heavy refactoring, the extra update site of EMF-IncQuery also contains a Zest version known working with the current version.<br />
<br />
[[Category:EmfIncQuery]]</div>Ujhelyiz.mit.bme.hu