Check-in [43a8ae7699]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Checkpoint in document on how to translate a model with micca.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:43a8ae7699ba42838a4e0534c3cb2b5580def699
User & Date: andrewm 2019-02-17 17:57:54
Context
2019-02-23
08:56
Checkpoint on writing a howto document for micca. check-in: 789c3e57bb user: andrewm tags: micca-develop
2019-02-17
17:57
Checkpoint in document on how to translate a model with micca. check-in: 43a8ae7699 user: andrewm tags: micca-develop
12:07
Starting writing on a "how to" for translation using micca. check-in: 9f687b8539 user: andrewm tags: micca-develop
Changes

Changes to micca/doc/howto/Makefile.

22
23
24
25
26
27
28

29
30
31

32
33
34
35
36
37
38
	marking.txt\
	syntax.txt\
	data.txt\
	dynamics.txt\
	processing.txt\
	bridge.txt\
	codeorg.txt\

	$(NULL)

DIAGRAMS =\

	$(NULL)

IMAGES =\
	$(patsubst %.uxf,$(IMAGEDIR)/%.pdf,$(DIAGRAMS))\
	$(NULL)

PDF 	=\







>



>







22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
	marking.txt\
	syntax.txt\
	data.txt\
	dynamics.txt\
	processing.txt\
	bridge.txt\
	codeorg.txt\
	bibliography.txt\
	$(NULL)

DIAGRAMS =\
	micca-translation.uxf\
	$(NULL)

IMAGES =\
	$(patsubst %.uxf,$(IMAGEDIR)/%.pdf,$(DIAGRAMS))\
	$(NULL)

PDF 	=\

Added micca/doc/howto/bibliography.txt.























































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
// vim:set syntax=asciidoc:

[bibliography]
== Bibliography [[bibliography]]
[bibliography]
.Books
- [[[mb-xuml]]] Stephen J. Mellor and Marc J. Balcer,
    'Executable UML: a foundation for model-driven architecture',
    Addison-Wesley (2002), ISBN 0-201-74804-5.
- [[[rs-xuml]]] Chris Raistrick, Paul Francis, John Wright, Colin Carter and
    Ian Wilkie,
    'Model Driven Architecture with Executable UML',
    Cambridge University Press (2004),
    ISBN 0-521-53771-1.
- [[[mtoc]]]
    Leon Starr, Andrew Mangogna and Stephen Mellor,
    'Models to Code: With No Mysterious Gaps',
    Apress (2017),
    ISBN 978-1-4842-2216-4
- [[[ls-build]]], Leon Starr,
    'How to Build Shlaer-Mellor Object Models',
    Yourdon Press (1996),
    ISBN 0-13-207663-2.
- [[[sm-data]]] Sally Shlaer and Stephen J. Mellor,
    'Object Oriented Systems Analysis: Modeling the World in Data',
    Prentice-Hall (1988),
    ISBN 0-13-629023-X.
- [[[sm-states]]]
    Sally Shlaer and Stephen J. Mellor,
    'Object Oriented Systems Analysis: Modeling the World in States',
    Prentice-Hall (1992),
    ISBN 0-13-629940-7.

[bibliography]
.Articles
- [[[ls-articulate]]] Leon Starr,
    'How to Build Articulate UML Class Models',
    2008,
    http://www.modelint.com/how-to-build-articulate-uml-class-models/
- [[[ls-time]]] Leon Starr,
    'Time and Synchronization in Executable UML',
    2008,
    http://www.modelint.com/time-and-synchronization-in-executable-uml/

Added micca/doc/howto/figures/micca-translation.uxf.













































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.3.0">
  <zoom_level>10</zoom_level>
  <element>
    <id>UMLActor</id>
    <coordinates>
      <x>270</x>
      <y>370</y>
      <w>60</w>
      <h>100</h>
    </coordinates>
    <panel_attributes>Analyst</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLUseCase</id>
    <coordinates>
      <x>470</x>
      <y>370</y>
      <w>160</w>
      <h>90</h>
    </coordinates>
    <panel_attributes>valign=center
Capture Platform
Independent Model
</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>480</x>
      <y>580</y>
      <w>190</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
Domain Diagrams
Class, State Model, Activity</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>320</x>
      <y>390</y>
      <w>170</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>lt=&lt;&lt;-&gt;&gt;
