Skip to content

GitLab

Commit 0fe05b5e authored by Kai-Holger Brassel's avatar Kai-Holger Brassel
Browse files

Update documentation 

* replace Obeo Designer by Eclipse Modeling Tools
* update to Java 17 and Eclipse 2021-12
* move PDF from git to Kai's web page
parent 8833138c
Pipeline #5731 passed with stage
Hide whitespace changes
Inline Side-by-side
.gitlab-ci.yml
View file @ 0fe05b5e
......@@ -3,7 +3,6 @@ pages:
script:
- mkdir .public
- cp -r ParameterCatalogs2Images .public
- cp ParameterCatalogs.pdf .public
- cp UnitsExamples.md .public
- cp ParameterCatalogs.html .public/index.html
- mv .public public
......
ParameterCatalogs.adoc
View file @ 0fe05b5e
......@@ -10,9 +10,9 @@ image:https://mirrors.creativecommons.org/presskit/icons/by.svg[by,20]
image:https://mirrors.creativecommons.org/presskit/icons/nc.svg[nc,20]
image:https://mirrors.creativecommons.org/presskit/icons/nd.svg[nd,20]
Non-final version: September 7^st^, 2021.
Non-final version: January 31, 2022.
Go to link:ParameterCatalogs.pdf[PDF-Version as of September 7^th^, 2021]
Go to link:https://www.khbrassel.de/parametercatalogs/ParameterCatalogs.pdf[PDF-Version as of January 31, 2022]
include::ParameterCatalogs1Overview.adoc[]
......
ParameterCatalogs.html
View file @ 0fe05b5e
......@@ -456,7 +456,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
<li><a href="#truehow-to-implement-parameter-catalogs-with-eclipse">How to Implement Parameter Catalogs with Eclipse</a>
<ul class="sectlevel2">
<li><a href="#trueeclipse-basics">Eclipse Basics</a></li>
<li><a href="#truesetup-obeo-designer">Setup Obeo Designer</a></li>
<li><a href="#truesetup-eclipse-modeling-tools">Setup Eclipse Modeling Tools</a></li>
<li><a href="#trueexercise-modeling-a-parameter-catalog-with-ecore">Exercise: Modeling a Parameter Catalog with Ecore</a></li>
<li><a href="#truemaking-an-application-to-create-and-edit-data">Making an Application to Create and Edit Data</a></li>
<li><a href="#trueworking-with-git-hosted-parameter-catalogs">Working with Git Hosted Parameter Catalogs</a></li>
......@@ -492,10 +492,10 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
<span class="image"><img src="https://mirrors.creativecommons.org/presskit/icons/nd.svg" alt="nd" width="20"></span></p>
</div>
<div class="paragraph">
<p>Non-final version: September 7<sup>st</sup>, 2021.</p>
<p>Non-final version: January 31, 2022.</p>
</div>
<div class="paragraph">
<p>Go to <a href="ParameterCatalogs.pdf">PDF-Version as of September 7<sup>th</sup>, 2021</a></p>
<p>Go to <a href="https://www.khbrassel.de/parametercatalogs/ParameterCatalogs.pdf">PDF-Version as of January 31, 2022</a></p>
</div>
</div>
</div>
......@@ -951,43 +951,41 @@ That way, we can follow the convention that local Git repositories should all be
</div>
</div>
<div class="sect2">
<h3 id="truesetup-obeo-designer"><a class="anchor" href="#truesetup-obeo-designer"></a>Setup Obeo Designer</h3>
<h3 id="truesetup-eclipse-modeling-tools"><a class="anchor" href="#truesetup-eclipse-modeling-tools"></a>Setup Eclipse Modeling Tools</h3>
<div class="paragraph">
<div class="title">Install Java</div>
<p>Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 11 or higher, to be installed on your machine.
Even if such JDK is already installed on your machine, please download the OpenJDK version <strong>16</strong> or newer for your operating system from <a href="https://adoptium.net">Adoptium</a>.
<p>Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 17 or higher, to be installed on your machine.
Even if such JDK is already installed on your machine, please download the JDK version <strong>17</strong> for your operating system from <a href="https://adoptium.net">Adoptium</a>.
Installation process is straight forward, but you can also find links to exhaustive instructions for your operating system.</p>
</div>
<div class="paragraph">
<p>New Java versions appear every six months, so one could tend to stick with older version 11 that comes with long time support (LTE) until next LTE version 17 arrives in autumn 2021.
However, actual version 16 conforms to the latest security measures built into macOS Catalina, so it is a must if software we build here shall be deployed to these systems, too.</p>
<p>New Java versions appear every six months, but we will stick for the coming years with version 17, since it comes with long time support (LTS).</p>
</div>
<div class="paragraph">
<p>Note that different versions of Java coexist peacefully.</p>
</div>
<div class="paragraph">
<div class="title">Install Obeo Designer, Community Edition</div>
<p>Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of <a href="https://www.obeodesigner.com/en/product/sirius">Eclipse Sirius</a>.
Technically, the Eclipse Sirius project provides a set of open source features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.
Instead of adding these software components manually, we start with a pre-configured Eclipse package named <em>Obeo Designer</em>.
Please download and install the latest version (11.5 at the time of writing) available at <a href="https://www.obeodesigner.com/en/download">Download Obeo Designer Community</a>.</p>
<div class="title">Install Eclipse Modeling Tools</div>
<p>Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of Eclipse Sirius, an open source framework that provides a set of features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Obeo Designer.</p>
<p>In the past, we used the pre-configured Eclipse package <em>Obeo Designer Community</em> from <a href="https://www.obeodesigner.com">Obeo</a>, but it wasn&#8217;t updated for a while and, thus, is stucked at Java version 14.</p>
</div>
</td>
</tr>
</table>
<div class="paragraph">
<p>Instead, we install the Eclipse package <em>Eclipse Modeling Tools</em> first and, then, Eclipse Sirius on top. To get current version 4.22 (2021‑12) of <em>Eclipse Modeling Tools</em>, go to <a href="https://www.eclipse.org/downloads/packages/">www.eclipse.org/downloads/packages/</a>.
On this page you may see <em>"Try the Eclipse Installer"</em> or similar.
Do <strong>not</strong> follow this advice, since we want more control over what versions of Java and Eclipse shall be installed.
Instead, look for package <em>Eclipse Modeling Tools</em> and follow the link for your operating system and system architecture displayed on the right:</p>
</div>
<div class="imageblock thumb">
<div class="content">
<img src="ParameterCatalogs2Images/EclipseDownload.gif" alt="EclipseDownload" width="500">
</div>
<div class="title">Figure 1. Download links for Eclipse Modeling Tools package</div>
</div>
<div class="paragraph">
<p>After the 400 something MB package has arrived, unzip the downloaded file and move the resulting application named <code>ObeoDesigner-Community</code> to a suited directory. This would be <code>Applications</code> on macOS, similar on Linux, but <strong>not</strong> <code>Programs</code> or <code>Programs (x86)</code> on Windows!</p>
<p>Finally, click on <code>Download</code> and wait for the 450 something MB package to arrive.
Unzip the downloaded file and possibly rename the resulting application <code>Eclipse</code> to something more specific like <code>EclipseModeling2112</code>. Then, move the application to a suited directory. This would be <code>Applications</code> on macOS, similar on Linux, but <strong>not</strong> <code>Programs</code> or <code>Programs (x86)</code> on Windows!</p>
</div>
<div class="admonitionblock warning">
<table>
......@@ -997,52 +995,39 @@ Please download and install the latest version (11.5 at the time of writing) ava
</td>
<td class="content">
<div class="paragraph">
<p><strong>Special installation note for Windows</strong>: We found that no plug-ins can be added to Obeo Designer, <strong>if</strong> it is installed in folder <em>Programs</em> or <em>Programs (x86)</em>. Since we have to add plug-ins for handling units and quantities below, please make sure to unzip the installation package elsewhere, e.g. the Desktop or the user&#8217;s home directory.</p>
<p><strong>Special installation note for Windows</strong>: We found that sometimes plug-ins cannot be added to Eclipse, <strong>if</strong> it is installed in folder <em>Programs</em> or <em>Programs (x86)</em>. Since we have to add plug-ins for Sirius and for handling units and quantities below, please make sure to unzip the installation package elsewhere, e.g. the Desktop or the user&#8217;s home directory.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p><strong>Special installation note for macOS</strong>: As Obeo Designer currently is not code-signed, macOS consideres it as damaged. To work around this security feature, remove the quarantine status of the program like so:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Open a terminal in the folder containing the .app file</p>
</li>
<li>
<p>Execute: xattr -d com.apple.quarantine ObeoDesigner-Community.app</p>
</li>
<li>
<p>Double click the app to start.</p>
</li>
</ol>
<p>Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Eclipse Modeling Tools.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>After installation has finished launch the application for the first time and you will see a dialog for choosing a new empty directory as its workspace.</p>
<p>After installation has finished, launch the application for the first time and you will see a dialog for choosing a new empty directory as its workspace.</p>
</div>
<div class="imageblock thumb">
<div class="content">
<img src="ParameterCatalogs2Images/SelectWorkspaceDirectory.gif" alt="SelectWorkspaceDirectory" width="500">
</div>
<div class="title">Figure 1. Initial Dialog to Choose a Workspace Directory</div>
<div class="title">Figure 2. Initial Dialog to Choose a Workspace Directory</div>
</div>
<div class="paragraph">
<p>More workspaces might come into existence later, so replace the proposed generic directory path and name with a more specific one, e.g.<code>ObeoDesignerWS</code>.
<p>More workspaces might come into existence later, so replace the proposed generic directory path and name with a more specific one, e.g.<code>EclipseWSCatalogs</code>.
The main window appears with a Welcome Screen open.
Especially under <code>Documentation</code> you will find exhaustive documentation on Eclipse that might be of interest later, e.g.:</p>
Especially under <code>Workbench Basics</code> you will find exhaustive documentation on Eclipse that might be of interest later, e.g.:</p>
</div>
<div class="ulist">
<ul>
......@@ -1064,16 +1049,16 @@ Especially under <code>Documentation</code> you will find exhaustive documentati
<div class="ulist">
<ul>
<li>
<p>Git for Eclipse Users</p>
<p>EGit User Guide</p>
</li>
<li>
<p>EGit User Guide</p>
<p>Git for Eclipse Users</p>
</li>
</ul>
</div>
</li>
<li>
<p>Ecore Tools User Manual: Learn how to use the Ecore diagram editor.</p>
<p>Ecore Tools User Manual: Learn how to design Ecore models.</p>
</li>
</ul>
</div>
......@@ -1083,6 +1068,35 @@ Especially under <code>Documentation</code> you will find exhaustive documentati
<div class="paragraph">
<p>Now you should see the initial window layout with <em>Model Explorer</em> and <em>Outline</em> on the left and a big empty editing area to the right with a <em>Properties</em> view below.</p>
</div>
<div class="paragraph">
<div class="title">Install Eclipse Sirius</div>
<p>While package <em>Eclipse Modeling Tools</em> already contains Sirius features that let you create graphical Ecore models, features for specifying your own forms and graphical editors are still missing. You can add these features easily from <em>Eclipse Marketplace</em>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Open dialog <code>Help &#8594; Eclipse Marketplace&#8230;&#8203;</code> and type <em>Search</em> into the search field</p>
</li>
<li>
<p>Look for Sirius 6.6 or newer in the list of results and click <code>Install</code></p>
</li>
<li>
<p>From the list of features choose <code>Sirius Specifier Environment</code> and <code>Sirius Support for AQL</code> for installation and unchoose the others (see screen shot)</p>
</li>
<li>
<p>Confirm your choice, acknowlege any licenses, and restart Eclipse when asked for.</p>
</li>
</ul>
</div>
<div class="imageblock thumb">
<div class="content">
<img src="ParameterCatalogs2Images/InstallSirius.png" alt="InstallSirius" width="500">
</div>
<div class="title">Figure 3. Download links for Eclipse Modeling Tools package</div>
</div>
<div class="paragraph">
<p>Above steps added commonly used software components to your Eclipse application, publicly available in the <em>Eclipse Marketplace</em>. In the next section, however, you will add features that were created specifically for parameter catalogs and hosted at the transfer portal of <em>HfT Stuttgart</em>.</p>
</div>
<div id="quantity-plug-ins" class="paragraph">
<div class="title">Add Plug-ins to deal with Quantities and Units</div>
<p>Parameter catalogs should be able to represent quantities, not just bare numbers.
......@@ -1099,7 +1113,7 @@ The reference implementation for this framework is <a href="https://unitsofmeasu
<div class="content">
<img src="ParameterCatalogs2Images/AddUpdateSite.png" alt="Install Plug-in" width="500">
</div>
<div class="title">Figure 2. Install Plug-in from Specific Update Site</div>
<div class="title">Figure 4. Install Plug-in from Specific Update Site</div>
</div>
<div class="paragraph">
<p>Select Indriya plug-in, press <code>Next &gt;</code> and acknowledge all following dialogs, including security warnings.</p>
......@@ -1111,9 +1125,6 @@ Finally, restart Eclipse to complete plug-in installation.</p>
<div class="paragraph">
<p>While the first plug-in installs Indriya, the second plug-in adds some specific units for urban simulation and Ecore types used for modeling quantities as attributes of classes.</p>
</div>
<div class="paragraph">
<p>Now you should see the initial layout of Eclipse with <em>Model Explorer</em> and <em>Outline</em> on the left and a big empty editing area to the right with a <em>Properties</em> view below.</p>
</div>
</div>
<div class="sect2">
<h3 id="trueexercise-modeling-a-parameter-catalog-with-ecore"><a class="anchor" href="#trueexercise-modeling-a-parameter-catalog-with-ecore"></a>Exercise: Modeling a Parameter Catalog with Ecore</h3>
......@@ -1237,7 +1248,7 @@ The <em>Model Explorer</em> shows the contents of the new Ecore modeling project
<div class="content">
<img src="ParameterCatalogs2Images/DemoCatalogEmpty.png" alt="DemoCatalogEmpty">
</div>
<div class="title">Figure 3. New Ecore Modeling Project</div>
<div class="title">Figure 5. New Ecore Modeling Project</div>
</div>
<div class="paragraph">
<p>To get your feet wet, do this:</p>
......@@ -1326,7 +1337,7 @@ Instead of artificial example classes like <em>Foo</em> and <em>Bar</em> it show
<div class="content">
<img src="ParameterCatalogs2Images/CatalogStructure.png" alt="CatalogStructure">
</div>
<div class="title">Figure 4. Principle Structure of a Parameter Catalog</div>
<div class="title">Figure 6. Principle Structure of a Parameter Catalog</div>
</div>
<div class="paragraph">
<p>The diagram models four types of technical components whose data shall be stored in the catalog, e.g. for parameterization of simulation models later: <em>Boiler</em>, <em>CombinedHeatPower</em>, <em>SolarPanel</em>, and <em>Inverter</em>.</p>
......@@ -1453,7 +1464,7 @@ These are <em>multiplicities</em> of associations: An <code>EnergyComponentsCata
<div class="content">
<img src="ParameterCatalogs2Images/EcoreRelations.gif" alt="EcoreRelations" width="200">
</div>
<div class="title">Figure 5. Ecore Relations</div>
<div class="title">Figure 7. Ecore Relations</div>
</div>
<div class="paragraph">
<p>To recapitulate: Our example parameter catalog already exhibits all four types of relations provided by Ecore.
......@@ -1492,7 +1503,7 @@ To get rid of the error:</p>
<div class="content">
<img src="ParameterCatalogs2Images/EcoreClassWithAttribute.png" alt="EcoreClassWithAttribute" width="200">
</div>
<div class="title">Figure 6. Class with Attribute</div>
<div class="title">Figure 8. Class with Attribute</div>
</div>
<div class="paragraph">
<p>Change the attribute&#8217;s name to <code>author</code> and the class should look like shown here.</p>
......@@ -1521,7 +1532,7 @@ In our example data model you&#8217;ll find one <em>Enumeration</em> named <code
<div class="content">
<img src="ParameterCatalogs2Images/EcoreClassifier.png" alt="EcoreClassifier" width="200">
</div>
<div class="title">Figure 7. Abstract Class</div>
<div class="title">Figure 9. Abstract Class</div>
</div>
<div class="paragraph">
<p>To do this, there is one more thing to know about classes: the difference between ordinary classes and abstract classes.
......@@ -1583,7 +1594,7 @@ Note that Eclipse synchronizes different editors of the same content automatical
<div class="content">
<img src="ParameterCatalogs2Images/Homework.png" alt="Homework">
</div>
<div class="title">Figure 8. Example Model (Homework)</div>
<div class="title">Figure 10. Example Model (Homework)</div>
</div>
</div>
<div class="sect2">
......@@ -1617,7 +1628,7 @@ Note that Eclipse synchronizes different editors of the same content automatical
<div class="content">
<img src="ParameterCatalogs2Images/GeneratedClasses.png" alt="GeneratedClasses" width="260">
</div>
<div class="title">Figure 9. Generated Classes</div>
<div class="title">Figure 11. Generated Classes</div>
</div>
<div class="paragraph">
<p><code>Generate &#8594; All</code> creates classes that represent the modeled data in code at first. These classes are located in three packages under directory <code>src-gen</code> in <code>org.example.democatalog.model</code>. Then, the command generates <code>Edit Code</code> and <code>Editor Code</code> within two new Eclipse projects named <code>org.example.democatalog.edit</code> and <code>org.example.democatalog.editor</code>, again with generated classes in <code>src-gen</code>.</p>
......@@ -1635,7 +1646,7 @@ Note that Eclipse synchronizes different editors of the same content automatical
<div class="content">
<img src="ParameterCatalogs2Images/Warnings.gif" alt="Warnings" width="500">
</div>
<div class="title">Figure 10. Warnings</div>
<div class="title">Figure 12. Warnings</div>
</div>
<div class="paragraph">
<p>In general, it is highly recommended to resolve warnings, and errors of course, but we will make an exception from the rule, since the warnings are uncritical and would reappear each time code is regenerated.</p>
......@@ -1800,7 +1811,7 @@ Say, we want to add a table for boilers to the UI:</p>
<div class="content">
<img src="ParameterCatalogs2Images/BoilerTableDesign.png" alt="BoilerTableAndProperties">
</div>
<div class="title">Figure 11. Boiler Tables Design</div>
<div class="title">Figure 13. Boiler Tables Design</div>
</div>
<div class="paragraph">
<p>Save it!</p>
......@@ -1812,7 +1823,7 @@ Say, we want to add a table for boilers to the UI:</p>
<div class="content">
<img src="ParameterCatalogs2Images/BoilerRepresentations.png" alt="BoilerRepresentations">
</div>
<div class="title">Figure 12. Administration of Model and Representations</div>
<div class="title">Figure 14. Administration of Model and Representations</div>
</div>
<div class="paragraph">
<p>In case viewpoint <code>Catalogs</code> under header <em>Representations</em> is still disabled as shown above, select it and press <code>Enable</code>. Then:</p>
......@@ -1839,7 +1850,7 @@ Say, we want to add a table for boilers to the UI:</p>
<div class="content">
<img src="ParameterCatalogs2Images/BoilerTableAndProperties.png" alt="BoilerTableAndProperties" width="350">
</div>
<div class="title">Figure 13. Boiler Table with Properties View</div>
<div class="title">Figure 15. Boiler Table with Properties View</div>
</div>
<div class="paragraph">
<p>The screenshot on the right shows <em>new Boiler_table</em> with just two entries. Details of the selected entry are editable in <em>Properties</em>.</p>
......@@ -1873,7 +1884,7 @@ However, since the UI is not implemented by program code, but a description in a
<h3 id="trueworking-with-git-hosted-parameter-catalogs"><a class="anchor" href="#trueworking-with-git-hosted-parameter-catalogs"></a>Working with Git Hosted Parameter Catalogs</h3>
<div class="paragraph">
<p>Ecore data models and Sirius based UI design are used to create parameter catalog software hosted in Git repositories.
To work with these, all you need is Jave 16 and the <em>Obeo Designer</em> with plug-ins for handling of Units installed (see <a href="#truesetup-obeo-designer">Setup Obeo Designer</a> for details.)</p>
To work with these, all you need is Jave 16 and the <em>Obeo Designer</em> with plug-ins for handling of Units installed (see <a href="#Setup Obeo Designer">[Setup Obeo Designer]</a> for details.)</p>
</div>
<div class="paragraph">
<div class="title">Import Modeling Projects from Git</div>
......@@ -1958,7 +1969,7 @@ In the figure below, this was already done.</p>
<div class="content">
<img src="ParameterCatalogs2Images/QuantityDefaultValues.png" alt="QuantityDefaultValues" width="400">
</div>
<div class="title">Figure 14. Quantity Default Values</div>
<div class="title">Figure 16. Quantity Default Values</div>
</div>
<div class="paragraph">
<p>The red arrow shows how a unit is defined in field <em>Default Value Literal</em>. E.g., attribute <code>densityOfDrySoil</code> has unit <code>kg/m³</code> assigned to it.</p>
......@@ -2010,7 +2021,7 @@ In contrast, <code>conductivityOfDrySoil</code> is given a unit and a default nu
<div class="content">
<img src="ParameterCatalogs2Images/QuantityRange.png" alt="Quantity Range" width="250">
</div>
<div class="title">Figure 15. Quantity Range Definition</div>
<div class="title">Figure 17. Quantity Range Definition</div>
</div>
<div class="paragraph">
<p>As you can see in the screenshot, the allowed range of attribute values is defined by a so called Ecore annotation named <code>UomQuantities</code>.
......@@ -2066,7 +2077,7 @@ Each Ecore model is accompanied by a <code>.genmodel</code> that lives besides t
<div class="content">
<img src="ParameterCatalogs2Images/QuantityDocumentation.png" alt="Quantity Documentation">
</div>
<div class="title">Figure 16. Quantity Documentation</div>
<div class="title">Figure 18. Quantity Documentation</div>
</div>
<div class="paragraph">
<p>In its <code>Properties</code> provide the tooltip in field <code>Edit &#8594; Property Description</code>.
......@@ -2156,7 +2167,7 @@ Sub-dialog <code>Add Repository</code> pops up.</p>
<div class="content">
<img src="ParameterCatalogs2Images/InstallMaven1.gif" alt="InstallMaven1">
</div>
<div class="title">Figure 17. Add update site m2e</div>
<div class="title">Figure 19. Add update site m2e</div>
</div>
<div class="paragraph">
<p>In there provide <code>m2e</code> as name and</p>
......@@ -2174,7 +2185,7 @@ After confirmation with <code>Add</code>, choose the new site to <code>Work with
<div class="content">
<img src="ParameterCatalogs2Images/InstallMaven2.gif" alt="InstallMaven2">
</div>
<div class="title">Figure 18. Choose features to install</div>
<div class="title">Figure 20. Choose features to install</div>
</div>
<div class="paragraph">
<p>Provided <code>Group items by category</code> is checked, above features are displayed. Check all features and confirm all following questions about licenses and security concerns.
......@@ -2185,7 +2196,7 @@ Verify that Maven version 3.6.3 or above is now installed in <code>Window &#8594
<div class="content">
<img src="ParameterCatalogs2Images/InstallMaven3.gif" alt="InstallMaven3" width="400">
</div>
<div class="title">Figure 19. Check Maven installation</div>
<div class="title">Figure 21. Check Maven installation</div>
</div>
<div class="paragraph">
<div class="title">Add third party Java libraries</div>
......@@ -2232,7 +2243,7 @@ Verify that Maven version 3.6.3 or above is now installed in <code>Window &#8594
</div>
<div id="footer">
<div id="footer-text">
Last updated 2021-11-20 14:13:22 +0100
Last updated 2022-01-31 12:48:18 +0100
</div>
</div>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.6/styles/github.min.css">
......
ParameterCatalogs2Creation.adoc
View file @ 0fe05b5e
......@@ -90,70 +90,83 @@ That way, we can follow the convention that local Git repositories should all be
`<userhome>/git`.
=== Setup Obeo Designer
=== Setup Eclipse Modeling Tools
.Install Java
Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 11 or higher, to be installed on your machine.
Even if such JDK is already installed on your machine, please download the OpenJDK version *16* or newer for your operating system from https://adoptium.net[Adoptium].
Eclipse runs on 64-bit versions of Windows, Linux, and macOS and requires an according Java Development Kit (JDK), version 17 or higher, to be installed on your machine.
Even if such JDK is already installed on your machine, please download the JDK version *17* for your operating system from https://adoptium.net[Adoptium].
Installation process is straight forward, but you can also find links to exhaustive instructions for your operating system.
New Java versions appear every six months, so one could tend to stick with older version 11 that comes with long time support (LTE) until next LTE version 17 arrives in autumn 2021.
However, actual version 16 conforms to the latest security measures built into macOS Catalina, so it is a must if software we build here shall be deployed to these systems, too.
New Java versions appear every six months, but we will stick for the coming years with version 17, since it comes with long time support (LTS).
Note that different versions of Java coexist peacefully.
.Install Obeo Designer, Community Edition
.Install Eclipse Modeling Tools
Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of https://www.obeodesigner.com/en/product/sirius[Eclipse Sirius].
Technically, the Eclipse Sirius project provides a set of open source features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.
Instead of adding these software components manually, we start with a pre-configured Eclipse package named _Obeo Designer_.
Please download and install the latest version (11.5 at the time of writing) available at https://www.obeodesigner.com/en/download[Download Obeo Designer Community].
Our graphical and form based modeling tools, e.g. Insel 9.0 and Parameter Catalogs, run on top of Eclipse Sirius, an open source framework that provides a set of features and plugins that can be added to any Eclipse package to transform it into a very flexible modeling workbench.
[NOTE]
====
Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Obeo Designer.
====
In the past, we used the pre-configured Eclipse package _Obeo Designer Community_ from https://www.obeodesigner.com[Obeo], but it wasn't updated for a while and, thus, is stucked at Java version 14.
After the 400 something MB package has arrived, unzip the downloaded file and move the resulting application named `ObeoDesigner-Community` to a suited directory. This would be `Applications` on macOS, similar on Linux, but **not** `Programs` or `Programs (x86)` on Windows!
Instead, we install the Eclipse package _Eclipse Modeling Tools_ first and, then, Eclipse Sirius on top. To get current version 4.22 (2021‑12) of _Eclipse Modeling Tools_, go to https://www.eclipse.org/downloads/packages/[www.eclipse.org/downloads/packages/].
On this page you may see _"Try the Eclipse Installer"_ or similar.
Do *not* follow this advice, since we want more control over what versions of Java and Eclipse shall be installed.
Instead, look for package _Eclipse Modeling Tools_ and follow the link for your operating system and system architecture displayed on the right:
[WARNING]
====
**Special installation note for Windows**: We found that no plug-ins can be added to Obeo Designer, **if** it is installed in folder _Programs_ or _Programs (x86)_. Since we have to add plug-ins for handling units and quantities below, please make sure to unzip the installation package elsewhere, e.g. the Desktop or the user's home directory.
.Download links for Eclipse Modeling Tools package
image::EclipseDownload.gif[EclipseDownload, 500, role="thumb"]
====
Finally, click on `Download` and wait for the 450 something MB package to arrive.
Unzip the downloaded file and possibly rename the resulting application `Eclipse` to something more specific like `EclipseModeling2112`. Then, move the application to a suited directory. This would be `Applications` on macOS, similar on Linux, but **not** `Programs` or `Programs (x86)` on Windows!
[WARNING]
====
**Special installation note for macOS**: As Obeo Designer currently is not code-signed, macOS consideres it as damaged. To work around this security feature, remove the quarantine status of the program like so:
**Special installation note for Windows**: We found that sometimes plug-ins cannot be added to Eclipse, **if** it is installed in folder _Programs_ or _Programs (x86)_. Since we have to add plug-ins for Sirius and for handling units and quantities below, please make sure to unzip the installation package elsewhere, e.g. the Desktop or the user's home directory.
====
. Open a terminal in the folder containing the .app file
. Execute: xattr -d com.apple.quarantine ObeoDesigner-Community.app
. Double click the app to start.
[NOTE]
====
Depending on the operating system, several security dialogs have to be acknowledged during installation and first launch of Eclipse Modeling Tools.
====
After installation has finished launch the application for the first time and you will see a dialog for choosing a new empty directory as its workspace.
After installation has finished, launch the application for the first time and you will see a dialog for choosing a new empty directory as its workspace.
.Initial Dialog to Choose a Workspace Directory
image::SelectWorkspaceDirectory.gif[SelectWorkspaceDirectory, 500, role="thumb"]
More workspaces might come into existence later, so replace the proposed generic directory path and name with a more specific one, e.g.`ObeoDesignerWS`.
More workspaces might come into existence later, so replace the proposed generic directory path and name with a more specific one, e.g.`EclipseWSCatalogs`.
The main window appears with a Welcome Screen open.
Especially under `Documentation` you will find exhaustive documentation on Eclipse that might be of interest later, e.g.:
Especially under `Workbench Basics` you will find exhaustive documentation on Eclipse that might be of interest later, e.g.:
** Workbench User Guide
*** Concepts: perspectives, projects, views, editors, features, resources, ...
*** Tasks: Working with perspectives, views and editors, installing new software. ...
** EGit Documentation
*** Git for Eclipse Users
*** EGit User Guide
** Ecore Tools User Manual: Learn how to use the Ecore diagram editor.
*** Git for Eclipse Users
** Ecore Tools User Manual: Learn how to design Ecore models.
For now, you can dismiss the welcome screen. It can be opened anytime by executing `Help -> Welcome`.
Now you should see the initial window layout with _Model Explorer_ and _Outline_ on the left and a big empty editing area to the right with a _Properties_ view below.
.Install Eclipse Sirius
While package _Eclipse Modeling Tools_ already contains Sirius features that let you create graphical Ecore models, features for specifying your own forms and graphical editors are still missing. You can add these features easily from _Eclipse Marketplace_:
* Open dialog `Help -> Eclipse Marketplace...` and type _Search_ into the search field
* Look for Sirius 6.6 or newer in the list of results and click `Install`
* From the list of features choose `Sirius Specifier Environment` and `Sirius Support for AQL` for installation and unchoose the others (see screen shot)
* Confirm your choice, acknowlege any licenses, and restart Eclipse when asked for.
.Download links for Eclipse Modeling Tools package
image::InstallSirius.png[InstallSirius, 500, role="thumb"]
Above steps added commonly used software components to your Eclipse application, publicly available in the _Eclipse Marketplace_. In the next section, however, you will add features that were created specifically for parameter catalogs and hosted at the transfer portal of _HfT Stuttgart_.
[[quantity-plug-ins]]
.Add Plug-ins to deal with Quantities and Units
......@@ -166,7 +179,7 @@ The reference implementation for this framework is https://unitsofmeasurement.gi
To make Indriya available for use in Ecore data models, the author has created two plug-ins that can easily be added to Eclipse. To do so, open dialog `Help -> Install New Software...` and enter site `https://transfer.hft-stuttgart.de/pages/neqmodplus/indriya-p2/release_target_211/` like depicted below.
.Install Plug-in from Specific Update Site
image::AddUpdateSite.png[Install Plug-in , 500, role="thumb"]
image::AddUpdateSite.png[Install Plug-in, 500, role="thumb"]
Select Indriya plug-in, press `Next >` and acknowledge all following dialogs, including security warnings.
......@@ -175,8 +188,6 @@ Finally, restart Eclipse to complete plug-in installation.
While the first plug-in installs Indriya, the second plug-in adds some specific units for urban simulation and Ecore types used for modeling quantities as attributes of classes.
Now you should see the initial layout of Eclipse with _Model Explorer_ and _Outline_ on the left and a big empty editing area to the right with a _Properties_ view below.
=== Exercise: Modeling a Parameter Catalog with Ecore
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Dies ist die Gitlab-Instanz des Transferportals der Hochschule für Technik Stuttgart. Hier geht es zurück zum Portal