Vor-Ergebnisse Studienarbeit

1 files changed, 289 insertions, 0 deletions

diff --git a/ksm-model/doc/KSM-Datamodel.asciidoc b/ksm-model/doc/KSM-Datamodel.asciidoc
new file mode 100644
index 0000000..1bc1634
--- /dev/null
+++ b/ksm-model/doc/KSM-Datamodel.asciidoc
@@ -0,0 +1,289 @@
+KSM Datenmodell
+===============
+Yves Fischer <i08005@ba-horb.de>
+
+:lang: de
+:doctype: book
+:toc:
+:toc-title: Inhaltsbla
+:encoding: utf-8
+:data-uri:
+
+
+Einleitung
+----------
+Mit der Entwicklung einer KSM Anwendung auf Eclipse-RCP Basis war es
+nötig ein Datenmodell zu entwerfen welches zum MVC-ähnlichen Muster
+des Eclipse Graphical Editor Framework (GEF) kompatibel ist.
+
+Grundsätzlich lassen sich alle Datenmodelle mit GEF abbilden, jedoch existierte
+in KSM/Swing nur ein stark mit der GUI und Logik verflochtenes und fehlerhaftes
+Datenmodell, dessen Serialisierung mit einer XML-Bibliothek erfolgte die nicht
+mehr weiter verwendet werden soll.
+
+Da es nicht beabsichtigt ist die KSM/Swing Anwendung auf kurze Zeit abzulösen
+liegt es nahe, dass das Datenmodell universell einsetzbar sein sollte.
+Mit der Umstellung von KSM/Swing auf ein neues Datenmodell ist einerseits
+die Daten-Kompatibiltät zwischen KSM/Swing und KSM/RCP gegeben und das
+Ziel die XML-Serialisierung in KSM/Swing zu überarbeiten kann einfacher erreicht
+werden.
+
+Dieses Dokument beschreibt die Implementation einer API zum Zugriff auf
+das in XML-Schema beschriebene Datenformat.
+
+Dieses Datenformat erlaubt es darüberhinaus freie Felder zu definieren welche
+ebenfalls in diesem Dokument spezifiert werden.
+
+Das XML-Schema
+--------------
+Die Namespace URL für das XML-Schema lautet:
+
+    http://www.ba-horb.de/~ksm/xml/ksm-1
+
+die Schemadatei ist abrufbar unter:
+
+    http://www.ba-horb.de/~ksm/xml/ksm-1.xsd
+
+Das XML-Schema ist angereichert um JAXB-Annotationen die den XML-Schema-Java-Compiler
+bei der Klassenerzeugung steuert.
+
+Typen des Datenmodell
+---------------------
+Die Bibltiohekt besteht aus einem Package in dem Interfaces die API-Beschreiben
+und einem Package mit Implementationen dieser Interfaces die jedoch für den Benutzer
+unsichtbar und daher austauschbar sind.
+
+Das folgende Diagram zeigt das Interface das dem Benutzer zur Verfügung steht:
+
+     de.dhbw.horb.ksm. xmlschema.api
+     +----------------------------------------------------------+
+     | +-------------+   +---------------+   +------------+     |
+     | |_____KSM_____|  *|___NodeGroup___|  *|____Node____|     |
+     | |getNodeGroup +---+getNodeGroups()+---+getC.tions()|     |
+     | |getVersion() |   |getNodes()     |   |            |     |
+     | |             |   |               |   |            |     |
+     | +---^---------+   +---------------+   +--+---+-----+     |
+     |     |       \       |   ________________/    |           |
+     |     |        \1     |1 /1       	            |*          |
+     |     |       +-+-----+-+--+      	         +---+--------+ |
+     |     |       |_Properties_|1     	         |_Connection_| |
+     |     |       |getString() +----------------+getTo()     | |
+     |     |       |getInteger()|                |            | |
+     |     |       |......      |                |            | |
+     |     |       +------------+                +------------+ |
+     |     |                                                    |
+     +----------------------------------------------------------+
+           |
+     de.dhbw.horb.ksm. xmlschema.impl
+     +-------------------------------+
+     |     |                         |
+     | +------------------+          |
+     | |____KSMFactory____|          |
+     | |createEmptyKSM()  |          |
+     | |saveKSM()         |          |
+     | |loadKSM()         |          |
+     | +------------------+          |
+     +-------------------------------+
+
+
+Ein Diagramm wird erstellt indem ein neues ('createEmptyKSM()') erstellt wird oder eines
+geladen wird ('loadKSM()'). Die weitere Navigation erfolgt durch Absteigen in dem
+Objekt-Baum der durch NodeGroup- und schliesslich Node-Objekte gebildet wird.
+
+Datentypen der Eigenschaften
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Im Modell gibt es die Datentypen KSM, NodeGroup, Node und Connection (siehe Klassen-Diagramm).
+Zusätzlich gibt es die Klasse Properties mit der an die Datentypen zusätzliche Eigenschaften
+mit einem Text-Bezeichner angehängt werden können.
+
+Für die Eigenschaften stehen folgende Typen zur Verfügung: ''string'', ''integer'', ''boolean'',
+''integerList'', ''decimalList'', ''stringList''. Der Datentyp erschliesst sich aus dem Namen.
+
+Prinzipiell kann jeder Bezeichner für jeden Datentyp einmal verwendet werden, ein Bezeichner sollte
+jedoch wegen der Übersichtlichkeit nur einmal verwendet werden.
+
+Verwendung der ChangeListener
+-----------------------------
+Die Klassen __NodeGroup__, __Node__ und __Properties__ implementieren Change-Listener
+auf die sich Listener-Klassen registrieren können um über Änderungen am Datenmodell
+informiert zu werden.
+
+Dies wird beispielsweise benötigt, wenn zwei  Programmteile wie ein Eigenschaften-Editor
+in Tabellenform und ein grafischer Editor voneinander unabhängig auf das Datenmodell
+zugreifen und beispielsweise die Farbe eines Knoten ändern.
+
+Die Spalte 'Index' zeigt an ob das Event eine Index-Eigenschaft hat die andeutet
+welches Element in einer Liste geändert wurde.
+
+Die Spalte 'Version' zeigt an, ab welcher Version des Datenformat (=Version dieses
+Dokumentes, Version Attribut in <ksm> Element) dieser Event unterstützt wird.
+
+.__NodeGroup__-Events
+[width="80%",cols="3,2,2,10",options="header"]
+|=========================================================
+|Property-Name | Version | Index? |Beschreibung
+|nodes         | 1+      | ✓      | Eine __Node__ wurde dieser __NodeGroup__
+                                    hinzugefügt oder entfernt
+|=========================================================
+
+.__Node__-Events
+[width="80%",cols="3,2,2,10",options="header"]
+|=========================================================
+|Property-Name | Version | Index? |Beschreibung
+|connections   | 1+      | ✓      | Eine __Connection__ wurde erstellt oder gelöscht
+|=========================================================
+
+.__Properties__-Events
+[width="80%",cols="3,2,2,10",options="header"]
+|=========================================================
+|Property-Name    | Version | Index? |Beschreibung
+|string: 'X'      |  1+     |  ✗     | Eine Zeichenketten Eigenschaft mit Name 'X' wurde geändert
+|decimal: 'X'     |  1+     |  ✗     | Eine Fliesskommazahl Eigenschaft mit Name 'X' wurde geändert
+|integer: 'X'     |  1+     |  ✗     | Eine ganzzahlige Eigenschaft mit Name 'X' wurde geändert
+|boolean: 'X'     |  1+     |  ✗     | Eine boolsche Eigenschaft mit Name 'X' wurde geändert
+|integerList: 'X' |  1+     |  ✓     | Eine Ganzzahl Liste mit Name 'X' wurde manipuliert
+|decimalList: 'X' |  1+     |  ✓     | Eine Fliesskommazahl Liste mit Name 'X' wurde manipuliert
+|stringList: 'X'  |  1+     |  ✓     | Eine Zeichenketten Liste mit Name 'X' wurde manipuliert
+|=========================================================
+
+Eigenschaften (Properties)
+--------------------------
+Allen Elementen im Datenmodell lassen sich dynamische, dass heist nicht in einem
+Schema festgelegte, Eigenschaften zuwiesen.
+Dies hat zur Folge, dass eine Anwendung sowohl den Fall handhaben muss, dass eine
+erwartete Eigenschaft nicht vorhanden ist als auch, dass Eigenschaften vorhanden sind
+die unbekannt sind und ignoriert werden müssen.
+Dazu steht der Anwendung jedoch das Attribut 'Version' im Schema (siehe KSM#getVersion())
+zur Verfügung, welches auf eine Version von diesem Dokument zeigt.
+
+Dieser Ansatz wurde gewählt, da sich gezeigt hat, dass die Studienarbeiten im KSM-Projekt
+einen begrenzten Fokus haben und es daher für einen einzelnen Studenten schwer möglich ist,
+alle benötigten Datenfelder zu definieren.
+Das bisherige KSM-Datenformat handhabt dies, indem das XML-Schema beliebig verändert
+wurde und damit sinnlos wurde.
+Da dies unvermeidbar ist wird es mit diesem Ansatz aktiv unterstützt.
+
+Eine alternative Herangehensweise wäre die Verwendung von verschiedenen XML-Schemas gewesen
+wobei mit jeder Erweiterung ein zusätzlicher Namensraum eingeführt wird. Dies
+schien jedoch sehr viel umständlicher und unnötig kompliziert.
+
+Eigenschaften von Modellen (KSM)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Die Spalte 'Typ' zeigt den Datentyp der Eigenschaft an. Die Spalte 'Schlüssel'
+den Bezeichner welcher in Kombination mit dem Typ eindeutig ist.
+
+Die Spalte 'Version' zeigt an, ab welcher Version des Datenformat (=Version dieses
+Dokumentes, Version Attribut in <ksm> Element) dieser Event unterstützt wird.
+
+.KSM Properties
+[width="80%",cols="3,4,2,10",options="header"]
+|=========================================================
+|Typ    | Schlüssel | Version | Beschreibung
+|nichts | ist | definiert | -
+|=========================================================
+
+Eigenschaften von Knoten (Node)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.Node Properties
+[width="80%",cols="3,4,1,10",options="header"]
+|=========================================================
+|Typ      | Schlüssel         | Ver.    | Beschreibung
+| string  | visual.caption    | 1+      | Titel der Node im Editor.
+| string  | visual.color      | 1+      | Farbliches Merkmal der Node
+                                          Hexadezimal im 8-Bit RGB Format
+                                          wie folgt: +#RRGGBB+.
+| integer | visual.location.x | 1+      | X-Position relativ zur übergeordneten NodeGroup
+| integer | visual.location.y | 1+      | Y-Position relativ zur übergeordneten NodeGroup
+| decimal | data.user_value   | 1+      | User Value (?)
+| decimal | data.min_value    | 1+      | Minimal Value (?)
+| decimal | data.max_value    | 1+      | Maximal Value (?)
+| decimal | data.extern       | 1+      | Extern Value (?)
+|=========================================================
+
+Als Erbe aus dem KSM/Swing Projekt kann ''visual.color'' die folgenden Werte
+annehmen, diese sollen auf den folgenden RGB-Wert übertragen werden:
+
+ * +White+ -> +#ffffff+
+ * +Light Yellow+ -> +#faffa2+
+ * +Medium Yellow+ -> +#f4ff4b+
+ * +Yellow+ -> +#edfc00+
+ * +Light Blue+ -> +#d4d5e9+
+ * +Medium Blue+ -> +#7678ff+
+ * +Blue+ -> +#0002f8+
+ * +Light Green+ -> +#c8f8c9+
+ * +Medium Green+ -> +#7afa7e+
+ * +Green+ -> +#1af520+
+ * +Light Red+ -> +#fdcccc+
+ * +Medium Red+ -> +#f95959+
+ * +Red+ -> +#f62020+
+
+Eigenschaften von Verbindungen (Connection)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.Connection Properties
+[width="80%",cols="3,4,1,10",options="header"]
+|=========================================================
+|Typ          | Schlüssel         | Ver.    | Beschreibung
+| string      | visual.caption    | 1+      | Titel der Connection im Editor.
+| string      | visual.color      | 1+      | Farbliches Merkmal der Connection
+| string      | data.functionType | 1+      | Ein Funktionstyp von:
+                                              'straight-line', 'individual',
+                                              'parable', 'parabolic-sections'.
+| decimalList | data.function     | 1+      | KSM-Simulator Funktionsparameter dieses Knoten
+|=========================================================
+''data.function'' enthält eine Liste von Argumenten für die verwendete, durch ''data.functionType''
+festgelegte Funktion.
+
+Eigenschaften von Gruppen (NodeGroup)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.NodeGroup Properties
+[width="80%",cols="3,4,1,10",options="header"]
+|=============================================================
+| Typ     | Schlüssel         | Ver.    | Beschreibung
+| string  | visual.caption    | 1+      | Titel der Group im Editor.
+| string  | visual.color      | 1+      | Farbliches Merkmal der Group
+| integer | visual.location.x | 1+      | X-Position relativ zu übergeordneten NodeGroup
+| integer | visual.location.y | 1+      | Y-Position relativ zu übergeordneten NodeGroup
+|=============================================================
+
+
+Dokumentation der Implementierung
+---------------------------------
+Das am Anfang vorgestellte Objektmodell wird durch Interfaces im Package
+'de.dhbw.horb.ksm. xmlschema.api' umgesetzt.
+
+Eine Implementierung dieser Interfaces findet sich im Package
+'de.dhbw.horb.ksm. xmlschema.impl'. Von dieser Implementierung ist für
+äusseren Zugriff nur die Klasse 'KSMFactory' vorgesehen, welche Methoden
+zum Laden und Speichern von KSM-Modellen zur Verfügung stellt.
+
+Die Implementierung benutzt vom XML-Schema-Compiler (xjc) von JAXB generierte
+Klassen die im Package 'de.dhbw.horb.ksm. xmlschema.generated' liegen.
+Das generieren wird vom Ant-Task 'compile-xjc' und Annotationen im Schema gesteuert.
+
+Der Zugriff auf das geladene Modell erfolgt auschliesslich über die in den Interfaces
+vorgesehen Methoden, ein direkter Zugriff ist nicht möglich.
+
+Neben dem Quellcode in src/ gibt es im Projektverzeichniss noch das Verzeichnis test/
+welches JUnit-4 Tests enthält die die Implementierung nahezu 100% abdecken. Die
+Tests sind dabei zum Teil im Stil des Behavior Driven Development (BDD) geschrieben unter
+Zuhilfename der Bibliothek mockito.
+
+Vorgehensweise bei Änderungen
+-----------------------------
+1. Eintragung der Änderung in diesem Dokument
+2. Erhöhen der Versionszahl
+3. Erstellen eines Eintrags in der Revisions Historie in diesem Dokument
+4. Anpassen der Versionszahl in build.xml 'project.version'
+5. Erstellen einer HTML- und PDF Version von diesem Dokument (asciidoc/a2x).
+
+Revisions Historie
+------------------
+.Revisions
+[width="80%",cols="1,3,4,10",options="header"]
+|=========================================================
+| Ver. | Datum      | Person             | Änderung
+| 1    | 2011-03-24 | Yves Fischer       | Beginn der Historie, KSM Version 1
+| 1    | 2011-04-26 | Fischer, Dreher    | Erläuterung Datentypen.
+                                           Festlegung Funktionsname/Parameter von
+                                           Connection's.
+|=========================================================
\ No newline at end of file