Model Edits</panel_attributes>
    <additional_attributes>10.0;20.0;150.0;20.0</additional_attributes>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>540</x>
      <y>450</y>
      <w>120</w>
      <h>150</h>
    </coordinates>
    <panel_attributes>lt=&lt;&lt;-&gt;&gt;
Domain
Data Elements</panel_attributes>
    <additional_attributes>10.0;130.0;10.0;10.0</additional_attributes>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>1310</x>
      <y>590</y>
      <w>130</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
PSM Data Store</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLUseCase</id>
    <coordinates>
      <x>1180</x>
      <y>380</y>
      <w>160</w>
      <h>100</h>
    </coordinates>
    <panel_attributes>valign=center
bg=yellow
layer=1
Capture Domain To
Platform Specific
Model</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1290</x>
      <y>460</y>
      <w>150</w>
      <h>150</h>
    </coordinates>
    <panel_attributes>lt=&lt;&lt;-
Platform Specific
Data Elements</panel_attributes>
    <additional_attributes>50.0;130.0;10.0;18.0</additional_attributes>
  </element>
  <element>
    <id>UMLActor</id>
    <coordinates>
      <x>740</x>
      <y>390</y>
      <w>80</w>
      <h>100</h>
    </coordinates>
    <panel_attributes>Translator
layer=1</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLUseCase</id>
    <coordinates>
      <x>1430</x>
      <y>390</y>
      <w>160</w>
      <h>90</h>
    </coordinates>
    <panel_attributes>valign=center
bg=yellow
layer=1
Generate
Code</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>1520</x>
      <y>590</y>
      <w>130</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
Domain Code Files</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1550</x>
      <y>460</y>
      <w>90</w>
      <h>150</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>10.0;10.0;20.0;130.0</additional_attributes>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1410</x>
      <y>460</y>
      <w>150</w>
      <h>150</h>
    </coordinates>
    <panel_attributes>lt=&lt;&lt;-
Platform Specific
Data Elements</panel_attributes>
    <additional_attributes>50.0;10.0;10.0;130.0</additional_attributes>
  </element>
  <element>
    <id>UMLUseCase</id>
    <coordinates>
      <x>1300</x>
      <y>730</y>
      <w>160</w>
      <h>90</h>
    </coordinates>
    <panel_attributes>valign=center
Compile, Link,
Build System</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1420</x>
      <y>620</y>
      <w>180</w>
      <h>140</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>160.0;10.0;10.0;120.0</additional_attributes>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>1520</x>
      <y>750</y>
      <w>170</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
bg=#3c7a00
Program Executable File</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1450</x>
      <y>760</y>
      <w>90</w>
      <h>30</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;</panel_attributes>
    <additional_attributes>10.0;10.0;70.0;10.0</additional_attributes>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>690</x>
      <y>240</y>
      <w>30</w>
      <h>520</h>
    </coordinates>
    <panel_attributes>lt=.
lw=3</panel_attributes>
    <additional_attributes>10.0;500.0;10.0;10.0</additional_attributes>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>610</x>
      <y>430</y>
      <w>160</w>
      <h>170</h>
    </coordinates>
    <panel_attributes>lt=.&gt;&gt;</panel_attributes>
    <additional_attributes>10.0;150.0;140.0;10.0</additional_attributes>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>800</x>
      <y>410</y>
      <w>140</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
layer=1
Domain
Configuration</panel_attributes>
    <additional_attributes>10.0;20.0;120.0;20.0</additional_attributes>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>920</x>
      <y>410</y>
      <w>130</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
layer=1
micca DSL source</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1040</x>
      <y>410</y>
      <w>160</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
Domain
Configuration</panel_attributes>
    <additional_attributes>10.0;20.0;140.0;20.0</additional_attributes>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>970</x>
      <y>560</y>
      <w>160</w>
      <h>140</h>
    </coordinates>
    <panel_attributes>Micca Run-time Domain
--
bg=light_gray
group=1</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1090</x>
      <y>630</y>
      <w>240</w>
      <h>140</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>10.0;10.0;220.0;120.0</additional_attributes>
  </element>
  <element>
    <id>UMLNote</id>
    <coordinates>
      <x>740</x>
      <y>270</y>
      <w>120</w>
      <h>30</h>
    </coordinates>
    <panel_attributes>style=autoresize
bg=yellow
Translation Phase</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLNote</id>
    <coordinates>
      <x>560</x>
      <y>270</y>
      <w>100</w>
      <h>30</h>
    </coordinates>
    <panel_attributes>style=autoresize
