To build a new data catalog from scratch, we first have to understand some basics about Eclipse, and then install the correct Eclipse package and add some plug-ins to it.
Thereafter, we can model our data with Ecore considering some best practices, followed by the generation of Java classes and user interface (UI).
Some hints on versioning data catalogs conclude this how-to-section.
=== Eclipse Basics
https://en.wikipedia.org/wiki/Eclipse_(software)[Eclipse] was originally developed by IBM and became Open Source in 2001.
It is best known for its Integrated Development Environments (_Eclipse IDEs_), not only for Java, but also for C++, Python and many other programming languages.
These IDEs are created on top of the Eclipse Rich Client Platform (Eclipse RCP), an application framework and plug-in system based on Java and OSGi.
Eclipse RCP is foundation of a plethora of general-purpose applications, too.
First time users of Eclipse better understand the following concepts.
.Eclipse Packages
An Eclipse package is an Eclipse distribution dedicated to a specific type of task.footnote:[The notion of an Eclipse package has nothing to do with Java packages.]
A list of packages is available at https://www.eclipse.org/downloads/packages/[eclipse.org].
Beside others it contains _Eclipse IDE for Java Developers_, _Eclipse IDE for Scientific Computing_, and the package we will use: _Eclipse Modeling Tools_.
Note that third parties offer many other packages, e.g. _GAMA_ for multi-agent-simulation or _Obeo Designer Community_ for creating Sirius diagram editors, both noted above.
[NOTE]
====
Several Eclipse packages can be installed side by side, even different releases of the same package. Multiple Eclipse installations can run at the same time, each on its own workspace (see below).
====
.Plug-ins / Features
An installed Eclipse package consists of a runtime core and a bunch of additional plug-ins.
Technically, a plug-in is just a special kind of Java archive (JAR) that uses and can be used by other plug-ins with regard to OSGi specifications.
Groups of plug-ins that belong together are called a _feature_.
Often, a user will add further plug-ins or features to an Eclipse installation to add new capabilities.
E.g. writing this documentation within my Eclipse IDE is facilitated by the plug-in https://marketplace.eclipse.org/content/asciidoctor-editor[Asciidoctor Editor].
Plug-ins can easily be installed via main menu command `Help → Eclipse Marketplace...`. Some plug-ins may be self-made like our plug-in `de.hftstuttgart.units` that enables Ecore to deal with quantities.
These may be provided via _Git_ or as download and have to be added to an Eclipse installation manually.
.Git
Today https://git-scm.com[Git] is the industry standard for collaborative work on, and versioning of, source code and any other kind of textual data. Collaborative development of data catalogs benefits massively from using Git, and Git support is built into _Eclipse Modeling Tools_, the Eclipse package we will use.
However, if Eclipse needs to connect to a Git server that uses SSH protocol (not HTTPS with password), access configuration is more involved and may be dependent on your operating system.
Some users, anyway, prefer to use Git from the command line or with on of the client application listed https://git-scm.com/downloads/guis[here], e.g. https://tortoisegit.org[TortoiseGit] for Windows.
While it is required to get Git working at some point, we won't refer to it in this document and, for now, do not cover the installation of Git on your machine or configuration of Git in Eclipse.
.Workspaces
When you start a new Eclipse installation for the first time, you are asked to designate a new directory in your file system to store an _Eclipse workspace_.
Eclipse is always running with exact one workspace open.
As the name implies, a workspace stores everything needed in a given context of work, that is a set of related projects the user is working on as well as meta-data like preference settings, the current status of projects, to do lists, and more. In case a user wants to work in different contexts, e.g. on different tasks, command `File -> Switch Workspace` allows to create additional workspaces and switch between them.
[NOTE]
====
Any plug-in from the original Eclipse package or installed by the user later will be copied into the Eclipse installation directory, *not* in any workspace. Configuration and current state of plug-ins, on the other hand, are stored in workspaces.
====
.Projects
An Eclipse project is a technical term for a directory that often contains:
* files of specific types for source code, scripts, XML files or other data
* build settings, configurations
* dependency definitions (remember the dependencies between plug-ins above?)
* other Eclipse projects
Depending on the plug-ins installed, `File -> New -> Project...` offers many different types of projects that the user can choose from, e.g. Java projects to create Java programs, model projects to work with Ecore data models, or general projects, that simple hold some arbitrary files.footnote:[Projects possess one or more _natures_ used to define a project's principal type.]
[WARNING]
====
Files that do not belong to a project are invisible for Eclipse!
====
The projects belonging to a workspace can either be directly stored within the workspace as sub-directories (the default offered to the user when creating a new project), or linked from it, that is the workspace just holds a link to the project directory that lives somewhere in the file system outside of the workspace.
Linking allows to work with the same projects in different workspaces.
While it sometimes makes sense to share or exchange workspaces between users,footnote:[Or even work on the same workspace provided in the cloud, see https://www.eclipse.org/che/technology/[Eclipse Che].], I do not recommend this for now.
Projects, on the other hand, are shared between users most of the time, usually via Git.
In general, I would suggest to store Eclipse projects outside workspaces at dedicated locations in the user's file system.
That way, we can follow the convention that local Git repositories should all be located under
`<userhome>/git`.
=== Setup Eclipse Modeling Tools
.Install Java
As a Java application, Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires a 64-bit Java runtime, version 1.8 (aka version 8) or higher, to be installed on your machine.
If not already there, download the latest version of OpenJDK (currently 14) for your operating system from https://adoptopenjdk.net[AdoptOpenJDK].footnote:[AdoptOpenJDK recently joined the Eclipse founation and soon will change its name to _Adoptium_ for legal reasons.]
Choose `HotSpot` as Java Virtual Machine.
Installation process is straight forward, but you can also find links to exhaustive instructions for your operating system. Note that different versions of Java can peacefully coexist.
.Install Eclipse Modeling Tools
Now its time to download and install the correct Eclipse package.
Please go to https://www.eclipse.org/downloads/packages[Eclipse download page for packages].
On top of this page you may see _"Try the Eclipse Installer"_ or similar.
We won't follow this advice, since it is not suited for our use-case. We won't either download the most recent package because releases after `2019-12` come with a bug that prevents the user from editing data in table cells within the generated UI.
[CAUTION]
.Download version 2019-12 (4.14) only!
====
Due to a bug in recent versions, make sure not to download the actual version, but the older version 2019-12 (4.14)!
====
To do so, click the link depicted by the red arrow below.
.Eclipse packages download page with links to older releases
A similar download page for all the packages appears but this time for version `2019-12`. Now look for package _Eclipse Modeling Tools_ and follow the link of your operating system on the right:
.Download links for Eclipse Modeling Tools package
Finally, you can click on `Download` and wait for the 400 something MB package to arrive.
[NOTE]
====
Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Eclipse.
====
The downloaded installation file contains the application simply named `Eclipse` ready to be copied into `Applications` on macOS or be installed in `Programs` on Windows.
Since you may add other Eclipse packages later, I suggest to rename the application to something more significant like `EclipseModeling`.
After installation has finished launch Eclipse for the first time and see the dialog for choosing a new empty directory as its workspace pop up.
Again, more workspaces might come into existence later, so replace the proposed generic directory name with a more specific one, e.g.`EclipseModelingWS`.
The Eclipse main window appears with a Welcome Screen open.
It contains links to exhaustive documentation on concept, features and usage of Eclipse that might be of interest later, especially:
For now, you can dismiss the welcome screen. It can be opened anytime by executing `Help -> Welcome`
.Add Support for Units and Quantities
As mentioned before, data catalogs for simulations should be able to represent quantities, not just bare integer and real numbers.
To this end, the author has created two Eclipse plug-in projects providing this feature to be used by Ecore and EMF Forms later.
Currently, the projects are not distributed as plug-ins.
Instead, we compile them from source code, simply by importing the projects.
These two projects will be the first to populate the yet empty workspace:
. Copy to file system ...
. Import project but *not* copying it in the workspace (just linking)
Text
=== Modeling Data Catalogs for Simulation with Ecore
Now domain experts can start modeling the data that the projected catalog shall contain.
Except ... understanding the basics of object-oriented modeling would be helpful.
This is why developers should support domain experts at this stage.
.Model Data with Class Diagrams
We will use Ecore diagramsfor data modeling below.
Ecore diagrams are simplified UML class diagrams.
Here some resources about what this is all about:
* http://www.cs.toronto.edu/~sme/CSC340F/slides/11-objects.pdf[Toronto Lecture on Object Oriented Modeling]
* http://agilemodeling.com/artifacts/classDiagram.htm[UML 2 Class Diagrams: An Agile Introduction]
* https://www.amazon.de/UML-Classroom-Einführung-objektorientierte-Modellierung-ebook/dp/B00AIBE1QA/ref=sr_1_2?__mk_de_DE=ÅMÅŽÕÑ&dchild=1&keywords=UML&qid=1585854599&sr=8-2[UML @ Classroom: Eine Einführung in die objektorientierte Modellierung (German Book)]
[TIP]
====
Beginners are strongly encouraged to read the first two resources. The first one contains a gentle introduction, especially suited for domain experts. The second one also serves as a reference.
====
In what follows, a principle understanding of concepts _Class_, _Object_, _Attribute_, _Association_, _Composition_, and _Multiplicity_ is taken for granted.
Note that the sources above differenciate between conceptual and detailed models. While the first work very well on a white board, the latter can be used for code generation.
.Principle Structure
<Use PlantUML?>
Hierarchic, main catalog with several lists of objects of the same type using attributes, primitive types, references and enums
Ids?
.Add Units to the Mix
using Indrya, the reference implementation for Units of Measurement in Java (JSR 385)
.Represent (Parameterized) Functions:
Text
.Derived References and Attributes
There are no derived references or attributes by now. But if one has to implement some by providing a getter, it is necessary to return an unmodifiable list like BasicEList.UnmodifiableEList or EcoreUtil.unmodifiableList(...) instead of EList as described here: https://www.ntnu.no/wiki/plugins/servlet/mobile?contentId=112269388#content/view/112269388 .
=== Generation of Java code and persistence layer
Custom code marked with `@generated NOT` in `de.hftstuttgart.energycomponents.provider` in project `de.hftstuttgart.energycomponents.edit`
