Components documentation

[71]

The code of GEMOC studio is gathered in several main groups.

The organization of these groups is driven by feature but also try to minimize dependencies.

Components overview

Figure 49. Components overview


1. Commons

Unresolved directive in master.asciidoc - include::../../../../../../gemoc-studio-modeldebugging/commons/docs/dev/Commons.asciidoc[]

2. Simulation model animation framework

[72]

Important

The initial design of this component comes from GEMOC ANR project. Some relevant architecture information not copied yet in this document may be found in http://gemoc.irisa.fr/ins-pub/m30/gemoc-anr-d4.3.1-v1.0.pdf

Tip

The content of this framework can be used standalone in order to use only basic animation and debug services. The concrete implementation then has to create its own engine and launcher architecture (Ie. reproduce the other parts of the GEMOC framework in order to integrate the DSL in the IDE UI). An example of such implementation can be found with the Arduino Designer demo https://github.com/mbats/arduino

2.1. Debugger

This is the base for the debugger.

Base DSLDebugger overview

Figure 50. Base debugger presentation overview


2.2. Debug model presentation

The debug model presentation is responsible for GUI representation of the debug model. It provides icons and labels. It also opens editor when a breakpoint is hit, or an instruction must be displayed for a given stack frame The DSL debugger provides a default implementation for generated EMF editors integration.

It can be used via the following extension:

<extension point="org.eclipse.debug.ui.debugModelPresentations">
	<debugModelPresentation
		class="org.eclipse.gemoc.dsl.debug.ide.sirius.ui.DSLDebugModelPresentation"
		id="com.example.dsl.ui.debugModel">
	</debugModelPresentation>
</extension>

It can also be extended for specific needs. For example, the GEMOC Framework provides an extended version of the Debug model presentation. See Section 3.1.2, “Debug model presentation”.

Base Debug model presentation overview

Figure 51. Base debug model presentation overview


3. GEMOC framework

3.1. Execution Framework

[73]

Figure 52, “ExecutionEngine overview” shows a typical concrete engine implementation. In this diagram, we use the concrete classes coming from the JavaEngine (see Section 5.1, “Java Execution”). Where the PlainK3ExecutionEngine is able to correctly deal with the step notifications to the IEngineAddon thanks to an IStepManager implementation in K3. This management of the Step notification may differ depending on the Engine and the technology used to implement the DSL behavior (mocml, ALE, XMOF, …​).

ExecutionEngine overview

Figure 52. ExecutionEngine overview


Figure 53, “ExecutionEngine typical flow” shows a typical execution flow of the Engine. The couple Engine and execution transformation must implement the IExecutionEngine interface (cf. Figure 56, “Execution Framework API Interfaces overview”) and are in charge of calling the methods of IengineAddon during the model execution.

In this sequence diagram, calls to Addons are actually a call to the corresponding method to all registered classes implementing IEngineAddon for the current execution context.

ExecutionEngine typical flow

Figure 53. ExecutionEngine typical flow


In most situation, the registration of addons is done using the org.eclipse.gemoc.gemoc_language_workbench.engine_addon or the org.eclipse.gemoc.gemoc_language_workbench.xdsml plugin extension points. Addons registered via extension points can be enabled or disabled by the end user in the launch configuration tab. (see Section 1.1.1, “Sequential Engine Launch Configuration” and Section 1.1.2, “Concurrent Launch configuration” in the Modeling Workbench User Guide)

Addons registered on org.eclipse.gemoc.gemoc_language_workbench.engine_addon extension point are supposed language agnostic and should apply to any DSL. However they may be engine dependent. They are typically designed by GEMOC contributors who wish to extend GEMOC features.

Addons registered on org.eclipse.gemoc.gemoc_language_workbench.xdsml extension point are supposed language specific and should apply to a single DSL. They are typically designed by a Language designer who which to offer a specific feature for the language he is developing.