bg=yellow
Analysis Phase</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>1150</x>
      <y>330</y>
      <w>480</w>
      <h>170</h>
    </coordinates>
    <panel_attributes>micca
--
bg=orange</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLPackage</id>
    <coordinates>
      <x>1000</x>
      <y>600</y>
      <w>100</w>
      <h>70</h>
    </coordinates>
    <panel_attributes>Run Time Code
bg=yellow
group=1</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>970</x>
      <y>750</y>
      <w>130</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
Bridge Code Files</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1090</x>
      <y>750</y>
      <w>230</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>10.0;20.0;210.0;20.0</additional_attributes>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>970</x>
      <y>820</y>
      <w>130</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
Realized Code Files</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1090</x>
      <y>780</y>
      <w>240</w>
      <h>80</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>10.0;60.0;220.0;10.0</additional_attributes>
  </element>
  <element>
    <id>UMLUseCase</id>
    <coordinates>
      <x>710</x>
      <y>340</y>
      <w>360</w>
      <h>180</h>
    </coordinates>
    <panel_attributes>valign=center
bg=#a0c0ff</panel_attributes>
    <additional_attributes/>
  </element>
</diagram>

Changes to micca/doc/howto/howto.txt.

11
12
13
14
15
16
17


18
19
20
include::dynamics.txt[]

include::processing.txt[]

include::bridge.txt[]

include::codeorg.txt[]




// vim:syntax=asciidoc:







>
>



11
12
13
14
15
16
17
18
19
20
21
22
include::dynamics.txt[]

include::processing.txt[]

include::bridge.txt[]

include::codeorg.txt[]

include::bibliography.txt[]


// vim:syntax=asciidoc:

Changes to micca/doc/howto/intro.txt.

1
2
3
4
5
6
7




8























































9
















































10
11
12
13
14
15
16
17
18
19
..
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
..
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
...
108
109
110
111
112
113
114
115









116






























117
118
119
120
121
122
123
124
125
126
127
128
== Introduction

This paper presents a set of techniques to demonstrate
translating an
https://en.wikipedia.org/wiki/Executable_UML[Executable UML (XUML)]
domain model into a "C" based implementation using `micca`.





* overall workflow scheme























































* Human driven translation
















































* available targets
* model first -- don't hack
* analysis vs translation

=== Complete model

Before translation can be begin,
it is necessary to have a complete model.
That seems like an obvious statement,
but in our usual rush to finish systems there is a natural tendency
................................................................................
does *not* necessarily imply that it is complete in terms
of the services it provides to the system.
Experience shows that models,
like conventional code bases,
benefit from incremental, iterative development.
Call it agile or waterfall or whatever you like,
skilled practitioners of software development do not build systems
in one sequential undertaking.
Development is iterative and the results of one iteration help direct
subsequent efforts.
The usual recommendation is to model core concepts that are central
to the subject matter of the domain and work out from there to more
peripheral concepts.
Of course such recommendations have little to offer in terms of how
to determine what the core concepts of a domain are.
................................................................................
Usually, some doubts enter into the process near the domain boundary
and its interactions with other domains.
This seems to be a property of any collection of logic when exceeding a certain
size (which size is almost never exceeded by the simple examples usually
presented).

However,
domain models are precise and therefore don't have _fuzzy_ parts that
left open for interpretation or dangling for future elaboration.
So we consider the following a _minimal_ set of deliverables that
are required before translation can begin.

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage).

  - Written descriptions of each class, relationship and attribute.
    Writing descriptions of the class model elements is an essential
    aspect of creating the class model and the presence of the
    descriptions indicates that the analyst has thoroughly checked
    the implications of the model.
  - A description of each model-level data type employed in the
    class model.
    The description must define the set of values (either by formula
    or enumeration) that constitute the data type.
