1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
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.
|=========================================================
|