Mandatory addons do not need to be declared as extension point, they are directly handled by the engine/launcher implementation. (search for a call to addEngineAddon in order to find addons that are programmatically added to the execution.

Two main examples for mandatory addons are:

  • the Sirius animation used by Sirius services is registered in AbstractSequentialGemocLauncher.launch
  • the debugger itself is registered in AbstractGemocLauncher.getDebugger. As it is responsible for pausing the execution flow on steps according to the breakpoints, it listens the calls to the engine events.

3.1.1. Execution Framework Debugger

The debugger of the GEMOC Execution Framework is based on the DSLDebugger of the Simulation and model animation framework (see Section 2.1, “Debugger”).

ExecutionFramework DSLDebugger overview

Figure 54. Execution framework debugger overview


3.1.2. Debug model presentation

The GEMOC Framework implements an extension of the Debug model presentation structure of the Simulation and model animation framework (see Section 2.1, “Debugger”).

Execution framework debug model presentation overview

Figure 55. Execution framework debug model presentation overview


TODO

3.2. Framework Commons

[74]

List of plugins:

  • org.eclipse.gemoc.executionframework.reflectivetrace.model:
  • org.eclipse.gemoc.opsemanticsview.gen:
  • org.eclipse.gemoc.opsemanticsview.gen.k3 :
  • org.eclipse.gemoc.opsemanticsview.model :
  • org.eclipse.gemoc.ws.server :
  • org.eclipse.gemoc.xdsmlframework.api :
  • org.eclipse.gemoc.xdsmlframework.commons :
  • org.eclipse.gemoc.xdsmlframework.commons.ui.k3 :

3.3. Websocket server

The org.eclipse.gemoc.ws.server plugin offers services to add websocket endpoints in an Eclipse application (with UI or headless).

The plugin starts a websocket server on a free port of the system. It uses Jetty as server.

It defines an extension point to define websocket endpoint so any other plugin can contribute their endpoint.

Example of use declaring a test endpoint:

In your plugin.xml:

<extension point="org.eclipse.gemoc.ws.server.endpoint">
  <GEMOC_WS_EndPoint
    class="org.example.endpoint.TestEndPoint" 1
    id="org.example.TestEndPoint">
  </GEMOC_WS_EndPoint>
</extension>

1

Name of the class implementing JSR 356 javax.websocket.server.ServerEndpoint.

Class implementing the endpoint.

package org.example.endpoint;

import javax.websocket.OnMessage;
import javax.websocket.server.ServerEndpoint;

@ServerEndpoint("/test") 1
public class TestEndPoint {

    @OnMessage
    public void handleOnMessage(String message) {
        System.out.println("Message received by WebSocket : "+message); 2
    }
}

1

path in the websocket server. If the alocated port is 96458, the endpoint is available at ws://0.0.0.0:96458/test (or ws://localhost:96458/test )

2

behavior when receiving message on this endpoint.

On start, the server look for an available port (this is displayed on the console).

Tip

An example of plugin using the org.eclipse.gemoc.ws.server in GEMOC Studio (available in the IDE and headless application) is org.eclipse.gemoc.executionframework.addon.eaop.server.

Note

The websocket server is started only when the org.eclipse.gemoc.ws.server plugin starts, you may either need to add it to the OSGI start or wait for another plugin to use it.

3.4. Framework Commons XDSLMFramework

Figure 56, “Execution Framework API Interfaces overview” shows some of the major interfaces of the execution framework API. Most notably, the IEngineAddon and IExecutionEngine interfaces that are the entry points when implementing an Addon for GEMOC.

Execution Framework API Interfaces overview

Figure 56. Execution Framework API Interfaces overview


Tip

The section Section 4.1, “Developing new Addons” contains some details and code snippets about how to write an engine addon.

3.5. XDSML Framework

[75]

The XDSML framework relies on the Section 3.2, “Framework Commons” and offers some base classes for implementing the Language workbench UI.

4. Trace framework

Unresolved directive in master.asciidoc - include::../../../../../../gemoc-studio-modeldebugging/trace/docs/dev/Trace.asciidoc[]

Unresolved directive in master.asciidoc - include::../../../../../../gemoc-studio-modeldebugging/trace/docs/dev/TraceCommons.asciidoc[]

Unresolved directive in master.asciidoc - include::../../../../../../gemoc-studio-modeldebugging/trace/docs/dev/TraceGenerator.asciidoc[]

Unresolved directive in master.asciidoc - include::../../../../../../gemoc-studio-modeldebugging/trace/docs/dev/TraceManager.asciidoc[]

5. Execution engines

5.1. Java Execution

[76]

The Java execution offers a way to express sequential behavior using Java and compatible languages such as xtend+K3.

As usual in the studio, the code is split between part dedicated to the Language Workbench or to the Modeling Workbench. Th code for the Language workbench is located in the java_xdsml folder, the code for the modeling workbench is in java_engine.

5.1.1. Java XDSML

[77]

This component implements the user interface and services for the language workbench dedicated to the case of the JavaEngine. As seen in Figure 49, “Components overview”, it is based on the XDSML Framework from GEMOC Framewok.

5.1.2. Java Engine

[78]

This component implements the services and user interface modeling workbench dedicated to the case of the JavaEngine. As seen in Figure 49, “Components overview”, it is based on the Execution Framework from GEMOC Framewok.

The engine provides the class org.eclipse.gemoc.execution.sequential.javaengine/src/org/eclipse/gemoc/execution/sequential/javaengine/PlainK3ExecutionEngine.java as a base implementation for the AbstractCommandBasedSequentialExecutionEngine.java class.

It relies on IStepManager and StepManagerRegistry provided by K3 in order to correctly do the notification calls to the Addons for each of the method that have been annotated with the @Step annotation.

PlainK3ExecutionEngine overview

Figure 57. PlainK3ExecutionEngine overview


PlainK3ExecutionEngine typical flow

Figure 58. ExecutionEngine typical flow


5.2. ALE Execution

[79]

The ALE execution offers a way to express sequential behavior using ALE language.

5.2.1. ALE XDSML

[80]

This component implements the user interface and services for the language workbench dedicated to the case of the ALE Engine. As seen in Figure 49, “Components overview”, it is based on the XDSML Framework from GEMOC Framewok.

5.2.2. ALE Interpreted Engine

[81]

This component implements the services and user interface modeling workbench dedicated to the case of the JavaEngine. As seen in Figure 49, “Components overview”, it is based on the Execution Framework from GEMOC Framewok.

The engine provides the class org.eclipse.gemoc.ale.interpreted.engine/src/org/eclipse/gemoc/ale/interpreted/engine/AleEngine.java as a base implementation for the AbstractCommandBasedSequentialExecutionEngine.java class.

Similarly to K3, it relies on annotations in the ALE code in order to correctly do the notification calls to the Addons.

This includes @step, @main, and @init annotations.

In order to achieve this, it registers to org.eclipse.emf.ecoretools.ale.core.interpreter.services.ServiceCallListener.

ALE Interpreter Execution Engine overview

Figure 59. ALE Interpreter ExecutionEngine overview