* A state model for each class that has non-trivial lifecycle behavior.
  The state models contain:
  - A UML state diagram (in accordance with XUML usage).
    The diagram must show the initial state and any final states.
  - A state transition matrix in which every possible transition
    is defined.
    Every transition not shown on the state model diagram must be
    marked as *CH* (can't happen) or *IG* (ignored).
    It is suggested that ignored events be justified as to the reasoning
    behind them.
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.
* A set of instance operation descriptions for each class
    that defines them, to include:
................................................................................
    Values of referential attributes indicate the relationship instances
    that are part of the initial instance population.
    Using action language to define initial data populations is not
    acceptible.

=== Translation workflow summary

The basic workflow described here for translating an XUML model is:








































. Perform an introspection of the model marking it to show the execution
    characteristics.
. Translate the class model.
. Translate the state models.
. Translate the data flow diagrams or action language to "C" code.
. Construct an initial instance population.
. Construct the bridges between domains.

Each of these areas is discussed below.


// vim:syntax=asciidoc:







>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
<
<







 







|







 







|
|

|


|
>



|






|







|







 







|
>
>
>
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|







|



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
...
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
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
...
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
== Introduction

This paper presents a set of techniques to demonstrate
translating an
https://en.wikipedia.org/wiki/Executable_UML[Executable UML (XUML)]
domain model into a "C" based implementation using `micca`.

* what is micca ???

=== Workflow overview

The following figure shows the overall workflow for creating a system
using modeling and translating with `micca`.

image::micca-translation.pdf[title="Workflow Overview"]

An *Analyst* creates one or more domain models.
Most systems consist of several domains.
During the analysis phase,
the analysts captures the domain requirements in a platform independent
model.
We do not explain how to perform analysis here.
Many books have been written on that subject and are listed in the
<<bibliography,bibliography>>.

When the analysis is complete,
it is transferred to a *Translator*.
The Translator is a human being.
The material transferred (as indicated by the dashed line in the figure)
is a set of diagrams and text which we
discuss <<model-contents,below>>.
Note that no machine readable content is transferred directly to the
translation phase.

The Translator's role in completing the process
is to examine the contents of the domain model materials
and formulate a micca DSL source file that contains a platform
specific configuration of the domain model.
This document is written to explain that one particular step in the overall
workflow (shown in the light blue oval in the diagram).

Once the domain configuration is complete,
`micca` reads the file and captures the platform specfic elements
it contains.
Using this data,
code is generated for the domain.
The code consists of a ``C'' source file and a ``C'' header file.

The source files for all the domains in the system,
along with any bridge code or other conventionally realized code
files are then compiled and linked together to form an executable
for the program.
Also supplied to the build process is the run-time code required
by `micca`.
Much of the code generated by `micca` depends upon or drives
the operation of its run-time code.
For example,
the state machine dispatch that sequences the lifecycles of class instances
is implemented in the run-time code and driven by data supplied in the
domain ``C'' source code.
We do *not* describe here how `micca` or its run-time code operate.
`Micca` and the run-time are fully described
http://repos.modelrealization.com/cgi-bin/fossil/mrtools/wiki?name=MiccaPage[elsewhere].

There are several points of interest in this workflow.

* The tooling for the analysis is completely separated from that of the
  translation.
  Ideally, it would be more convenient to automate the translation
  process by eliminating the human translator.
  In practice, the complexity of UML tooling and specifically the narrow
  use of UML concepts in Executable UML makes that automation
  difficult.
  The solution chosen here is to apply human intelligence to bridge the
  tooling gap.
  We do not consider this any more unusual than applying human
  intelligence to write any other computer program.
* Because a human is involved,
  there are substantial possiblities for tailoring the solution to the
  specfic needs of the target platform.
  This can be quite difficult when attempting the translation with
  generic tooling intented to support a wider array of platforms.
* There is substantial amount of the system that is conventionally coded.
  Bridge code is supplied manually.
  Low level operating system or device specific code is usually required to
  interface to the external world.
  Claims of translation schemes that purport to yield 100% code generation
  should be viewed with skepticism.
* `Micca` is able to externally save it platform specific model population.
  This is used by companion tools, such as
  http://repos.modelrealization.com/cgi-bin/fossil/mrtools/wiki?name=BosalPage[bosal],
  to aid in testing and analyzing the implementation.
* The person who performs the role of Analyst does not have to be the
  same person who performs the role of Translator.
  It is recommended that these two roles be done by different people.
  Having different persons perform the roles adds two important
  project checks:
  ** More than one person becomes familiar with the content of the domain model.
  ** The skill sets required to be a good Translator are quite different than
    those required of a good Analyst.
    Specialization can increase the efficiency of accomplishing the work.

+
Experience has shown that all models have small logical inconsistencies
and errors in them before they are translated.
Such errors or not an indictment of the Analyst's talents.
It is important that the Translator and the Analyst communicate
and correct the inevitable errors that will be found in the first
attempts to translate the model.
The separation of analysis from translation is intended to separate the problem
essentials from the implemenatation artifacts.
It is *not* intended to erect a virtual wall across which political battles can
be waged with one side contending the models can't be made to run
and the other side contending that they are perfectly translatable.

=== Available targets
Available targets



=== Complete model

Before translation can be begin,
it is necessary to have a complete model.
That seems like an obvious statement,
but in our usual rush to finish systems there is a natural tendency
................................................................................
does *not* necessarily imply that it is complete in terms
of the services it provides to the system.
Experience shows that models,
like conventional code bases,
benefit from incremental, iterative development.
Call it agile or waterfall or whatever you like,
skilled practitioners of software development do not build systems
in one strictly sequential undertaking.
Development is iterative and the results of one iteration help direct
subsequent efforts.
The usual recommendation is to model core concepts that are central
to the subject matter of the domain and work out from there to more
peripheral concepts.
Of course such recommendations have little to offer in terms of how
to determine what the core concepts of a domain are.
................................................................................
Usually, some doubts enter into the process near the domain boundary
and its interactions with other domains.
This seems to be a property of any collection of logic when exceeding a certain
size (which size is almost never exceeded by the simple examples usually
presented).

However,
domain models are precise and therefore don't have _fuzzy_ parts that stubbed
out or left open for interpretation or dangling for future elaboration.
So we consider the following a _minimal_ set of deliverables that
are required before translation can begin.[[model-contents]]

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage of class
    diagram constructs).
  - Written descriptions of each class, relationship and attribute.
    Writing descriptions of the class model elements is an essential
    aspect of creating the class model and the presence of the
    descriptions indicates that the analyst has thoroughly considered
    the implications of the model.
  - A description of each model-level data type employed in the
    class model.
    The description must define the set of values (either by formula
    or enumeration) that constitute the data type.
