Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "VIATRA/Integration/MWE2 Integration"
(Created the initial page.) |
|||
Line 14: | Line 14: | ||
Generic modeling workflows can be easily described via using the Xtext Modeling Workflow Engine. It enables the creation of components with various attributes, and it executes them in order. More, exact information about the Xtext MWE 2 can be found at https://www.eclipse.org/Xtext/documentation/306_mwe2.html | Generic modeling workflows can be easily described via using the Xtext Modeling Workflow Engine. It enables the creation of components with various attributes, and it executes them in order. More, exact information about the Xtext MWE 2 can be found at https://www.eclipse.org/Xtext/documentation/306_mwe2.html | ||
− | == | + | == VIATRA MWE2 Integration Library == |
− | + | The VIATRA MWE2 Integration library provides support for defining complex transformation chains using Xtext MWE 2 workflows. As it can be seen on the figure below, due to the fact that the transformation chain itself is an MWE component, it can be easily integrated into higher level modeling workflows. | |
− | + | [[File:VIATRAMWE2.png]] | |
− | The | + | The Transformation chain consists of numerous transformation steps and channels. This is required as certain transformations (for example event-driven transformations) do not follow the batch execution semantics of the MWE language. This way incremental transformation can be wrapped into batch transformation chains. Transformation steps represent the individual transformations. Channels can be used to determine dependability relations between the steps themselves. If a step listens to a channel, the addition of a certain event to the channel will enable the execution of the step. After the execution has finished, new events are pushed to the site's target channels. Note, that the transformation chain itself has input and output channels. These can be used to indicate the first and last transformation steps in the chain. |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | === | + | ===Prerequisites and Installation=== |
− | * | + | |
− | * | + | In order to use this library, the following Eclipse plug-ins are required: |
− | ** | + | *Eclipse Modeling 4.4 Luna recommended |
− | * | + | *EMF-IncQuery 1.0.0 --> http://download.eclipse.org/incquery/updates/integration |
− | ** | + | *MWE2 Language SDK 2.7.1 --> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ |
+ | |||
+ | After the prerequisites are met clone the following repository and import the contained projects. Note, that it contains the source of the VIATRA framework as well. | ||
+ | https://github.com/lunkpeter/org.eclipse.viatra | ||
+ | |||
+ | ===Library Classes=== | ||
+ | |||
+ | The library defines a set of base classes which represent the main elements the previously described transformation workflow semantics. User defined behavior can be added to these elements via inheritance. | ||
+ | *'''TransformationChain''': Represents a basic transformation chain. It provides an interface for defining transformation steps, as well as owns references to its inwards and outwards facing channels. | ||
+ | *'''TranformationStep''': Base abstract class for defining transformation steps. It stores references to the channels it targets and listens to. The user defined functionality can be defined in the execute, initialize and dispose methods. It also provides an interface for the addition of event processors. Transformation steps execute if ONE of their listening channels are triggered by an event. | ||
+ | *'''SyncTranformationStep''': Child class of the TransformationStep class. Synchronizing transformation steps only execute if ALL of their listening channels are triggered by an event. | ||
+ | *'''Channel''': Representation of transformation chain channels. It contains a set of events, and provides an interface for defining a custom event factory. | ||
+ | *'''IEvent''': Interface for events | ||
+ | *'''ControlEvent''': Implements the IEvent interface and represents a regular control event with no data flow. | ||
+ | *'''Advanced Features:''' | ||
+ | **'''IEventFactory''': Provides an interface for adding and removing certain typed events to and from the channel it is attached to. The events can contain parameters. Event and parameter types are specified as generic type parameters. | ||
+ | **'''ControlEventFactory''': Responsible for managing control events. Every channel owns one of these by default. | ||
+ | **'''EventProcessor''': Abstract class responsible for processing a certain type of Event. It can be attached to a transformation step. The type of the processed events are defined by generic type parameters. | ||
+ | **'''ControlEventProcessor''': Child class of the EventProcessor, processes control events. | ||
+ | |||
+ | ===Example=== | ||
+ | The usage of these classes can be most effectively described via a simple 'Hello World' example: | ||
+ | |||
+ | *Create a new Eclipse plug-in project via File Menu --> New --> Project | ||
+ | *Create a new MWE2 file (in a not default package) using the similar method. If prompted, add the Xtext nature to the project. | ||
+ | |||
+ | ====Define Transformation Steps==== | ||
+ | |||
+ | In the next step define the concrete transformation steps. Add these classes to the package created before. | ||
+ | |||
+ | '''BatchTransformationStep.java''' | ||
+ | |||
+ | <source lang="java"> | ||
+ | import org.eclipse.emf.mwe2.runtime.workflow.IWorkflowContext; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.Channel; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.EventProcessor; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.IEvent; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.TransformationStep; | ||
+ | |||
+ | public class BatchTransformationStep extends TransformationStep { | ||
+ | @Override | ||
+ | public void initialize(IWorkflowContext ctx) { | ||
+ | // create transformation | ||
+ | System.out.println("Init batch transformation"); | ||
+ | this.context = ctx; | ||
+ | } | ||
+ | public void execute() { | ||
+ | for (Channel channel : listeningChannels) { | ||
+ | IEvent<? extends Object> nextEvent = channel.getNextEvent(); | ||
+ | for (EventProcessor<? extends IEvent<?>> processor : processors) { | ||
+ | processor.processEvent(nextEvent); | ||
+ | } | ||
+ | } | ||
+ | System.out.println("Batch transformation executed"); | ||
+ | for (Channel channel : getTargetChannels()) { | ||
+ | try { | ||
+ | channel.registerEvent(null); | ||
+ | } catch (InterruptedException e) { | ||
+ | e.printStackTrace(); | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | @Override | ||
+ | public void dispose() { | ||
+ | isRunning = false; | ||
+ | System.out.println("Dispose batch transformation"); | ||
+ | } | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | '''EventDrivenTransformationStep.java''' | ||
+ | |||
+ | <source lang="java"> | ||
+ | import org.eclipse.emf.mwe2.runtime.workflow.IWorkflowContext; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.Channel; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.EventProcessor; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.IEvent; | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.TransformationStep; | ||
+ | |||
+ | public class EventDrivenTransformationStep extends TransformationStep { | ||
+ | @Override | ||
+ | public void initialize(IWorkflowContext ctx) { | ||
+ | System.out.println("Init event-driven transformation"); | ||
+ | this.context = ctx; | ||
+ | |||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void execute() { | ||
+ | for (Channel channel : listeningChannels) { | ||
+ | IEvent<? extends Object> nextEvent = channel.getNextEvent(); | ||
+ | for (EventProcessor<? extends IEvent<?>> processor : processors) { | ||
+ | processor.processEvent(nextEvent); | ||
+ | } | ||
+ | } | ||
+ | System.out.println("Send tick to event-driven transformation"); | ||
+ | for (Channel channel : getTargetChannels()) { | ||
+ | try { | ||
+ | channel.registerEvent(null); | ||
+ | } catch (InterruptedException e) { | ||
+ | e.printStackTrace(); | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void dispose() { | ||
+ | isRunning = false; | ||
+ | System.out.println("Dispose event-driven transformation"); | ||
+ | |||
+ | } | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | ====Define Transformation Structure==== | ||
+ | |||
+ | Define the transformation chain structure using the MWE2 language. Make sure to include all the referenced packages (if the classes are in the same package as the MWE2 file, include that package as well), and that the module name matches the containing package. | ||
+ | |||
+ | '''TransformationDemo.mwe2''' | ||
+ | |||
+ | <source lang="java"> | ||
+ | module org.eclipse.viatra.emf.mwe2orchestrator.transdemo | ||
+ | |||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.* | ||
+ | import org.eclipse.viatra.emf.mwe2orchestrator.transdemo.* | ||
+ | |||
+ | var chainStartChannel = Channel {} | ||
+ | var chainEndChannel = Channel {} | ||
+ | |||
+ | var BatchChannel = Channel {} | ||
+ | var EventDrivenChannel = Channel {} | ||
+ | |||
+ | Workflow { | ||
+ | component = TransformationChain { | ||
+ | inChannel = chainStartChannel | ||
+ | outChannel = chainEndChannel | ||
+ | |||
+ | transformationStep = EventDrivenTransformationStep { | ||
+ | listeningChannel = chainStartChannel | ||
+ | listeningChannel = EventDrivenChannel | ||
+ | targetChannel = BatchChannel | ||
+ | } | ||
+ | |||
+ | transformationStep = BatchTransformationStep { | ||
+ | listeningChannel = BatchChannel | ||
+ | targetChannel = chainEndChannel | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | This example is included in the library project under the *.transdemo package. | ||
== Project Locations == | == Project Locations == | ||
Line 43: | Line 184: | ||
The library itself can be found at https://github.com/lunkpeter/org.eclipse.viatra/tree/master/MWE/org.eclipse.viatra.emf.mwe2orchestrator | The library itself can be found at https://github.com/lunkpeter/org.eclipse.viatra/tree/master/MWE/org.eclipse.viatra.emf.mwe2orchestrator | ||
It contains a simple example as well. | It contains a simple example as well. | ||
+ | Note that at its current state, the library itself is not an integrated part of the VIATRA framework, however as this inclusion is intended in the future, the library is in the org.eclipse.viatra namespace. |
Revision as of 04:38, 2 June 2015
Contents
Transformation Chains Using VIATRA MWE 2 Integration
Motivation
Define heterogeneous model transformation chains using a specialized description language.
- Sequence of model transformation steps can be easily specified and maintained.
- Nontrivial side-effect relations between transformation steps can be handled.
- The execution of event-driven transformation can be controlled.
- Because of the specialized language, the description code base is short and easily expandable
MWE 2 Basics
Generic modeling workflows can be easily described via using the Xtext Modeling Workflow Engine. It enables the creation of components with various attributes, and it executes them in order. More, exact information about the Xtext MWE 2 can be found at https://www.eclipse.org/Xtext/documentation/306_mwe2.html
VIATRA MWE2 Integration Library
The VIATRA MWE2 Integration library provides support for defining complex transformation chains using Xtext MWE 2 workflows. As it can be seen on the figure below, due to the fact that the transformation chain itself is an MWE component, it can be easily integrated into higher level modeling workflows.
The Transformation chain consists of numerous transformation steps and channels. This is required as certain transformations (for example event-driven transformations) do not follow the batch execution semantics of the MWE language. This way incremental transformation can be wrapped into batch transformation chains. Transformation steps represent the individual transformations. Channels can be used to determine dependability relations between the steps themselves. If a step listens to a channel, the addition of a certain event to the channel will enable the execution of the step. After the execution has finished, new events are pushed to the site's target channels. Note, that the transformation chain itself has input and output channels. These can be used to indicate the first and last transformation steps in the chain.
Prerequisites and Installation
In order to use this library, the following Eclipse plug-ins are required:
- Eclipse Modeling 4.4 Luna recommended
- EMF-IncQuery 1.0.0 --> http://download.eclipse.org/incquery/updates/integration
- MWE2 Language SDK 2.7.1 --> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/
After the prerequisites are met clone the following repository and import the contained projects. Note, that it contains the source of the VIATRA framework as well. https://github.com/lunkpeter/org.eclipse.viatra
Library Classes
The library defines a set of base classes which represent the main elements the previously described transformation workflow semantics. User defined behavior can be added to these elements via inheritance.
- TransformationChain: Represents a basic transformation chain. It provides an interface for defining transformation steps, as well as owns references to its inwards and outwards facing channels.
- TranformationStep: Base abstract class for defining transformation steps. It stores references to the channels it targets and listens to. The user defined functionality can be defined in the execute, initialize and dispose methods. It also provides an interface for the addition of event processors. Transformation steps execute if ONE of their listening channels are triggered by an event.
- SyncTranformationStep: Child class of the TransformationStep class. Synchronizing transformation steps only execute if ALL of their listening channels are triggered by an event.
- Channel: Representation of transformation chain channels. It contains a set of events, and provides an interface for defining a custom event factory.
- IEvent: Interface for events
- ControlEvent: Implements the IEvent interface and represents a regular control event with no data flow.
- Advanced Features:
- IEventFactory: Provides an interface for adding and removing certain typed events to and from the channel it is attached to. The events can contain parameters. Event and parameter types are specified as generic type parameters.
- ControlEventFactory: Responsible for managing control events. Every channel owns one of these by default.
- EventProcessor: Abstract class responsible for processing a certain type of Event. It can be attached to a transformation step. The type of the processed events are defined by generic type parameters.
- ControlEventProcessor: Child class of the EventProcessor, processes control events.
Example
The usage of these classes can be most effectively described via a simple 'Hello World' example:
- Create a new Eclipse plug-in project via File Menu --> New --> Project
- Create a new MWE2 file (in a not default package) using the similar method. If prompted, add the Xtext nature to the project.
Define Transformation Steps
In the next step define the concrete transformation steps. Add these classes to the package created before.
BatchTransformationStep.java
import org.eclipse.emf.mwe2.runtime.workflow.IWorkflowContext; import org.eclipse.viatra.emf.mwe2orchestrator.Channel; import org.eclipse.viatra.emf.mwe2orchestrator.EventProcessor; import org.eclipse.viatra.emf.mwe2orchestrator.IEvent; import org.eclipse.viatra.emf.mwe2orchestrator.TransformationStep; public class BatchTransformationStep extends TransformationStep { @Override public void initialize(IWorkflowContext ctx) { // create transformation System.out.println("Init batch transformation"); this.context = ctx; } public void execute() { for (Channel channel : listeningChannels) { IEvent<? extends Object> nextEvent = channel.getNextEvent(); for (EventProcessor<? extends IEvent<?>> processor : processors) { processor.processEvent(nextEvent); } } System.out.println("Batch transformation executed"); for (Channel channel : getTargetChannels()) { try { channel.registerEvent(null); } catch (InterruptedException e) { e.printStackTrace(); } } } @Override public void dispose() { isRunning = false; System.out.println("Dispose batch transformation"); } }
EventDrivenTransformationStep.java
import org.eclipse.emf.mwe2.runtime.workflow.IWorkflowContext; import org.eclipse.viatra.emf.mwe2orchestrator.Channel; import org.eclipse.viatra.emf.mwe2orchestrator.EventProcessor; import org.eclipse.viatra.emf.mwe2orchestrator.IEvent; import org.eclipse.viatra.emf.mwe2orchestrator.TransformationStep; public class EventDrivenTransformationStep extends TransformationStep { @Override public void initialize(IWorkflowContext ctx) { System.out.println("Init event-driven transformation"); this.context = ctx; } @Override public void execute() { for (Channel channel : listeningChannels) { IEvent<? extends Object> nextEvent = channel.getNextEvent(); for (EventProcessor<? extends IEvent<?>> processor : processors) { processor.processEvent(nextEvent); } } System.out.println("Send tick to event-driven transformation"); for (Channel channel : getTargetChannels()) { try { channel.registerEvent(null); } catch (InterruptedException e) { e.printStackTrace(); } } } @Override public void dispose() { isRunning = false; System.out.println("Dispose event-driven transformation"); } }
Define Transformation Structure
Define the transformation chain structure using the MWE2 language. Make sure to include all the referenced packages (if the classes are in the same package as the MWE2 file, include that package as well), and that the module name matches the containing package.
TransformationDemo.mwe2
module org.eclipse.viatra.emf.mwe2orchestrator.transdemo import org.eclipse.viatra.emf.mwe2orchestrator.* import org.eclipse.viatra.emf.mwe2orchestrator.transdemo.* var chainStartChannel = Channel {} var chainEndChannel = Channel {} var BatchChannel = Channel {} var EventDrivenChannel = Channel {} Workflow { component = TransformationChain { inChannel = chainStartChannel outChannel = chainEndChannel transformationStep = EventDrivenTransformationStep { listeningChannel = chainStartChannel listeningChannel = EventDrivenChannel targetChannel = BatchChannel } transformationStep = BatchTransformationStep { listeningChannel = BatchChannel targetChannel = chainEndChannel } } }
This example is included in the library project under the *.transdemo package.
Project Locations
The library itself can be found at https://github.com/lunkpeter/org.eclipse.viatra/tree/master/MWE/org.eclipse.viatra.emf.mwe2orchestrator It contains a simple example as well. Note that at its current state, the library itself is not an integrated part of the VIATRA framework, however as this inclusion is intended in the future, the library is in the org.eclipse.viatra namespace.