Finished chapter on creation of parameter catalogs

ParameterCatalogs2Creation.adoc

@@ -102,7 +102,7 @@ footnote:[AdoptOpenJDK recently joined the Eclipse foundation and soon will chan
 Choose `HotSpot` as Java Virtual Machine.
 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 version 17 arrives in autumn 2021.
+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.
 
 Note that different versions of Java coexist peacefully.
@@ -110,7 +110,7 @@ Note that different versions of Java coexist peacefully.
 
 .Install Eclipse Modeling Tools
 
-Now its time to download and install the correct Eclipse package _Eclipse Modeling Tools_, version 2020-09 or newer.footnote:[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.]
+Now its time to download and install the correct Eclipse package _Eclipse Modeling Tools_, version 2021-03 or newer.
 Please go to https://www.eclipse.org/downloads/packages[Eclipse download page for 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.
@@ -127,7 +127,7 @@ Depending on the operating system, several security dialogs have to be acknowled
 ====
 
 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 later you may add other Eclipse packages -- or different versions of the same package -- I suggest to rename the application more significantly to `EclipseModeling2009` or similar.
+Since later you may add other Eclipse packages -- or different versions of the same package -- I suggest to rename the application more significantly to `EclipseModeling2103` or similar.
 
 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.  
 
@@ -171,7 +171,7 @@ Since it is not always clear where names provided during modeling are used later
                    | org.example                    | hft-stuttgart.de 
 | Main Package     | democatalog                    | buildingphysics 
 | Eclipse Projectfootnote:[https://wiki.eclipse.org/Naming_Conventions#Eclipse_Workspace_Projects]
-                   | org.example.democatalog        | de.hft-stuttgart.buildingphysics 
+                   | org.example.democatalog.model  | de.hft-stuttgart.buildingphysics
 | Class Prefix     | Democatalog                    | Buildingphysics 
 | XML File Suffix  | democatalog                    | buildingphysics 
 | Classes          | e.g. SolarPanel                | e.g. WindowType 
@@ -187,7 +187,7 @@ It consists of a global unique domain name and a path to the project, unique wit
 Use the names of example _Demo Catalog_ to create your first Ecore modeling project:
 
 . Execute `File -> New -> Ecore Modeling Project` from main menu -- not `Modeling Project`!
-. Name the project `org.example.democatalog` and uncheck `Use default location` so that the new project is *not* stored in workspace but a different directory you create/choose, then click `Next >`
+. Name the project `org.example.democatalog.model` and uncheck `Use default location` so that the new project is *not* stored in workspace but a different directory you create/choose, then click `Next >`
 . Provide `democatalog` as main Java package name, uncheck `Use default namespace parameter` and provide `http://example.org/democatalog` as _Ns URI_ and `democat` as  _Ns prefix_
 . Click `Finish`.
 
@@ -232,7 +232,7 @@ The second one can also serve as reference.
 We will touch central object-oriented concepts _Class_, _Object_, _Attribute_, _Association_, _Composition_, and _Multiplicity_ in an example below, but work through above sources to get a deeper understanding and to enhance your modeling skills.
 
 Note that above sources differentiate between _conceptual_ and _detailed_ 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.
 
@@ -383,7 +383,7 @@ _Dev_: "`Fine ... good meeting.`"
 ****
 
 Observe in our data model, reference `producedBy` points _from_ `EnergyComponent` _to_ `Manufacturer` 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.
 
 Observe also the annotations `0..*` and `1..1` near class `Manufacturer`.
@@ -501,7 +501,7 @@ If, by mistake, project `org.example.democatalog.editor` was created, just delet
 .Generated Classes
 image::GeneratedClasses.png[GeneratedClasses, 260, float="right", role="thumb"]
 
-`Generate -> Model Code` creates classes that represent the modeled data in code. These classes are located in three packages under directory `src-gen` in `org.example.democatalog`.
+`Generate -> Model Code` creates classes that represent the modeled data in code. These classes are located in three packages under directory `src-gen` in `org.example.democatalog.model`.
 
 `Generate -> Edit Code` creates a whole new Eclipse project named `org.example.democatalog.edit`, again with generated classes under directory `src-gen`.
 
@@ -524,7 +524,7 @@ In this section you will learn how to generate and tweak a CRUD user interface b
 To find out what user interface controls and layouts are provided by this framework have a look at https://eclipsesource.com/blogs/tutorials/emf-forms-view-model-elements/[EMF Forms – View Model Elements]. _EMF Forms_ is already part of package _Eclipse Modeling Tools_, so we can create a third Eclipse project/plugin that implements a user interface for editing catalog data without further ado:
 
 . In the _Model Explorer_ execute `EMF Forms -> Create View Model Project` from context menu over `democatalog.ecore`
-. Leave project name `org.example.democatalog.viewmodel` as is but uncheck `Use default location` -- as we always do -- and browse to the directory containing `org.example.democatalog`
+. Leave project name `org.example.democatalog.viewmodel` as is but uncheck `Use default location` -- as we always do -- and browse to the directory containing `org.example.democatalog.model`
 . Click `Next >` and select `EnergyComponentsCatalog` as data element we want to create a user interface for
 . Leave `Fill view model with default layout` checked and click `Finish`.
 
@@ -706,56 +706,75 @@ To our convenience, view model specifications incompatible with data model are i
 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.
 
 
-==== Summary
+=== Add Units to the Mix
 
-What have we achieved so far?
+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 https://docs.google.com/document/d/12KhosAFriGCczBs6gwtJJDfg_QlANT92_lhxUWO2gCY/edit#heading=h.6698n7erex5o[Java Specification Request (JSR) 385].
+The reference implementation for this framework is https://unitsofmeasurement.github.io/indriya/[Indriya]. Demos of its usage can be found at https://unitsofmeasurement.github.io/uom-demos/[].
 
-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.
+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 `Help -> Install New Software...` and enter site `https://transfer.hft-stuttgart.de/pages/neqmodplus/indriya-p2/release_target_211/` like depicted below.
 
-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.
+.Install Plug-in from Specific Update Site
+image::AddUpdateSite.png[Install Plug-in , 500, role="thumb"]
 
-Lastly, we thought about a good user interface for this data and used _EMF Forms_ to model it resulting in a full functional prototype.
+Select Indriya plug-in, press `Next >` and acknowledge all following dialogs, including security warnings.
 
+Do the same for the City Units plug-in available at site `https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/release_target_101/`
+Finally, restart Eclipse to complete plug-in installation.
 
-=== Bonus: Solutions for Specific Modeling Problems
+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.
 
+Make the new Ecore types `QuantityLong` and `QuantityDouble` available like so:
 
-==== Add Units to the Mix
+. Open `Sample Ecore Model Editor` from the context menu over your Ecore model
+. From the context menu in this editor, execute `Load Resource...` and then `Browse Target Platform Packages...`
+. Select package `https://www.hftstuttgart.de/quantities` and confirm the addition of 
+`platform:/resource/de.hftstuttgart.cityunits.model/model/Quantities.ecore`.
 
-*TBD*
+.Set QuantityDouble Type
+image::QuantityDoubleAttributeType.png[Install Plug-in, 300, float="right", role="thumb"]
 
-As mentioned earlier, parameter catalogs for simulations should be able to represent quantities, not just bare integer and real numbers.
+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.
 
-using Indrya, the reference implementation for Units of Measurement in Java (JSR 385)
+Note here, that I also changed the default value from `0.0` to `0.0 V` to indicate that `maxDCVoltage` of inverters is given in *Volt*.
 
-To this end, the author has created two Eclipse plug-in projects providing this feature to be used by Ecore and EMF Forms.
+The symbols for defining units follow SI and other standards, including decimal prefixes like `m` for Milli or `G` for Giga as well as derived units, that is: `mV`, `GV` or `kW·h/m³` 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 link:UnitsExamples.md[].
 
-Third-party libraries like Indrya, usually, are not distributed as plug-ins, but _Tycho_ can wrap them automatically as OSGi plug-ins that can added directly to our application.
+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:
 
-Another plug-in, created by the author connects the Ecore and Indrya. We will compile it from source code, simply by importing the projects.
+.Error Message for Wrong Unit Definition
+image::ErrorInUnitDefinition.png[Install Plug-in , 400, role="thumb"]
 
-. Copy to file system ...
-. Import project but *not* copying it in the workspace (just linking)
+[WARNING]
+====
+Be told that each attribute of type `QuantityLong` or `QuantityDouble` has to have a unit defined in its `Default Value Literal`, 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. 
 
+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 `Default Value Literal`, e.g. `V` will work as well as `1.0 V` but leaving the numeric value initially undefined.
+====
 
-==== Represent Functions in a Parameter Catalog
+One last technicality. *Before* code from an Ecore model with attributes of type `QuantityLong` or `QuantityDouble` can be generated correctly, we must tell Eclipse to reuse the corresponding generator model from the City Units plug-in:
 
-*TBD*
+. In package or project explorer find your generator model, e.g. `democatalog.genmodel` and execute `Reload...` from its context menu
+. Choose `Ecore model`, press `Next >` and `Load` the model (again)
+. `Next >` will open the page  below. In section _Referenced Generator Models_ select the Quantities generator model as depicted and click on `Finish`.
 
-for creating custom UI labels:
+.Add Reference to imported Generator Model
+image::ReferenceGeneratorModel.png[Install Plug-in , 500, role="thumb"]
 
-* `ExponentialFunctionItemProvider.java`
-* `LinearFunctionItemProvider.java`
-* `TableFunctionItemProvider.java`
+If no generator model is available for selection, press button `Add...` to add it first (this only works if `QuantityLong` or `QuantityDouble` were used at least once in the Ecore model).
 
-Custom code marked with `@generated NOT` in `de.hftstuttgart.energycomponents.provider` in project `de.hftstuttgart.energycomponents.edit`
 
-==== How to Model Derived References and Attributes
+=== Summary
 
-*TBD*
+Congratulations on making it this far. What have we achieved?
+
+We get to know the _Eclipse Modeling Tools_ 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.
+
+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.
 
-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: https://www.ntnu.no/wiki/plugins/servlet/mobile?contentId=112269388#content/view/112269388 .
+We reflected on a good user interface for this data and used _EMF Forms_ to model such an interface resulting in a full functional prototype.
 
+Lastly, we enhanced Eclipse, Ecore and _EMF Forms_ with two plug-ins for modeling, editing and persisting physical quantities as numerical values with defined units.

README.md

@@ -4,4 +4,6 @@
 
 Exhaustive tutorial on how to create parameter catalogs - e.g. for energy devices, building physics, building usage - based on Ecore and other Eclipse technologies.
 
-Includes background information, a gentle introduction to Ecore data modeling and step-by-step instructions on how to generate editor applications from data model.
\ No newline at end of file
+Includes background information, a gentle introduction to Ecore data modeling and step-by-step instructions on how to generate editor applications from data model.
+
+Special sections describe the incorporation of explicit units in the data model, possibly usage scenarios of parameter catalogs, and the creation od deployable editor applications.
\ No newline at end of file

UnitsExamples.md

+
+## Units of Measurement
+
+For an introduction on dealing with units in Java, see
+[Baeldung: Introduction to javax.measure](https://www.baeldung.com/javax-measure).
+
+Here some examples for valid units:
+
+
+| Symbol   | Dimension           
+| -------- | ------------------- 
+| Hz       | 1/[T] 
+| Bq       | 1/[T] 
+| A        | [I] 
+| F        | [I]²·[T]^4/([L]²·[M]) 
+| S        | [I]²·[T]³/([L]²·[M]) 
+| C        | [I]·[T] 
+| cd       | [J] 
+| lm       | [J] 
+| lx       | [J]/[L]² 
+| m        | [L] 
+| m/s      | [L]/[T] 
+| km/h     | [L]/[T] 
+| m/s²     | [L]/[T]² 
+| m²       | [L]² 
+| Sv       | [L]²/[T]² 
+| Gy       | [L]²/[T]² 
+| H        | [L]²·[M]/([I]²·[T]²) 
+| Ω        | [L]²·[M]/([I]²·[T]³) 
+| Wb       | [L]²·[M]/([I]·[T]²) 
+| V        | [L]²·[M]/([I]·[T]³) 
+| J        | [L]²·[M]/[T]² 
+| W        | [L]²·[M]/[T]³ 
+| l        | [L]³ 
+| m³       | [L]³ 
+| N        | [L]·[M]/[T]² 
+| kg       | [M] 
+| g        | [M] 
+| T        | [M]/([I]·[T]²) 
+| Pa       | [M]/([L]·[T]²) 
+| mol      | [N] 
+| kat      | [N]/[T] 
+| h        | [T] 
+| year     | [T] 
+| s        | [T] 
+| day      | [T] 
+| week     | [T] 
+| min      | [T] 
+| K        | [Θ] 
+| ℃        | [Θ] 
+| one      | one 
+| %        | one 
+| rad      | one 
+| sr       | one 
+
+Some units of special interest for Urban Simulation, partly introduced with Plug-in "City Units":
+
+| Symbol   | Dimension           
+| -------- | -------------- 
+| W·s      | [L]²·[M]/[T]² 
+| W·h      | [L]²·[M]/[T]² 
+| kW·h     | [L]²·[M]/[T]² 
+| MW·h     | [L]²·[M]/[T]² 
+| m³/min   | [L]³/[T] 
+| m³/h     | [L]³/[T] 
+| m³/s     | [L]³/[T] 
+| m³/d     | [L]³/[T] 
+| l/min    | [L]³/[T] 
+| W/m²     | [M]/[T]³ 
+| ppm      | one 
+| dB       | one 
+| €        | [$]
+| $        | [$]
+
+Note that monetary units have been added ad hoc to City Untis to model costs, but may be abandoned in future.