* A state model for each class that has non-trivial lifecycle behavior.
  The state models must contain:
  - A UML state diagram (in accordance with XUML usage).
    The diagram must show the initial state and any final states.
  - A state transition matrix in which every possible transition
    is defined.
    Every transition not shown on the state model diagram must be
    marked as *CH* (can't happen) or *IG* (ignored).
    It is suggested that ignored events be justified as to the reasoning
    for ignoring them.
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.
* A set of instance operation descriptions for each class
    that defines them, to include:
................................................................................
    Values of referential attributes indicate the relationship instances
    that are part of the initial instance population.
    Using action language to define initial data populations is not
    acceptible.

=== Translation workflow summary

When a language compiler, say a ``C'' compiler, compiles a code file,
it does not produce the code according to the way the program should
have been written if you are a good programmer.
A badly structured piece of source code produces an equally badly
structured output.
The compiler can work only with the what it is given and it must
faithfully produce code, that when executed, accomplishes
the logic contained in the original source.
The compile is unaware of any intent in the code or any higher
order design in the system.

The same is true of translating XUML domain models.
A Translator does not produce code for the model as it would have
come from a good analysis.
The output can only be _derived_ from the model as it was
given by the Analyst.
If the model is overly complex and poorly conceived,
the resulting code will reflect that.

It is most important that the translation do not add or subtract
anything from the logic of the domain model.
The intent of translation is only to add the necessary software
technology to make the domain run on the intended platform.
Consequently,
a Translator tends to pay little attention to the details of
what a domain actually accomplishes.
It is a somewhat rote undertaking.
Rather the focus is on formulating clear and concise program
statements to reflect the actions of the model.
Translation concerns are those of the computing platform and not
those of the subject matter of the domain.

As described previously,
the purpose of this document is to describe a single step in the
overall workflow, namely,
formulating a platform specific domain configuration from the
platform independent modeling material transferred from the
analysis phase
The workflow for formulating the platform specific domain configuration
can be summarized as:

. Perform an introspection of the model, marking it to show the execution
    characteristics.
. Translate the class model.
. Translate the state models.
. Translate the data flow diagrams or action language to "C" code.
. Construct an initial instance population.
. Construct the bridges between domains.

Each of these areas is below in a separate section.


// vim:syntax=asciidoc:

Changes to micca/doc/howto/marking.txt.

1
2
3
4
5
6
7
8
9
== Model marking
Model marking

* marking is analogous to semantic analysis for a language compiler.

* model compiler does not generate the model you should have written.


* mark instance creation/deletion -- both sync and async

<







1

2
3
4
5
6
7
8
== Model marking


* marking is analogous to semantic analysis for a language compiler.

* model compiler does not generate the model you should have written.


* mark instance creation/deletion -- both sync and async