Skip to content
This repository was archived by the owner on Jun 16, 2021. It is now read-only.

Latest commit

 

History

History
194 lines (146 loc) · 8.15 KB

design-doc.md

File metadata and controls

194 lines (146 loc) · 8.15 KB

Design Document

What is a design document?

Context and Scope

Ecore is a meta model inside the Eclipse Modeling Framework (EMF). This meta model is used by developers to create domain models when practising Model-Driven Software Engineering (MDSE). An Ecore model can be visualized as a diagram similar to UML (like EcoreTools/Sirius), as a tree stucture or a raw XML-like file.

For editing Ecore in Theia, we already have the ecore-glsp. However, this is only a graph editor. Another common way of editing Ecore is through a tree view + properties panel.

This project aims to implement a tree view editor for Ecore in Theia, and bundle as a VSCode extension (.vsix) that is installable in Gitpods.

Reference implementations

Inspiration and guidance is drawn from the Eclipse implementations: Ecore Model Editor and the Sample Reflective Ecore Model Editor.

Ecore model Editor

Sample Reflective Ecore Model Editor

Note that the Sample Reflective Ecore Model Editor can also edit model instances (xmi-files) and run OCL validations:

Sample Reflective Ecore Model Editor with a model instance xmi open

Goals and non-goals

  • Visualize Ecore models as trees
    • Package, datatype, class, attribute, annotation and annotation-values as nodes
    • Labels: name, icon, datatype
  • Add and remove nodes in the tree
  • Property sheet editor. Master-detail where tree=master and property=detail.
  • Both meta-model (Ecore) and model instance (xmi)
  • Automatically update when underlying model changes (push not poll)

Non-goal: Things that could be goals, but we chose not to do them.

Most of these are non-goals due to time constraints, and could be in-scope for a finalized product.

Non-goals:

  • Lazy load children for large models
  • Handle dependencies to other models
  • Drag-n-drop nodes
  • Editable names in tree
  • Custom labels (e.g. via OCL) for model instances (xmi)
  • Customizable icons for model instances (xmi)
  • OCL constraint validation for model instances (xmi)
  • Live OCL evaluator for writing queries

Design and trade-offs

It will be a VSCode extension project in Typescript. Using the VSCode extension API you can install the extension during runtime into a Theia instance. This is possibly needed for Gitpods (assumption). A trade-off is that using Theia Extensions, you get full control. Here we are restricted to VSCode API and what subset of it Theia supports.

Using a VSCode extension, the text editor is limited to text. Thus we have to rely on a Custom Editor API to create arbitrary layouts. (An alternative is WebView , but I don't know which API Theia will support first). The Custom Editor API is essentially WebView+Document APIs. These WebViews have special requirements for serializing state, and restrictions for where they can load resources.

CustomTextEditorProvider or CustomEditorProvider? A CustomEditorProvider may be best. A text based editor gets a document model for free, and related functionality like saving. If a tree can easily map to text editing, this could be beneficial. However, most changes to the document would not be performed by the editor, but the model server. The editor is mostly a model observer and change-command dispatcher; not an editor itself.

System-context-diagram

@startuml
mainframe Deployment diagram

node openVsx {
  artifact "ecore-tree-editor.vsix"
}

node gitpods {
  node dockerContainer {
    [TheiaBackend]
    artifact TheiaFrontendSrc
    artifact "Ecore user project" as workspace
  }

  artifact projectDockerImage

  dockerContainer -> projectDockerImage: runs
}

node github {
  artifact "Ecore user project repo" as repo
}

[TheiaBackend] --> openVsx : "install plugin from"
workspace --> repo : clone

@enduml
@startuml
mainframe Component diagram

node browser {
  [TheiaFrontend]
  [<<CustomEditor>>\nTree editor] as TreeEditor
  TreeEditor <- TheiaFrontend: Tree state
  TreeEditor -> TheiaFrontend: Tree change command
}
node backend {
  [TheiaBackend]
  [<<extension>>\necore-tree-editor] as plugin
  [Tree Language Server] as bundledProcess
  [<<Java>>\nEMF.Cloud Model Server] as modelServer
}

[TheiaFrontend] <--> [TheiaBackend]: json-rpc
[TheiaBackend] -> [plugin]: (de)activate
[plugin] <-- [TheiaBackend]: User actions
[plugin] --> [TheiaBackend]: New Tree state
[plugin] <-> [bundledProcess]: stdio
[plugin] -> [bundledProcess]: start/stop
[bundledProcess] -> [modelServer]: <<websocket>>\nsubscribe changes
[bundledProcess] -> [modelServer]: <<http>>\nmodel REST API

@enduml
@startuml
mainframe Interactions

[Theia]
[<<CustomEditor>>\nTree Editor] as TreeEditor
[<<extension>>\necore-tree-editor] as plugin
[Tree Language Server] as bundledProcess
artifact "Ecore user project"
[<<Java>>\nEMF.Cloud Model Server] as modelServer
actor user

user .> [Ecore user project]: develops
user -> [Theia]: uses
user -> TreeEditor: uses
TreeEditor <- Theia: hosts
TreeEditor <.. plugin: bundles
[Theia] -> [Ecore user project]: workspace
[Ecore user project] <-- modelServer: operates on
bundledProcess -> modelServer: queries
bundledProcess <- modelServer: notifies
[Theia] <--> plugin: instructs
plugin <-> bundledProcess: commands
@enduml

Degree of constraint

The project must work in Theia inside Gitpods. Gitpods is the ultimate target. However, when is an important question. Within 2 years from Jan/20201 is reasonable. This timeframe allows for Theia to (maybe) support the CustomEditor or WebView VSCode APIs.

It should be an VSCode extension, but if Gitpods can load Theia Extensions, this constraint falls.

It may use EMF.Cloud's EMF Model Server if this simplifies model parsing or enhances tool/extension interoperability/cooperation among other extensions.

It should use Theia Tree View if this is possible to use in a VSCode extension. (Seems to not be possible. It depends on Theia core and uses Theia Extension API).

It should use JSON Forms for the detail view. This supports React and Angular.

Alternatives considered