<li><ahref="#truemodeling-parameter-catalogs-for-simulation-with-ecore">Modeling Parameter Catalogs for Simulation with Ecore</a></li>
<li><ahref="#truegeneration-of-java-code-from-data-model">Generation of Java Code from Data Model</a></li>
<li><ahref="#truegeneration-and-tweaking-of-user-interface">Generation and Tweaking of User Interface</a></li>
<li><ahref="#truebonus-solutions-for-specific-modeling-problems">Bonus: Solutions for Specific Modeling Problems</a></li>
<li><ahref="#trueadd-units-to-the-mix">Add Units to the Mix</a></li>
<li><ahref="#truesummary">Summary</a></li>
</ul>
</li>
<li><ahref="#trueaccessing-and-using-parameter-catalogs">Accessing and Using Parameter Catalogs</a>
...
...
@@ -934,7 +935,7 @@ Choose <code>HotSpot</code> as Java Virtual Machine.
Installation process is straight forward, but you can also find links to exhaustive instructions for your operating system.</p>
</div>
<divclass="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 version 17 arrives in autumn 2021.
<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 15 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>
</div>
<divclass="paragraph">
...
...
@@ -942,7 +943,7 @@ However, actual version 15 conforms to the latest security measures built into m
<p>Now its time to download and install the correct Eclipse package <em>Eclipse Modeling Tools</em>, version 2020-09 or newer.<supclass="footnote">[<aid="_footnoteref_7"class="footnote"href="#_footnotedef_7"title="View footnote.">7</a>]</sup>
<p>Now its time to download and install the correct Eclipse package <em>Eclipse Modeling Tools</em>, version 2021-03 or newer.
Please go to <ahref="https://www.eclipse.org/downloads/packages">Eclipse download page for 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.
...
...
@@ -973,7 +974,7 @@ Instead, look for package <em>Eclipse Modeling Tools</em> and follow the link fo
</div>
<divclass="paragraph">
<p>The downloaded installation file contains the application simply named <code>Eclipse</code> ready to be copied into <code>Applications</code> on macOS or be installed in <code>Programs</code> on Windows.
Since later you may add other Eclipse packages — or different versions of the same package — I suggest to rename the application more significantly to <code>EclipseModeling2009</code> or similar.</p>
Since later you may add other Eclipse packages — or different versions of the same package — I suggest to rename the application more significantly to <code>EclipseModeling2103</code> or similar.</p>
</div>
<divclass="paragraph">
<p>After installation has finished launch Eclipse for the first time and you will see a dialog for choosing a new empty directory as its workspace.</p>
...
...
@@ -1073,7 +1074,7 @@ Since it is not always clear where names provided during modeling are used later
@@ -1130,7 +1131,7 @@ It consists of a global unique domain name and a path to the project, unique wit
<p>Execute <code>File → New → Ecore Modeling Project</code> from main menu — not <code>Modeling Project</code>!</p>
</li>
<li>
<p>Name the project <code>org.example.democatalog</code> and uncheck <code>Use default location</code> so that the new project is <strong>not</strong> stored in workspace but a different directory you create/choose, then click <code>Next ></code></p>
<p>Name the project <code>org.example.democatalog.model</code> and uncheck <code>Use default location</code> so that the new project is <strong>not</strong> stored in workspace but a different directory you create/choose, then click <code>Next ></code></p>
</li>
<li>
<p>Provide <code>democatalog</code> as main Java package name, uncheck <code>Use default namespace parameter</code> and provide <code><ahref="http://example.org/democatalog"class="bare">http://example.org/democatalog</a></code> as <em>Ns URI</em> and <code>democat</code> as <em>Ns prefix</em></p>
...
...
@@ -1226,7 +1227,7 @@ The second one can also serve as reference.</p>
</div>
<divclass="paragraph">
<p>Note that above sources differentiate between <em>conceptual</em> and <em>detailed</em> models.
All in all we go for detailed models, since only these contain enough information to generate code.
We go for detailed models, since only these contain enough information to generate code.
Having said this, it is usually a good idea to have two or three conceptual iterations at a white board to agree on the broad approach before going too much into detail.
But even if one starts with Ecore models right away, these also can be adapted any time to follow a new train of thought.</p>
</div>
...
...
@@ -1236,7 +1237,7 @@ Instead of artificial example classes like <em>Foo</em> and <em>Bar</em> it show
<divclass="title">Figure 4. Principle Structure of a Parameter Catalog</div>
</div>
...
...
@@ -1352,7 +1353,7 @@ By the way: Is the name all you want to know about manufacturers?”</p>
</div>
<divclass="paragraph">
<p>Observe in our data model, reference <code>producedBy</code> points <em>from</em><code>EnergyComponent</code><em>to</em><code>Manufacturer</code> making it uni-directional reference.
One can simply query the manufacturer of a product, but not so the other way around.
One can simply query the manufacturer of a product, but not the other way around.
With a bi-directional reference both queries would be available.</p>
</div>
<divclass="paragraph">
...
...
@@ -1549,7 +1550,7 @@ If, by mistake, project <code>org.example.democatalog.editor</code> was created,
<p><code>Generate → Model Code</code> creates classes that represent the modeled data in code. These classes are located in three packages under directory <code>src-gen</code> in <code>org.example.democatalog</code>.</p>
<p><code>Generate → Model Code</code> creates classes that represent the modeled data in code. These classes are located in three packages under directory <code>src-gen</code> in <code>org.example.democatalog.model</code>.</p>
</div>
<divclass="paragraph">
<p><code>Generate → Edit Code</code> creates a whole new Eclipse project named <code>org.example.democatalog.edit</code>, again with generated classes under directory <code>src-gen</code>.</p>
...
...
@@ -1587,7 +1588,7 @@ To find out what user interface controls and layouts are provided by this framew
<p>In the <em>Model Explorer</em> execute <code>EMF Forms → Create View Model Project</code> from context menu over <code>democatalog.ecore</code></p>
</li>
<li>
<p>Leave project name <code>org.example.democatalog.viewmodel</code> as is but uncheck <code>Use default location</code> — as we always do — and browse to the directory containing <code>org.example.democatalog</code></p>
<p>Leave project name <code>org.example.democatalog.viewmodel</code> as is but uncheck <code>Use default location</code> — as we always do — and browse to the directory containing <code>org.example.democatalog.model</code></p>
</li>
<li>
<p>Click <code>Next ></code> and select <code>EnergyComponentsCatalog</code> as data element we want to create a user interface for</p>
...
...
@@ -1883,93 +1884,138 @@ To our convenience, view model specifications incompatible with data model are i
<p>Changes in data model also can make existing XML data incompatible. There are tools for data migration, but for now, recreation of test data or manual editing of XML file is the way to go.</p>
<p>We created a graphical Ecore data model with a catalog class and five classes/types of objects therein.
Classes have been defined by name, attributes, and relations between them, often with cardinalities.
Whenever classes shared some attributes or references we factored these out into super classes.
An enumeration introduced a new attribute type as a set of named values.</p>
</div>
<divclass="sect2">
<h3id="trueadd-units-to-the-mix"><aclass="anchor"href="#trueadd-units-to-the-mix"></a>Add Units to the Mix</h3>
<divclass="paragraph">
<p>From this data model, we issued commands to create Java code for representing the data in memory as well as to store and retrieve them on and from disk. Methods to create, read, update and delete data objects (CRUD) were generated, too.</p>
<p>As mentioned earlier, parameter catalogs should be able to represent quantities, not just bare numbers.
Java provides an extensive framework to deal with quantities and their units defined in <ahref="https://docs.google.com/document/d/12KhosAFriGCczBs6gwtJJDfg_QlANT92_lhxUWO2gCY/edit#heading=h.6698n7erex5o">Java Specification Request (JSR) 385</a>.
The reference implementation for this framework is <ahref="https://unitsofmeasurement.github.io/indriya/">Indriya</a>. Demos of its usage can be found at <ahref="https://unitsofmeasurement.github.io/uom-demos/"class="bare">https://unitsofmeasurement.github.io/uom-demos/</a>.</p>
</div>
<divclass="paragraph">
<p>Lastly, we thought about a good user interface for this data and used <em>EMF Forms</em> to model it resulting in a full functional prototype.</p>
</div>
</div>
<p>To make Indriya available Ecore data models and EMF Forms, the author has created two plug-ins that can easily be added to Eclipse. To do so, open dialog <code>Help → Install New Software…​</code> and enter site <code><ahref="https://transfer.hft-stuttgart.de/pages/neqmodplus/indriya-p2/release_target_211/"class="bare">https://transfer.hft-stuttgart.de/pages/neqmodplus/indriya-p2/release_target_211/</a></code> like depicted below.</p>
</div>
<divclass="sect2">
<h3id="truebonus-solutions-for-specific-modeling-problems"><aclass="anchor"href="#truebonus-solutions-for-specific-modeling-problems"></a>Bonus: Solutions for Specific Modeling Problems</h3>
<divclass="sect3">
<h4id="trueadd-units-to-the-mix"><aclass="anchor"href="#trueadd-units-to-the-mix"></a>Add Units to the Mix</h4>
<p>As mentioned earlier, parameter catalogs for simulations should be able to represent quantities, not just bare integer and real numbers.</p>
<divclass="title">Figure 20. Install Plug-in from Specific Update Site</div>
</div>
<divclass="paragraph">
<p>using Indrya, the reference implementation for Units of Measurement in Java (JSR 385)</p>
<p>Select Indriya plug-in, press <code>Next ></code> and acknowledge all following dialogs, including security warnings.</p>
</div>
<divclass="paragraph">
<p>To this end, the author has created two Eclipse plug-in projects providing this feature to be used by Ecore and EMF Forms.</p>
<p>Do the same for the City Units plug-in available at site <code><ahref="https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/release_target_101/"class="bare">https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/release_target_101/</a></code>
Finally, restart Eclipse to complete plug-in installation.</p>
</div>
<divclass="paragraph">
<p>Third-party libraries like Indrya, usually, are not distributed as plug-ins, but <em>Tycho</em> can wrap them automatically as OSGi plug-ins that can added directly to our application.</p>
<p>While the first plug-in installs Indriya, the second plug-in adds some specific units for urban simulation, EMF Forms editor fields for quantities, and Ecore types used for modeling quantities as attributes of classes.</p>
</div>
<divclass="paragraph">
<p>Another plug-in, created by the author connects the Ecore and Indrya. We will compile it from source code, simply by importing the projects.</p>
<p>Make the new Ecore types <code>QuantityLong</code> and <code>QuantityDouble</code> available like so:</p>
</div>
<divclass="olist arabic">
<olclass="arabic">
<li>
<p>Copy to file system …​</p>
<p>Open <code>Sample Ecore Model Editor</code> from the context menu over your Ecore model</p>
</li>
<li>
<p>From the context menu in this editor, execute <code>Load Resource…​</code> and then <code>Browse Target Platform Packages…​</code></p>
</li>
<li>
<p>Import project but <strong>not</strong> copying it in the workspace (just linking)</p>
<p>Select package <code><ahref="https://www.hftstuttgart.de/quantities"class="bare">https://www.hftstuttgart.de/quantities</a></code> and confirm the addition of
<divclass="title">Figure 21. Set QuantityDouble Type</div>
</div>
<divclass="sect3">
<h4id="truerepresent-functions-in-a-parameter-catalog"><aclass="anchor"href="#truerepresent-functions-in-a-parameter-catalog"></a>Represent Functions in a Parameter Catalog</h4>
<divclass="paragraph">
<p><strong>TBD</strong></p>
<p>From now on, the new attribute types are available to model quantities with integer or floating point values as can be seen on the screenshot to the right.</p>
</div>
<divclass="paragraph">
<p>for creating custom UI labels:</p>
<p>Note here, that I also changed the default value from <code>0.0</code> to <code>0.0 V</code> to indicate that <code>maxDCVoltage</code> of inverters is given in <strong>Volt</strong>.</p>
</div>
<divclass="ulist">
<ul>
<divclass="paragraph">
<p>The symbols for defining units follow SI and other standards, including decimal prefixes like <code>m</code> for Milli or <code>G</code> for Giga as well as derived units, that is: <code>mV</code>, <code>GV</code> or <code>kW·h/m³</code> are all valid unit definitions. This is all documented well in the resources mentioned at the top of this section, but for convenience, a table with valid units, including some specific units for urban simulation, is compiled in <ahref="UnitsExamples.md"class="bare">UnitsExamples.md</a>.</p>
</div>
<divclass="paragraph">
<p>If a unit symbol cannot be interpreted, this error is not already detected while generating and compiling code from model, but not before runt time when the application tries to create the default value. In that case, you will see an error message like this:</p>
<divclass="title">Figure 22. Error Message for Wrong Unit Definition</div>
</div>
<divclass="admonitionblock warning">
<table>
<tr>
<tdclass="icon">
<iclass="fa icon-warning"title="Warning"></i>
</td>
<tdclass="content">
<divclass="paragraph">
<p>Be told that each attribute of type <code>QuantityLong</code> or <code>QuantityDouble</code> has to have a unit defined in its <code>Default Value Literal</code>, even optional attributes that do not require a numerical value to be set. For these, too, the Ecore model must specify the unit to use.</p>
</div>
<divclass="paragraph">
<p>In other words: If you do not want to preset an attribute with a numerical default, you can omit the numerical part, but still must provide the unit symbol as <code>Default Value Literal</code>, e.g. <code>V</code> will work as well as <code>1.0 V</code> but leaving the numeric value initially undefined.</p>
</div>
</td>
</tr>
</table>
</div>
<divclass="paragraph">
<p>One last technicality. <strong>Before</strong> code from an Ecore model with attributes of type <code>QuantityLong</code> or <code>QuantityDouble</code> can be generated correctly, we must tell Eclipse to reuse the corresponding generator model from the City Units plug-in:</p>
<p>In package or project explorer find your generator model, e.g. <code>democatalog.genmodel</code> and execute <code>Reload…​</code> from its context menu</p>
<p><code>Next ></code> will open the page below. In section <em>Referenced Generator Models</em> select the Quantities generator model as depicted and click on <code>Finish</code>.</p>
<divclass="title">Figure 23. Add Reference to imported Generator Model</div>
</div>
<divclass="paragraph">
<p>Custom code marked with <code>@generated NOT</code> in <code>de.hftstuttgart.energycomponents.provider</code> in project <code>de.hftstuttgart.energycomponents.edit</code></p>
<p>If no generator model is available for selection, press button <code>Add…​</code> to add it first (this only works if <code>QuantityLong</code> or <code>QuantityDouble</code> were used at least once in the Ecore model).</p>
</div>
</div>
<divclass="sect3">
<h4id="truehow-to-model-derived-references-and-attributes"><aclass="anchor"href="#truehow-to-model-derived-references-and-attributes"></a>How to Model Derived References and Attributes</h4>
<p>Congratulations on making it this far. What have we achieved?</p>
</div>
<divclass="paragraph">
<p>We haven’t used 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: <ahref="https://www.ntnu.no/wiki/plugins/servlet/mobile?contentId=112269388#content/view/112269388"class="bare">https://www.ntnu.no/wiki/plugins/servlet/mobile?contentId=112269388#content/view/112269388</a> .</p>
<p>We get to know the <em>Eclipse Modeling Tools</em> IDE and created a graphical Ecore data model with one catalog class and five classes/types of domain objects therein.
Classes have been defined by name, attributes, and relationships between them, often with cardinalities.
Whenever classes shared some attributes or relationships we factored these out into super classes.
An enumeration introduced a new attribute type as a set of named values.</p>
</div>
<divstyle="page-break-after: always;"></div>
<divclass="paragraph">
<p>From this data model, we issued commands to create Java code for representing the data in memory as well as to store and retrieve them on and from disk. Methods to create, read, update and delete data objects (CRUD) were generated, too.</p>
</div>
<divclass="paragraph">
<p>We reflected on a good user interface for this data and used <em>EMF Forms</em> to model such an interface resulting in a full functional prototype.</p>
</div>
<divclass="paragraph">
<p>Lastly, we enhanced Eclipse, Ecore and <em>EMF Forms</em> with two plug-ins for modeling, editing and persisting physical quantities as numerical values with defined units.</p>
<divclass="title">Figure 21. Choose features to install</div>
<divclass="title">Figure 25. Choose features to install</div>
</div>
<divclass="paragraph">
<p>Check the items to install like shown above and confirm all following questions about licenses and security concerns.
<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.
After download is complete — it can take a few minutes — restart Eclipse.
Verify that Maven version 3.6.3 or above is now installed in <code>Window → Preferences…​</code> (or <code>Eclipse → Preferences…​</code> on macOS) under <code>Maven → Installations</code>.</p>
</div>
...
...
@@ -2107,7 +2153,7 @@ Verify that Maven version 3.6.3 or above is now installed in <code>Window →
@@ -2164,18 +2210,15 @@ Verify that Maven version 3.6.3 or above is now installed in <code>Window →
<ahref="#_footnoteref_6">6</a>. AdoptOpenJDK recently joined the Eclipse foundation and soon will change its name to <em>Adoptium</em> for legal reasons.
</div>
<divclass="footnote"id="_footnotedef_7">
<ahref="#_footnoteref_7">7</a>. Please stay away from version 2020-03 and 2020-06 of Eclipse Modeling Tools, since these came with a bug preventing the user from editing data in table cells within the generated UI.
