Skip to content

Commit 30e69df

Browse files
dvojtisedvojtise
authored
Improve documentation (#221)
* udpate description of commons * improve commons doc add ws.server doc * added a section about the current protocol generator * adjust width Signed-off-by: Didier Vojtisek <didier.vojtisek@inria.fr>
1 parent f754715 commit 30e69df

File tree

4 files changed

+135
-2
lines changed

4 files changed

+135
-2
lines changed

‎commons/docs/dev/Commons.asciidoc‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,14 @@ They are organized in order to minimize the dependencies to Eclipse.
5353
- `org.eclipse.gemoc.commons.eclipse.messagingsystem.ui`: UI for messagingsystem.api
5454
- `org.eclipse.gemoc.commons.eclipse.pde`: various helper classes and abstract classes allowing to manipulate plugin definition (modify manifest, classpath, build.properties);
5555
it also offers a base _new project wizard_ supporting extensible templates.
56-
- `org.eclipse.gemoc.commons.eclipse.ui`
56+
- `org.eclipse.gemoc.commons.eclipse.ui` : helpers related to Eclipse UI.
57+
- `org.eclipse.gemoc.commons.eclipse.xtext` : helpers related to xText.
5758

5859

60+
==== Commons
61+
62+
- `org.eclipse.gemoc.commons.utils` : helpers not related to any framework. Currently contains classes useful in protocol management.
63+
5964
[[devguide-commons-timeline]]
6065
==== Timeline
6166

‎framework/framework_commons/docs/dev/FrameworkCommons.asciidoc‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,82 @@ endif::[]
1515
footnote:[asciidoc source of this page: https://github.com/eclipse/gemoc-studio-modeldebugging/tree/master/execution_framework/xdsml_framework/docs/dev/FrameworkCommons.asciidoc.]
1616

1717

18+
List of plugins:
19+
20+
- `org.eclipse.gemoc.executionframework.reflectivetrace.model`:
21+
- `org.eclipse.gemoc.opsemanticsview.gen`:
22+
- `org.eclipse.gemoc.opsemanticsview.gen.k3` :
23+
- `org.eclipse.gemoc.opsemanticsview.model` :
24+
- `org.eclipse.gemoc.ws.server` :
25+
- `org.eclipse.gemoc.xdsmlframework.api` :
26+
- `org.eclipse.gemoc.xdsmlframework.commons` :
27+
- `org.eclipse.gemoc.xdsmlframework.commons.ui.k3` :
28+
29+
[[devguide-frameworkcommons-ws-server]]
30+
==== Websocket server
31+
32+
The `org.eclipse.gemoc.ws.server` plugin offers services to add websocket endpoints in an Eclipse application (with UI or headless).
33+
34+
35+
The plugin starts a websocket server on a free port of the system. It uses Jetty as server.
36+
37+
It defines an extension point to define websocket endpoint so any other plugin can contribute their endpoint.
38+
39+
40+
Example of use declaring a test endpoint:
41+
42+
In your `plugin.xml:`
43+
[source,xml]
44+
----
45+
<extension point="org.eclipse.gemoc.ws.server.endpoint">
46+
<GEMOC_WS_EndPoint
47+
class="org.example.endpoint.TestEndPoint" <1>
48+
id="org.example.TestEndPoint">
49+
</GEMOC_WS_EndPoint>
50+
</extension>
51+
----
52+
<1> Name of the class implementing JSR 356 `javax.websocket.server.ServerEndpoint`.
53+
54+
Class implementing the endpoint.
55+
[source,java]
56+
----
57+
package org.example.endpoint;
58+
59+
import javax.websocket.OnMessage;
60+
import javax.websocket.server.ServerEndpoint;
61+
62+
@ServerEndpoint("/test") <1>
63+
public class TestEndPoint {
64+
65+
@OnMessage
66+
public void handleOnMessage(String message) {
67+
System.out.println("Message received by WebSocket : "+message); <2>
68+
}
69+
}
70+
----
71+
<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` )
72+
<2> behavior when receiving message on this endpoint.
73+
74+
75+
On start, the server look for an available port (this is displayed on the console).
76+
77+
78+
[TIP]
79+
====
80+
An example of plugin using the `org.eclipse.gemoc.ws.server` in GEMOC Studio (available in the IDE and headless application) is https://github.com/eclipse/gemoc-studio-modeldebugging/tree/master/framework/execution_framework/plugins/org.eclipse.gemoc.executionframework.addon.eaop.server[org.eclipse.gemoc.executionframework.addon.eaop.server].
81+
====
82+
83+
84+
[NOTE]
85+
====
86+
The websocket server is started only when the `org.eclipse.gemoc.ws.server` plugin starts,
87+
you may either need to add it to the OSGI start or wait for another plugin to use it.
88+
====
89+
90+
91+
==== Framework Commons XDSLMFramework
92+
93+
1894
<<img-FrameworkCommons-overview-CD-devguide>> shows some of the major interfaces of the execution framework API.
1995
Most notably, the _IEngineAddon_ and _IExecutionEngine_ interfaces that are the entry points when implementing an Addon for GEMOC.
2096

@@ -26,3 +102,5 @@ image::images/dev/frameworkcommons_api_overview_CD.png["Execution Framework API
26102

27103
TIP: The section <<dev-new-addons>> contains some details and code snippets about how to write an engine addon.
28104

105+
106+

‎protocols/engine_addon_protocol/docs/EngineAddonProtocol.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ The figure <<img-EAOP-CD-devguide>> presents the Client and Server JSON RPC met
1919

2020
[[img-EAOP-CD-devguide]]
2121
.Engine Add-On Protocol overview
22-
image::images/EngineAddonProtocol.png["EngineAddonProtocol"]
22+
image::images/EngineAddonProtocol.png[EngineAddonProtocol, 1024]
2323

2424

2525

‎protocols/generators/docs/ProtocolGenerators.asciidoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
////////////////////////////////////////////////////////////////
2+
// Reproduce title only if not included in master documentation
3+
////////////////////////////////////////////////////////////////
4+
ifndef::includedInMaster[]
5+
6+
= Developer Guide
7+
== Protocols
8+
9+
endif::[]
10+
11+
=== Protocol generators
12+
13+
footnote:[asciidoc source of this page: https://github.com/eclipse/gemoc-studio-modeldebugging/tree/master/protocols/generators/docs/ProtocolGenerators.asciidoc.]
14+
15+
GEMOC provides a basic generator in order to consistently create protocol implementations using LSP like approach.
16+
17+
[NOTE]
18+
====
19+
The current generator primarily targets websocket endpoints, but the generated classes are probabl generic enough to be used in other context.
20+
21+
====
22+
23+
24+
=== JSONSchema2APIProtocolGenerator
25+
26+
`JSONSchema2APIProtocolGenerator` allows to generate several interfaces, implementations and documentation artifacts from a JSON schema representing the protocol message specification.
27+
28+
The current version of `JSONSchema2APIProtocolGenerator` is written in typescript.
29+
30+
Inputs :
31+
It uses a file `generator_config.json` to drive the generations and output directories.
32+
`generator_config.json` defines some parameters such as
33+
34+
* *protocolJSONSchemaPath* : path to the JSON schema representing the protocol messages
35+
36+
37+
Currently supported output:
38+
39+
* *plantuml* : a graphical representation of the protocol
40+
* *tsAPI* : a typescript implementation of the API (Work In Progress, please contribute )
41+
* *javaAPI* : a java implementation of the API and the DTO (data transfert object), actually generated using xTend and using `org.eclipse.lsp4j.jsonrpc` library.
42+
* *javaServer* : a java interface of this protocol server
43+
* *javaClient* : a java interface of this protocol client
44+
45+
46+
47+
48+
49+
50+

0 commit comments

Comments
 (0)