Check-in [604404cd7c]
Not logged in

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

Overview
Comment:Checkpoint on how to translate using micca document. Finished translating dynamics part.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:604404cd7cc6219d43397818b0b6053b2b571460
User & Date: andrewm 2019-02-23 16:24:50
Context
2019-03-11
19:44
Checkpoint on how to translate document. check-in: 00c9bc755a user: andrewm tags: micca-develop
2019-02-23
16:24
Checkpoint on how to translate using micca document. Finished translating dynamics part. check-in: 604404cd7c user: andrewm tags: micca-develop
08:56
Checkpoint on writing a howto document for micca. check-in: 789c3e57bb user: andrewm tags: micca-develop
Changes

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

1
2


3
4
5
6
7
== Translating data
Translating data



* data type translation


// vim:syntax=asciidoc:


>
>





1
2
3
4
5
6
7
8
9
== Translating data
Translating data

* names as "C" identifiers

* data type translation


// vim:syntax=asciidoc:

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

1
2

3
4
5
6






7
8
9
10
11
12
13
..
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
..
70
71
72
73
74
75
76


77
78
79
80
81
82


83
84
85
86
87
88
89
...
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
...
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
...
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
== Translating dynamics


Translating the dynamics of the model requires the least amount of
transformation of the three model facets.
The semantics of the Moore state models used in XUML are directly
mapped to `micca` commands.







For classes with a state model,
add a `statemodel` command to its class definition:

----
class LightBulb {
    # light bulb attributes, etc.
................................................................................
----

For brevity in the following examples,
we assume the `statemodel` command is contained within the appropriate
`class` definition script.

Two things must be defined for a state model.

The states must be defined and the code to execute when the state
is entered is part of that definition.











In this section,
we do not discuss translating the code for state activities.
We consider that in the next section.



To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

["plantuml"]
----
@startuml
hide empty description






[*] --> Off
Off --> On : Turn on
On --> Off : Turn off

Off : ~# code for Off state
On : ~# code for On state
................................................................................
. The body of ``C'' code to execute when the state is entered.

State activity parameters are carried along in the event that
causes the transition _into_ the state.
We discuss states with parameters more below.
Here there are no parameters to the state activity,
so we specify them as empty ({}).



The other aspect of a state model translation is to specify all the state
transitions.
The starting point for translating the state transitions is,
naturally enough, the transition matrix of each state model.
Consider the following simple transition matrix.



[options="header",cols="3*^",title="Light Bulb State Transitions",width="50%"]
|=====
|State / Event  |Turn off       |Turn on
|Off            |IG             |On
|On             |Off            |IG
|=====
................................................................................
You can put all the `transition` command first or mix them around
in any way you wish.
One common organization is to list the _outgoing_ transitions
for a state immediately after the `state` command defining the state.

=== Default transitions

The state model diagram show previously,
only shows transitions to states.
It does not show ignored (IG) or can't happen (CH) pseudo-transitions.
In our translation of the example,
we explicitly stated all the IG transitions.
This can be tedious if there are a lot of these types of transitions
to encode.
So, `micca` allows you to set a default transition.
Any transition _not_ mentioned in a `transition` command is assigned
the default transition.

Normally, the default transition is *CH* (for some very good reasons
that catches many errors).
However,
some state models, assigners in particular, 
ignore most event that do not cause an explicit transition to a state.
Our light bulb example also ignores events.
To change the default transition,
use the `defaulttrans` command.
Our light bulb example might have been written as:

----
statemodel {
    defaulttrans IG

    state Off {} {
        # code to execute when the Off state is entered.
    }
    transition Off - Turn_on -> On

    state On {} {
        # code to execute when the On state is entered.
    }
    transition On - Turn_off -> Off
}
----




Some find this manner of specifying the state model clearer.
Note also the `defaulttrans` command may appear anywhere and need not
be the first command in the state model definition.

=== Initial state

................................................................................
The `initialstate` command is used to specify the initial starting state
for a state model.
If no `initialstate` command is specified in the state model definition,
then `micca` chooses the first state defined as the initial state.
It is usually wise to specify the initial state, if only for documentation
purposes and to make sure things don't go wrong if the order of
state definitions is changed.
Again,
our light bulb example might have bee written as:

----
statemodel {
    initialstate Off
    defaulttrans IG

    state Off {} {
................................................................................
How initial states get handled is fundamentally an analysis concern.
However,
it is worth repeating here how activities associated with initial states
are handled.
Sometimes, problems with initial state activity execution are
assumed to be translation problems.

There are two ways to create class instances:

. Synchronously, where a state activity requests a class instance be
    created and that instance exists when the invocation of the request
    function completes.
    If that class has a state model,
    the newly created instance is placed in an initial state according to:
    .. the default initial state defined in the `statemodel` script, or
    .. the _initial state requested by the state activity_ performing
        the synchronous creation.
        It is possible when the instance creation is operation is invoked,
        to request a specific state into which the newly created instance
        is to be placed.
        This feature is _not_ often used, but it does exist and it
        has useful cases where it is needed.

+
Regardless of how the initial state of a synchronously created
instance is determined,
the state activity associated with the initial state *is not executed*.

. Asynchronously, where a state activity sends a creation event.
    After signaling a creation event,
    the state activity that performed the signaling continues
    executing and the new class instance is created at some later time.
    When the creation event is eventually dispatched,
    the class instance is created in the _pseudo-initial state_, and the
    creation event causes a transition out of that state.



    There is only one pseudo-initial state, but there may be many
    events that cause a transition out of it (and any event which
    does not cause a transition out of the pseudo-initial state
    will cause a *CH* transition if it is used as a creation event).
    When the transition out of the pseudo-initial state happens
    a new state is entered,
    and the *state activity of the new state is executed*.









We discuss how to specify creation events below.

=== Final states

The lifecycle of some classes is over when they enter a certain state.
Consider the state model below.

["plantuml"]
----
@startuml
hide empty description






[*] --> Starting
Starting --> Requesting : Request
Requesting --> Requesting : Request
Requesting --> Finished : Done
Finished --> [*]

Starting : ~# code for Starting state
Requesting : ~# code for Requesting state
Finished : ~# code for the Finishing state
@enduml
----










----
statemodel {
    # state and transition definitions

    final Finished
}
----
















































































=== Event definitions
Event definitions









































=== Polymorphic events









































Polymorphic events









=== Creation events




























Creation events




==== Assigner state models























































































































Assigner state models






















// vim:syntax=asciidoc:


>




>
>
>
>
>
>







 







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



>
>
>









>
>
>
>
>







 







>
>





|
>
>







 







|
|










|


|












|







>
>
>







 







<
|







 







|


|
|
|




|



|













>
>
>








>
>
>
>
>
>
>
>
|










>
>
>
>
>













>
>
>
>
>
>
>
>
>








>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

<

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

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

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

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



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
..
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
..
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
...
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
...
206
207
208
209
210
211
212

213
214
215
216
217
218
219
220
...
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
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
== Translating dynamics

The second facet of the model to translate is that of the dynamics.
Translating the dynamics of the model requires the least amount of
transformation of the three model facets.
The semantics of the Moore state models used in XUML are directly
mapped to `micca` commands.

Note at this stage we are _not_ translating the action language of the
activities associated with any state model.
State model activities should be left empty at this time so we can
focus on getting the correct structure of states and transitions.
We discuss the translation of the processing in a subsequent section.

For classes with a state model,
add a `statemodel` command to its class definition:

----
class LightBulb {
    # light bulb attributes, etc.
................................................................................
----

For brevity in the following examples,
we assume the `statemodel` command is contained within the appropriate
`class` definition script.

Two things must be defined for a state model.

. The states must be defined.
    The code to execute when the state is entered is part of that definition,
    however we defer that until the skeleton of the state model is
    constructed.
. The transitions between states must be associated to the events which
    cause those transitions.
    When an event is recieved, it causes:
    .. A transition to a state (possibly the same state receiving the event).
    .. Is ignored. This is given the symbol, *IG*.
    .. Is an error conditions because it is logically impossible for
        the event to be received in the state, _i.e._ it can't happen.
        This is given the symbol *CH*.

In this section,
we do not discuss translating the code for state activities.
We consider that in the next section.

=== Defining states

To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

["plantuml"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
}

[*] --> Off
Off --> On : Turn on
On --> Off : Turn off

Off : ~# code for Off state
On : ~# code for On state
................................................................................
. The body of ``C'' code to execute when the state is entered.

State activity parameters are carried along in the event that
causes the transition _into_ the state.
We discuss states with parameters more below.
Here there are no parameters to the state activity,
so we specify them as empty ({}).

=== Defining transitions

The other aspect of a state model translation is to specify all the state
transitions.
The starting point for translating the state transitions is,
naturally enough, the transition matrix of each state model.
Consider the transition matrix for our simple light bulb model.
Each state has a row in the matrix.
Each event has a column in the matrix.

[options="header",cols="3*^",title="Light Bulb State Transitions",width="50%"]
|=====
|State / Event  |Turn off       |Turn on
|Off            |IG             |On
|On             |Off            |IG
|=====
................................................................................
You can put all the `transition` command first or mix them around
in any way you wish.
One common organization is to list the _outgoing_ transitions
for a state immediately after the `state` command defining the state.

=== Default transitions

A state model diagram typically only shows transitions from one state
to another.
It does not show ignored (IG) or can't happen (CH) pseudo-transitions.
In our translation of the example,
we explicitly stated all the IG transitions.
This can be tedious if there are a lot of these types of transitions
to encode.
So, `micca` allows you to set a default transition.
Any transition _not_ mentioned in a `transition` command is assigned
the default transition.

Normally, the default transition is *CH* (for some very good reasons
a default of *CH* catches many errors).
However,
some state models, assigners in particular, 
ignore most events that do not cause an explicit transition to a state.
Our light bulb example also ignores events.
To change the default transition,
use the `defaulttrans` command.
Our light bulb example might have been written as:

----
statemodel {
    defaulttrans IG

    state Off {} {
        # code to execute when the Off state is entered.
    }
    transition Off - Turn_on -> On ; # <1>

    state On {} {
        # code to execute when the On state is entered.
    }
    transition On - Turn_off -> Off
}
----
<1> Note the spaces around the `-` and `->` characters.
This is _syntactic sugar_ intended to be mnemonic of the transition
and is required.

Some find this manner of specifying the state model clearer.
Note also the `defaulttrans` command may appear anywhere and need not
be the first command in the state model definition.

=== Initial state

................................................................................
The `initialstate` command is used to specify the initial starting state
for a state model.
If no `initialstate` command is specified in the state model definition,
then `micca` chooses the first state defined as the initial state.
It is usually wise to specify the initial state, if only for documentation
purposes and to make sure things don't go wrong if the order of
state definitions is changed.

Our light bulb example might have been written as:

----
statemodel {
    initialstate Off
    defaulttrans IG

    state Off {} {
................................................................................
How initial states get handled is fundamentally an analysis concern.
However,
it is worth repeating here how activities associated with initial states
are handled.
Sometimes, problems with initial state activity execution are
assumed to be translation problems.

In XUML, there are two ways to create class instances:

. Synchronously, where a state activity requests a class instance be
    created and that instance exists when the invocation of the create
    request completes.
    If the class has a state model,
    the newly created instance is placed in an initial state according to:
    .. the default initial state defined in the `statemodel` script, or
    .. the _initial state requested by the state activity_ performing
        the synchronous creation.
        It is an option when the instance creation operation is invoked,
        to request a specific state into which the newly created instance
        is to be placed.
        This feature is _not_ often used, but it does exist and it
        has useful cases.

+
Regardless of how the initial state of a synchronously created
instance is determined,
the state activity associated with the initial state *is not executed*.

. Asynchronously, where a state activity sends a creation event.
    After signaling a creation event,
    the state activity that performed the signaling continues
    executing and the new class instance is created at some later time.
    When the creation event is eventually dispatched,
    the class instance is created in the _pseudo-initial state_, and the
    creation event causes a transition out of that state.
    This would be indicated on a state model diagram by outgoing
    arrows from the pseudo-initial state that are labeled with an
    event name.
    There is only one pseudo-initial state, but there may be many
    events that cause a transition out of it (and any event which
    does not cause a transition out of the pseudo-initial state
    will cause a *CH* transition if it is used as a creation event).
    When the transition out of the pseudo-initial state happens
    a new state is entered,
    and the *state activity of the new state is executed*.

The fundamental rule is that a state activity is only executed when a
transition causes the state to be entered.
Creation events cause a transition from the pseudo-initial state into
a new state and therefore the activity of the new state is executed.
Synchronous instance creation does not cause any transition,
but only sets the value of the initial state and thereby determines the manner
in which _subsequent_ events are handled.

We discuss how to specify creation events <<creation-events,below>>.

=== Final states

The lifecycle of some classes is over when they enter a certain state.
Consider the state model below.

["plantuml"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
}

[*] --> Starting
Starting --> Requesting : Request
Requesting --> Requesting : Request
Requesting --> Finished : Done
Finished --> [*]

Starting : ~# code for Starting state
Requesting : ~# code for Requesting state
Finished : ~# code for the Finishing state
@enduml
----

When the *Finished* state is entered and after its state activity has
been executed,
it transitions (with no event label on the arrow) to a final state
which is shown by a black circle with a white halo.
Any instance of a class entering a final state is automatically deleted
by the run-time code.
To indicate a final state,
`micca` uses the `final` command.

----
statemodel {
    # state and transition definitions

    final Finished
}
----

It is possible to have multiple final states.
It is also possible to use the `final` command several times or
to list several states in the invocation of the `final` command.

=== States with parameters

So far,
none of the states we have show has had any parameters.
Events may carry argument values that are available to state activity.
It is a corollary to the way Moore state machines operate that
the parameter signature of any event which causes a transition
_into_ a state must match the parameter signature of the state activity.
Normally, this is an analysis concern and up to the analyst to get
the two signatures to match correctly.
However, `micca` does detect such errors.

Consider our previous state model with the addition that
a *Request* event carries with it a count of the number of items to
request and a size of items to request.

["plantuml"]
----
@startuml
hide empty description
skinparam state {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
}

[*] --> Starting
Starting --> Requesting : Request(count, size)
Requesting --> Requesting : Request(count, size)
Requesting --> Finished : Done
Finished --> [*]

Starting : ~# code for Starting state
Requesting : ~# code for Requesting state
Finished : ~# code for the Finishing state
@enduml
----

We must specify the signature of the *Requesting* state to
show the arguments it receives when entered.

----
statemodel {
    initialstate Starting
    defaulttrans CH
    final Finished

    state Starting {} {
        # code for the Starting state
    }
    transition Starting - Request -> Requesting

    state Requesting {count int size int} {
        # code for the Requesting state
        # two variables, count and size are defined as int's
        # and are available to the code in the state activity
    }
    transition Requesting - Done -> Finished

    state Finished {} {
        # code for the Finished state
    }
}
----

So parameters to a state are given in the second argument of the
`state` command.
That argument is a list of alternating argument name / argument type
pairs.
The argument name will show up as a variable in the generated ``C''
code.
The argument type is a ``C'' type name, in this case, both arguments
were `int` types.
The signature of the *Requesting* state is (in ``C'' terms) `(int, int)`.

=== Event definitions


You might have noticed that there have not been any definitions of
the events.
Usually,
there is no need to define the events of the state model.
`Micca` will find all the event names mentioned in the `transition`
statements and just use them.

However, sometimes it is useful to be able to specify an event.
This is usually the case when an event carries arguments.
So, in the previous example,
we could have specified:

----
statemodel {
    # commands to specify the state model
    # ...

    event Request count int size int

    # other commands to specify the state model
    # ...
}
----

Event specifications are usually not necessary because `micca`
can recognize that a state signature with two integer arguments
is the same signature regardless of what the argument names are.
It is the data types of the arguments that determine the
signature of an event,
_not_ the names given to the arguments.

One reason for defining an event signature has to do with bridging,
which we discuss later.
When you are constructing an event to signal via a bridge and that
event has arguments,
explicitly defining the event in the state model makes the naming
of the arguments explicit in the bridge code.
It's an advanced topic and we discuss it later when we talk about
bridging.

=== Polymorphic events

In XUML,
polymorphism arises when classes participate in a generalization
relationship and the subclasses in the relationship have lifecycles
modeled by state models.
We do not discuss all the aspects of polymorphic events here since
our concern is translation.

The usual convention in model diagrams marks polymorphic events by
pre-pending an asterisk, _i.e._ **Run*.
This is done as an aid in keeping track of things in the model.
`Micca` does not use such conventions.

`Micca` requires that a polymorphic event be defined as part of the
class specification for the superclass.
The event can be given any name
(as long as it can be turned into a ``C'' identifier).
When an event by the same name is consumed
(_i.e._ appears in a transition statement)
in a leaf state model,
`micca` knows, because the name is the same, that the event was polymorphic.

So if a model contains a class, *Torpedo*, which defines a polymorphic event,
*Fire* which takes a parameter of _speed_, it would be specified as:

----
class Torpedo {
    # commands to specify the attributes, etc. of a Torpedo
    # ...

    polymorphic Fire speed float

    # ...
    # other commands to specify a Torpedo
}
----

Defining a polymorphic event is similar in syntax to defining an ordinary
event.
The main difference is that the polymorphic event is defined as part of
the `class` command script and _not_ as part of the `statemodel`.
A child class consumes the polymorphic event,
when an event of the same name as the polymorphic event is used in a
`transition` command within a `statemodel` script.

`Micca` understands that in multi-level generalizations,
polymorphic events not consumed by intermediate level classes are
deferred to child classes.
It also understands all the other rules about polymorphic events and insists
the specification be correct.

=== Creation events [[creation-events]]

Previously,
we briefly discussed creation events in the context of the semantics
of initial states.
A creation event is one which causes an outgoing transition from the
pseudo-initial state.
A creation event appears in a `transition` command just as any other event.
The difference is that the pseudo-initial state has the special name of, `@`.
For example:

----
statemodel {
    # commands to define the state model of the class
    # ...

    transition @ - Go -> Starting

    # ...
    # other commands to define the state model of the class
}
----

In this example,
*Go* is a creation event that causes a transition from the pseudo-initial
state (`@`) to the *Starting* state.
There is nothing particularly special about the *Go* event in this example.
It is signaled to a newly created instance when an asynchronous
instance creation is requested in an activity.
The name of the creation event must be supplied as part of
the process of asynchronously creating an instance.
The event may have parameters or not depending upon what the analytical
model has specified.

==== Assigner state models [[assigner-state-models]]

The nature of some associations between classes is competitive.
The concurrency rules of XUML imply that instances of the relationship
must be created by serializing the actions involved.
This is accomplished by associating a state model to the relationship
itself and those state models are called _assigner_ state models.
The archetypal example for assigner state models is the assignment
of store clerks to service customers:


["plantuml"]
----
@startuml
skinparam class {
    BackgroundColor yellow
    BorderColor black
    ArrowColor black
}
hide methods
hide circle

class Clerk {
    Name : string {I}
}
class Customer {
    Name : string {I}
}
class Service {
    Customer Name : string {I}
    Clerk Name : string {I}
}

Clerk "0..1" - "0..1" Customer
(Clerk, Customer) .. Service : R16
@enduml
----

Since the state model is bound to the association,
it is specified as part of the association definition.
For the previous example:

----
domain operations {
    # commands to specify domain characteristics
    # ...

    association R16 -associator Service Clerk 0..1-0..1 Customer {
        statemodel {
            # state model definition for the R16 assigner
        }
    }

    # ...
    # other commands to specify domain characteristics
}
----

The commands used to specify an assigner state model are the same as
for a class state model, so we do not repeat them here.
The difference is that the `statemodel` command and its definition
script are part of the definition of
the association itself and _not_ to any particular class (indeed in this case,
the *Service* class may have its own state model).

`Micca` will arrange for the assigner to exist before the domain starts
to run and will place the assigner in the inital state as specified by
the `statemodel` script.

==== Multi-assigner models

Usually,
there is only a single instance of an assigner.
This was the case in the previous example.
However,
some competitive relationships are more complicated and are partitioned
by the instances of another class.
Extending our previous example,
it may be the case that a *Clerk* may only service *Customers* when the
*Customer* is in the same department where the *Clerk* works,
_i.e._ a *Clerk* is not allowed to service *Customers* outside of his/her
department.
In that case,
we would need an instance of the assigner for each instance of *Department*.
This is a multi-assigner situation.
The `identifyby` command, used in the script of an association, specifies
that the assigner is a multi-assigner and gives the class which
partitions the instances.

Extending our previous example, we would have:

----
domain operations {
    # commands to specify domain characteristics
    # ...

    association R16 -associator Service Clerk 0..1-0..1 Customer {
        identifyby Department ; # >>> Here, we indicate a multi-assigner
        statemodel {
            # state model definition for the R16 assigner
        }
    }

    # ...
    # other commands to specify domain characteristics
}
----

==== Multi-assigner population

Since there are multiple instances of a multi-assigner,
we must define a population for those instances.
This is accomplished with the `assigner` command within a population.
Again expanding upon our previous example:

----
population operations {
    # commands to specify populations of classes
    # ...

    assigner R16 {
        instance sports_service sports_department
        instance apparel_service apparel_department
        instance garden_service garden_department
    }

    # ...
    # other population commands
}
----

The `assigner` command and the script containing the `instance` commands
define three assigners for service associated with three departments
where *Clerks* work.
Here, `sport_department` _et.al_ are names of instances of the
*Department* class which is the partitioning class for the
multiple assigners.

Note that for single assigners,
no population specification is required since `micca` already knows
how many assigner instances to create (_i.e._ one).


// vim:syntax=asciidoc:

Changes to micca/doc/howto/figures/micca-translation.uxf.

83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
...
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
...
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
...
415
416
417
418
419
420
421
























422
      <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>
................................................................................
    <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>
................................................................................
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/>
................................................................................
      <w>360</w>
      <h>180</h>
    </coordinates>
    <panel_attributes>valign=center
bg=#a0c0ff</panel_attributes>
    <additional_attributes/>
  </element>
























</diagram>







|







 







|
>









|

|



|







 







|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
...
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
...
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
...
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
      <y>380</y>
      <w>160</w>
      <h>100</h>
    </coordinates>
    <panel_attributes>valign=center
bg=yellow
layer=1
Capture Domain As
Platform Specific
Model</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
................................................................................
    <id>UMLGeneric</id>
    <coordinates>
      <x>970</x>
      <y>560</y>
      <w>160</w>
      <h>140</h>
    </coordinates>
    <panel_attributes>Micca Model
Execution Domain
--
bg=light_gray
group=1</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1090</x>
      <y>640</y>
      <w>240</w>
      <h>130</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>10.0;10.0;220.0;110.0</additional_attributes>
  </element>
  <element>
    <id>UMLNote</id>
    <coordinates>
      <x>740</x>
      <y>270</y>
      <w>120</w>
................................................................................
bg=orange</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLPackage</id>
    <coordinates>
      <x>1000</x>
      <y>610</y>
      <w>100</w>
      <h>70</h>
    </coordinates>
    <panel_attributes>Run Time Code
bg=yellow
group=1</panel_attributes>
    <additional_attributes/>
................................................................................
      <w>360</w>
      <h>180</h>
    </coordinates>
    <panel_attributes>valign=center
bg=#a0c0ff</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>UMLGeneric</id>
    <coordinates>
      <x>1070</x>
      <y>890</y>
      <w>170</w>
      <h>40</h>
    </coordinates>
    <panel_attributes>valign=center
Other Domain Code Files</panel_attributes>
    <additional_attributes/>
  </element>
  <element>
    <id>Relation</id>
    <coordinates>
      <x>1170</x>
      <y>800</y>
      <w>180</w>
      <h>110</h>
    </coordinates>
    <panel_attributes>lt=-&gt;&gt;
"C" Code</panel_attributes>
    <additional_attributes>10.0;90.0;160.0;10.0</additional_attributes>
  </element>
</diagram>

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

31
32
33
34
35
36
37
38

39
40
41
42
43
44
45
..
75
76
77
78
79
80
81
82

83
84
85
86
87
88
89
...
199
200
201
202
203
204
205


206
207
208
209
210
211
212
...
216
217
218
219
220
221
222



223
224
225
226
227
228
229
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,
................................................................................
  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.
................................................................................
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
  - A written description of the operation function and interface.
  - The processing of the domain operation presented as action language
    or a data flow diagram.


* A set of external entity descriptions that include:
  - A description of the logical dependencies allocated to the external
    entity by the domain.
  - A description of the function and interface for each operation
    performed by the external entity.
    This must include whether the operation is considered as synchronous
    or asynchronous in its behavior.
................................................................................
    The preferred manner of specification is via tabluar layout in a
    purely data oriented fashion.
    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.







|
>







 







|
>







 







>
>







 







>
>
>







31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
..
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
...
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
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 and is _derived_
from 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,
................................................................................
  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 wide array or the lowest common
  denominator 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.
................................................................................
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
  - A written description of the operation function and interface.
  - The processing of the domain operation presented as action language
    or a data flow diagram.
* For any mathematically dependent attribute, the action language
    formula required to compute the value of the attribute.
* A set of external entity descriptions that include:
  - A description of the logical dependencies allocated to the external
    entity by the domain.
  - A description of the function and interface for each operation
    performed by the external entity.
    This must include whether the operation is considered as synchronous
    or asynchronous in its behavior.
................................................................................
    The preferred manner of specification is via tabluar layout in a
    purely data oriented fashion.
    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.

=== Model facets
Model facets -- three facets of the model. Translation order

=== 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.

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

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
..
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
..
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
124
125
126
127
128
129
130



131
132
133
134
135
136
137
138
139
140
141
142
143
144
that is then interpreted (or further compiled) at run time to
execute the program.
The many different approaches all have trade-offs,
yielding different characteristics,
that make them more or less suitable for a particular problem.

Most compilers use a semantic checking and analysis phase.
During this phase the compiler insures that language statement which are
syntactically correct are actually meaningful within the rules of
the way the language works.
In all language systems,
it is possible to have correct statements in the language that have
no meaning.
For example,
if the language requires that variables be declared before they are used,
an expression that refers to an undeclared variable has no meaning
even if that expression was correctly composed of valid language tokens..

Language compilers also typically examine the execution characteristics
of the program being compiled.
Internally, a flow graph of execution is often generated and many of
the optimizations performed by a compile are operations that transform
a flow graph into a semantically equivalent one that minimizes
some aspect of the resulting code.
For example it is possible to examine the flow graph of a function
that contains a loop construct and determine that some code piece
may be _lifted_ outside of the loop and still achieve the same result.

It should come as no surprise then that
translating an XUML model requires analogous examination.
Fortunately,
the situation is much simpler for a model than a compiled language.
For the case of a model,
a single pass over the processing description of the activities
is sufficient to generate the introspection we need.
We call this analysis of the model processing with the goal of
................................................................................
It is important to understand the purpose of the model marking.
The first step of model translation is to cast the platform
independent model into a platform dependent model.
`Micca` operates off of a platform dependent specification of
the domain properties
and supplies a specific set of mechanisms by which model semantics
may be realized as an actual implementation targeted at a
specific scale of computing.
In the process of transforming the model into a platform specific
description,
logical aspects of the model must be made concrete in terms
supported by the platform specific model.

For example,
models specify the data types of attributes as a set of values.
................................................................................
the specific use case of the model rather than necessarily providing
a general capability that would support any model.
For example,
if the model activities never access the referential attributes
of a class in a descriptive manner,
then such attributes need not be stored since the underlying
platform specifics supplied by `micca` handle implementing
the referential implications of the modeling language.

The importance of model marking is then to gather the information
about what the activities of the model actually do so as to make
informed decisions about how to map those activities onto the
platform specific mechanisms provide by `micca`.

=== Model metadata
................................................................................

==== Relationship metadata

For relationships,
we are interested in the navigation of relationships by the activities
in the model. Specifically:




* The direction of navigation of a relationship between the participating
  classes.
* Navigating generalization relationships from supertype to some subtype.
* Navigating generalization relationships from a subtype instance to
  its corresponding supertype instance.
* Subtype migration of one subtype into being instance of a different
  subtype.

=== Marking mechanics

The following is the suggested way to obtain and record the model metatdata
is:

* Start with a clean printout of the class diagram of the model on the







|
|
|






|




|


|



|







 







|







 







|







 







>
>
>





<
<







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
..
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
..
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138


139
140
141
142
143
144
145
that is then interpreted (or further compiled) at run time to
execute the program.
The many different approaches all have trade-offs,
yielding different characteristics,
that make them more or less suitable for a particular problem.

Most compilers use a semantic checking and analysis phase.
During this phase the compiler insures that language statements,
which are syntactically correct,
are actually meaningful within the rules of the way the language works.
In all language systems,
it is possible to have correct statements in the language that have
no meaning.
For example,
if the language requires that variables be declared before they are used,
an expression that refers to an undeclared variable has no meaning
even if that expression was correctly composed of valid language tokens.

Language compilers also typically examine the execution characteristics
of the program being compiled.
Internally, a flow graph of execution is often generated and many of
the optimizations performed by a compiler are operations that transform
a flow graph into a semantically equivalent one that minimizes
some aspect of the resulting code.
For example, it is possible to examine the flow graph of a function
that contains a loop construct and determine that some code piece
may be _lifted_ outside of the loop and still achieve the same result.

It should come as no surprise that
translating an XUML model requires analogous examination.
Fortunately,
the situation is much simpler for a model than a compiled language.
For the case of a model,
a single pass over the processing description of the activities
is sufficient to generate the introspection we need.
We call this analysis of the model processing with the goal of
................................................................................
It is important to understand the purpose of the model marking.
The first step of model translation is to cast the platform
independent model into a platform dependent model.
`Micca` operates off of a platform dependent specification of
the domain properties
and supplies a specific set of mechanisms by which model semantics
may be realized as an actual implementation targeted at a
specific type of computing platform.
In the process of transforming the model into a platform specific
description,
logical aspects of the model must be made concrete in terms
supported by the platform specific model.

For example,
models specify the data types of attributes as a set of values.
................................................................................
the specific use case of the model rather than necessarily providing
a general capability that would support any model.
For example,
if the model activities never access the referential attributes
of a class in a descriptive manner,
then such attributes need not be stored since the underlying
platform specifics supplied by `micca` handle implementing
the referential implications of an XUML model.

The importance of model marking is then to gather the information
about what the activities of the model actually do so as to make
informed decisions about how to map those activities onto the
platform specific mechanisms provide by `micca`.

=== Model metadata
................................................................................

==== Relationship metadata

For relationships,
we are interested in the navigation of relationships by the activities
in the model. Specifically:

* Creating, deleting or updating the instances of a relationship.
    This includes subtype migration of one subtype into being instance of a
    different subtype.
* The direction of navigation of a relationship between the participating
  classes.
* Navigating generalization relationships from supertype to some subtype.
* Navigating generalization relationships from a subtype instance to
  its corresponding supertype instance.



=== Marking mechanics

The following is the suggested way to obtain and record the model metatdata
is:

* Start with a clean printout of the class diagram of the model on the