Ecore names explained with examples, changed models/figures accordingly

ParameterCatalogs2Creation.adoc

@@ -147,25 +147,54 @@ It contains links to exhaustive documentation on concept, features and usage of
 * Learn how to use the Ecore diagram editor
 * Launch the Eclipse Marketplace
 
-For now, you can dismiss the welcome screen. It can be opened anytime by executing `Help -> Welcome`
+For now, you can dismiss the welcome screen. It can be opened anytime by executing `Help -> Welcome`.
+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.
 
 
 === Modeling Parameter Catalogs for Simulation with Ecore
-
-Now you should see the initial layout of Eclipse with _Model Explorer_ and _Outline_ on the left and a big empty editing area with _Properties_ view below to the right.
-
-Since we will use Ecore diagrams for data modeling, create your first Ecore modeling project now:
+[quote,Phil Karlton / N.N.]
+____
+There are two hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.
+____
+
+It takes time and effort to come along with good names for model entities, projects, files, and so on.
+Also, specific naming conventions are in place to enhance readability of models and program code.
+Since it is not always clear where names provided during modeling are used later, I compiled a list of names important in Ecore projects and added examples and comments to elucidate their meaning and naming conventions.
+
+.Naming
+[width="100%",options="header"]
+|====================
+| Name             | Demo Catalog Example           | Real World Expample 
+| Namespace URI    | http://example.org/democatalog | http://hft-stuttgart.de/buildingphysics 
+| Namespace Prefix | democat                        | buildphys 
+| Base Package (reverse domain)footnote:[https://en.wikipedia.org/wiki/Reverse_domain_name_notation]
+                   | 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 
+| Class Prefix     | Democatalog                    | Buildingphysics 
+| XML File Suffix  | democatalog                    | buildingphysics 
+| Classes          | e.g. SolarPanel                | e.g. WindowType 
+| Attributes       | e.g. nominalPower              | e.g. id
+| Associations     | e.g. solarPanels               | e.g. windowTypes 
+|====================
+
+Classes are written in https://en.wikipedia.org/wiki/Camel_case[Camel case notation] starting with an upper case letter. Associations and attributes are written the same way, but starting with a lower case letter.
+
+All other names should be derived from the globally unique _name space_ of the project, in our example: `example.org/democatalog`.
+It consists of a global unique domain name and a path to the project, unique within that domain.
+
+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 it `demo.catalog` and click `Next >`
-. 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 and click `Finish`.
+. 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 >`
+. 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`.
 
 Eclipse should look like below with an new empty graphical Ecore diagram editor opened.
 The diagram is automatically named `democatalog` after the package name for the Java classes that will be generated from it (provided above).
 The _Model Explorer_ shows the contents of the new Ecore modeling project.
 
-
 .New Ecore Modeling Project
 image::DemoCatalogEmpty.png[DemoCatalogEmpty, role="thumb"]
 
@@ -227,10 +256,14 @@ abstract class EnergyComponent {
     revisionYear: int
 }
 
-abstract class ChemicalEnergyDevice {
+abstract class ChemicalDevice {
     installedThermalPower: double
 }
 
+abstract class ElectricalDevice {
+    nominalPower : double
+}
+
 class Boiler {
     type : BoilerType
 }
@@ -238,7 +271,6 @@ class Boiler {
 class CombinedHeatPower {
     thermalEfficiency : double
     electricalEfficiency : double
-
 }
 
 class Manufacturer {
@@ -251,24 +283,23 @@ enum BoilerType {
 }
 
 class SolarPanel {
-    nominalPower : double
     mppVoltage : double
     mppCurrent : double
 }
 
 class Inverter {
-    nominalPower : double
     maxDCVoltage : double
     maxDCCurrent : double
 }
 
 BoilerType -[hidden]- Boiler
 
-SolarPanel --|> EnergyComponent
-Inverter --|> EnergyComponent
-ChemicalEnergyDevice --|> EnergyComponent
-Boiler --|> ChemicalEnergyDevice
-CombinedHeatPower --|> ChemicalEnergyDevice
+ElectricalDevice --|> EnergyComponent
+SolarPanel --|> ElectricalDevice
+Inverter --|> ElectricalDevice
+ChemicalDevice --|> EnergyComponent
+Boiler --|> ChemicalDevice
+CombinedHeatPower --|> ChemicalDevice
 
 EnergyComponentsCatalog *-- "0..*" Inverter: inverters
 EnergyComponentsCatalog *-- "0..*" SolarPanel: solarPanels
@@ -290,7 +321,8 @@ Compositions are depicted as a link with a diamond shape attached to the contain
 
 [IMPORTANT]
 ====
-Note that class names -- despite the fact that they model a set of similar objects -- are always written in _singular_! They are written in https://en.wikipedia.org/wiki/Camel_case[Camel case notation] starting with an upper case letter. Associations and attributes are written the same way, but starting with a lower case letter. Names for list-like associations and attributes usually are written in plural form.
+Note that class names -- despite the fact that they model a set of similar objects -- are always written in _singular_!
+Names for list-like associations and attributes usually are written in plural form.
 ====
 
 .Inheritance
@@ -299,7 +331,8 @@ Whenever classes of objects share the same attributes or associations, we don't
 Instead, we add a _super class_ to define common attributes and associations and connect it to _sub classes_ that will automatically _inherit_ all the features of their super class.
 
 In our example above, common to all four energy components are attributes `modelName` and `revisionYear`, thus these are modeled by class `EnergyComponent` that is directly or indirectly a super class of _Boiler_, _CombinedHeatPower_, _SolarPanel_, and _Inverter_.
-Similar, _Boiler_ and _CombinedHeatPower_ share attribute `installedThermalPower` factored out by class _ChemicalEnergyDevice_.
+Similar, _Boiler_ and _CombinedHeatPower_ share attribute `installedThermalPower` factored out by class _ChemicalDevice_.
+_SolarPanel_ and _Inverter_ share attribute `nominalPower` modeled in abstract class _ElectricalDevice_.
 
 .Associations
 You probably noticed a fifth type of objects contained in the catalog, namely `Manufacturer` objects stored in list `manufactureres`.
@@ -443,14 +476,14 @@ By now, your Ecore model should look like this:
 
 [[fig-example-model]]
 .Example Model (Homework)
-image::Homework.gif[Homework, role="thumb"]
+image::Homework.png[Homework, role="thumb"]
 
 Let us bring the model to life, that is, generate code from it that creates, reads, updates, and deletes concrete data objects of modeled classes in computers.
 I would like to tell you that this is done with just one click but, actually, you need two or three:
 
 . Make sure all files are saved (`File -> Save All`)
-. Execute `Generate -> Model Code` from context menu over `democatalog.ecore`
-. Execute `Generate -> Edit Code` from context menu over `democatalog.ecore`
+. Execute `Generate -> Model Code` from the context menu of Ecore editor `democatalog`
+. Execute `Generate -> Edit Code` from the same context menu
 
 [WARNING]
 ====
@@ -459,7 +492,7 @@ Please do *not* execute `Generate -> All` or `Generate -> Editor Code`.
 image::GenerateMenu.png[GeneratedClasses, 260, role="thumb"]
 
 This would create code for a simple user interface, but we use more advanced EMF Forms for that later.
-If, by mistake, project `demo.catalog.editor` was created, just delete it from _Model Explorer_ and do not forget to check `Delete project contents on disk` in confirmation dialog.
+If, by mistake, project `org.example.democatalog.editor` was created, just delete it from _Model Explorer_ and do not forget to check `Delete project contents on disk` in confirmation dialog.
 
 ====
 
@@ -468,9 +501,9 @@ If, by mistake, project `demo.catalog.editor` was created, just delete it from _
 .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 `demo.catalog`.
+`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 -> Edit Code` creates a whole new Eclipse project named `demo.catalog.edit`, again with generated classes under directory `src-gen`.
+`Generate -> Edit Code` creates a whole new Eclipse project named `org.example.democatalog.edit`, again with generated classes under directory `src-gen`.
 
 You may have a look at some Java classes for curiosity by double clicking at them in _Model Explorer_. There is no point in trying to understand the code in detail, but observe token `@generated` present in the comments of all classes, fields and methods. Classes, fields and methods marked with this token are (re)generated whenever above commands are executed.
 
@@ -490,12 +523,12 @@ In general, it is highly recommended to resolve warnings, and errors of course,
 In this section you will learn how to generate and tweak a CRUD user interface based on Ecore data model and Java classes created for our demo parameters catalog above. Topics described here are discussed in more detail in tutorial https://eclipsesource.com/blogs/tutorials/getting-started-with-EMF-Forms/[Getting started with EMF Forms].
 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:
 
-. From context menu over `democatalog.ecore` execute `EMF Forms -> Create View Model Project`
-. Leave project name `demo.catalog.viewmodel` as is but uncheck `Use default location` -- as we always do -- and browse to the directory containing `demo.catalog`
+. 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`
 . 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`.
 
-According to these inputs a new project is created with file `EnergyComponentsCatalog.view` under directory `view models`.
+According to these inputs a new project is created with file `EnergyComponentsCatalog.view` under directory `viewmodels`.
 This file opens automatically in a special _View Editor_.
 
 .New View Model
@@ -528,7 +561,7 @@ This is what _functional_ preview means.
 You can even create new boilers or other objects in lists provided, with all forms created "automagically" with respect to our underlying Ecore data model.
 
 Of course, such automatic approach has its limits.
-In our case, to have a long list of lists is not very user-friendly, because one has to scroll up and down to find a specific list.
+In our case, a long list of lists is not very user-friendly, because one has to scroll up and down to find a specific list.
 Also, no specific object data are shown in the list and data can only be edited in a pop-up form (no inline editing).
 
 How should a better UI look and feel like?
@@ -626,7 +659,7 @@ Yes! ... Please repeat above procedure to create table controls for chps, solar
 In last section we improved our catalog's UI by replacing simple object lists by tables that can be sorted, customized and edited inline as well as in an associated panel.
 Alas, instead a list of lists we have got an even bigger list of tables.
 
-High time to introduce a master-detail view that presents categories of object types in a master view and, after one is selected, the according object table as detail.
+High time to introduce a master-detail view that presents categories of object types in a master view and, after one is selected, the according object table in the detail view.
 
 [.float-group]
 --
@@ -666,8 +699,8 @@ Note that _EMF Forms Preview_ provides these buttons image:ViewModelPersistence.
 In fact, this feature gives us a fully functional prototype.
 At least during refinement of model and UI, data sets can be created, edited, and tested for usability without the need to built a full blown, deployable application -- see parts _Accessing and Using Parameter Catalogs_ and _Build (Parameter Catalog) Applications with Eclipse Tycho_ below.
 
-Be aware that in some cases the view model must adapt to changes in the data model, e.g. a new leaf category and table component has to be created for a new catalog object type.
-Other changes are automatically reflected in the generated UI, at least for default forms and other UI elements.
+Be aware that in some cases the view model must adapt to changes in data model, e.g. a new leaf category and table component must be created for a new catalog object type.
+Other changes are automatically reflected in the generated UI, at least for default forms and default table columns.
 To our convenience, view model specifications incompatible with data model are indicated by error badges in the _View Editor_.
 
 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.
@@ -678,13 +711,13 @@ Changes in data model also can make existing XML data incompatible. There are to
 What have we achieved so far?
 
 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, often with cardinalities.
+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 from a set of named values.
+An enumeration introduced a new attribute type as a set of named values.
 
-From this data model, we issued commands to create matching 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.
+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.
 
-Lastly, we thought about a good user interface for this data and used _EMF Forms_ to model and prototype it.
+Lastly, we thought about a good user interface for this data and used _EMF Forms_ to model it resulting in a full functional prototype.
 
 
 === Bonus: Solutions for Specific Modeling Problems