Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: f3a983d3c5e643d7cc16e68798ed7cff650a0923 (plain) (blame)
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
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
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
FeaturizerModel eTriceROOMLanguage
	imports "etrice.featurizer"


Package ROOMLanguage
	description '''The Real Time Object Oriented Modeling (ROOM)'''
	text '''
		eTrice comprises several models:

		- the ROOM model (*.room) -- defines model classes and the logical structure of the model
		- the Config model (*.config) -- defines configuration values for attributes
		- the Physical model (*.etphys) -- defines the structure and properties of the physical system
		- the Mapping model (*.etmap) -- defines a mapping from logical elements to physical elements
		
		
		In the following diagram the models and their relations are depicted. The meaning of the arrows is: uses/references.

		![Model overview](images/080-models.jpg)
	'''
	contains LogicalModel 
	contains PhysicalModel 
	contains MappingModel
	contains ConfigModel
;

Feature AnnotationType
description '''AnnotationTypes can be used to tag ROOM classes for further custom processing'''
text '''
	They provide the ability to associate custom properties to ROOM classes, that adjust or toggle features, like generation or the runtime behavior.
	eTrice comes with predefined annotations, which can be found in Annotations.room within the eTrice modellib.

	See section Annotations for further reading.
''' 
help '''
	```room
	/** documentation */
	AnnotationType AnnotationName {
		target = ActorClass
		mandatory attribute name: ptCharacter
		optional attribute name: ptInteger
	}
	```
'''
stable
;

Feature Annotation
description '''An Annotation can be attached to a ROOM class to specify the properties of its AnnotationType'''
text '''
	It refers to an AnnotationType and may have to pass key value pairs. Its notation is similar to Java:

	```room
	@AnnotationType1
	@AnnotationType2(key1="STRING", key2=3, ...)
	```

	See section Annotations for further reading.
'''
example '''
	```room
	import etrice.api.annotations.BehaviorManual

	ActorClass ComponentAbstraction {
		Interface {
			conjugated Port port1: Protocol1
		}
		Structure {
			external Port port1
		}
		Behavior {
			// custom/external state machine implementation
			@BehaviorManual
		}
	}
	```
'''
isOfType AnnotationType
stable
;

Feature Inheritance
	description '''A class can specify a single super class and inherits elements from the super class hierarchy'''
	text '''
		When a ROOM class specifies a super class, it generally inherits all elements and properties.
		In several cases, it is possible, to override these inherited elements. Generally, eTrice has two semantics of overriding: refinement and replacement.
		Refinement is used in most cases (e.g. StateMachine) and realizes an extension of the overridden elements.
		In this case, if a sub class overrides a piece of logic from a super class, it will always be executed subsequently to the inherited.
		Contrary to this, replacement is applied to overridden Operations, similar to programming languages C++ and Java.

		A formal definition of several variants of overriding is given below:
		
		- early or late resolve - if element is overridden, which one should the super class use by default - own or override?
		- replacing or refining - ignore inherited code or prepend inherited code automatically?
		- (non-)accessible - if element is overridden, is super class' original accessible from sub class? E.g. super.foo()
		- implicit or explicit - does it use a distinct model element or keyword?
		
		
		Examples from programming languages:
		C++ virtual function and Java override  <==> accessible, explicit, late, replacing
		C++ function redefine <==> accessible, implicit, early, replacing
		C++ destructor <==> late, refining\\
		
		eTrice override of model elements:
		Operations (C generation)  <==> non-accessible, explicit, late, replacing
		Operations (Java generation) <==> accessible, explicit, late, replacing
		State and Transitions <==> non-accessible, explicit, late, refining
		ctor/dtor <==> non-accessible, implicit, late, refining
		StateMachine <==> non-accessible, implicit, late, refining
		UserCode <==> non-accessible, implicit, late, refining
	'''
	example |||
		```room
		ActorClass ActorSubClass extends ActorBaseClass {
			// inherits all elements from super type hierarchy
		}
		
		ActorClass ActorBaseClass {
			Interface {
				Port port1 : ProtocolBaseClass
			}
			Structure {
				Attribute attribute1 : uint32
			}
			Behavior {
				Operation operation1() '''
					return;
				'''
			}
		}
		
		ProtocolClass ProtocolSubClass extends ProtocolBaseClass {
			// inherits all elements from super type hierarchy
		}
		
		ProtocolClass ProtocolBaseClass {
			incoming {
				Message message1()
			}
		}
		
		DataClass DataSubClass extends DataBaseClass {
			// inherits all elements from super type hierarchy
		}
		
		DataClass DataBaseClass {
			Attribute attribute1 : uint32
		}
		```
		|||
	prototype	
;

Feature PhysicalModel
	description '''The PhysicalModel defines the setup of your nodes with their attributes like threads and mode of execution'''
	text '''
		The model describes the physical view of your system:

		```etphys
		PhysicalSystem PhysSys1 {
			NodeRef nodeRef1 : NodeClass1
			NodeRef nodeRef2 : NodeClass2
		}
		```

		The central element is a NodeClass, that models the executional aspects of a device (node).
		At first, it can be associated with a RuntimeClass, which specifies if your device supports multiple threads.
		'priomin' and 'priomax' define the range of priorities, that can be assigned to threads.

		```etphys
		NodeClass NodeClass1 {
			runtime = RuntimeClass1
			priomin = -10
			priomax = 10

			// Thread definitions ...
		}

		RuntimeClass RuntimeClass1 {
			model = multiThreaded // or singleThreaded
		}
		```

		A thread has to specify the following properties:
		
		- **execmode**: defines the execution type, see more at ExecutionType
			- blocked: message-driven only, thread wakes up if message arrives and is put to sleep after all action is done
			- polled: data-driven only, thread is executed cyclic. The 'interval' property is mandatory in this case.
			- mixed: combines both execution types

		- **msgblocksize**: the size in bytes of a message
		- **msgpoolsize**:  the amount of messages, that the thread's message queue can store
		
		Note: 'msgblocksize' and 'msgpoolsize' also apply to the polled execution due the internal implementation via message passing.
		 The size of the message queue can be calculated as follows: msgpoolsize * msgblocksize bytes 

		```etphys
		DefaultThread ThreadMessaging {
			execmode = polled
			prio = 0
			stacksize = 1024
			msgblocksize = 32
			msgpoolsize = 10
		}

		Thread ThreadPolled {
			execmode = polled
			prio = 0
			interval = 100ms
			stacksize = 1024
			msgblocksize = 32
			msgpoolsize = 10
		}
		```
		
		![Overview of PhysicalModel](images/300-PhysicalModelOverview.png)
	'''
	stable
;

Feature MappingModel
	description '''The MappingModel describes the mapping of elements of the LogicalModel to elements of the PhysicalModel'''
	text '''
		It enables the complete decoupling of the LogicalModel and the PhysicalModel, thus providing a maximum flexibility and reuse for the models.
		
		The model starts with an import part, where you can import .room and .etphys models. They must contain at least one LogicalSystem and one PhysicalSystem.
		A Mapping entry puts both in relation, meaning that all sub systems of the LogicalSystem will be distributed to the nodes of the PhysicalSystem.
		This is carried out by a SubSystemMapping, that maps a SubSystemRef (logical node) to a NodeRef (physical node).
		In the next step, ThreadMappings provide the same action for the logical and physical threads.

		```etmap
		MappingModel PingPongMapping {
			import PingPong_Model.LogSys
			import GenericPhysicalModel.PhysSys1
		
			Mapping LogSys -> PhysSys1 {
				SubSystemMapping subSystemRef -> nodeRef1 {
					ThreadMapping defaultThread -> PhysicalThread1
				}
			}
		
		}
		```
	'''
	uses LogicalSystem
	uses SubSystemRef
	uses PhysicalModel
	stable
;

Feature ConfigModel
	description '''The ConfigModel describes the Attribute configuration of ActorInstances and PortInstances. '''
	text '''
		The scope of this model is the configuration of Attributes of the LogicalModel.
		Thus it provides enhanced capabilities for assigning default values to Attributes, which are:
		
		- type safe value assignment
		- setting on class level
		- setting on instance level
		
		Values defined for class attributes are used for all instances unless there is an instance value configured for the same attribute.
		The configuration is available for actors and ports, thus ActorClasses/ActorRefs and ProtocolClasses/Ports.

		```etconfig
		ConfigModel ExampleConfig {
			import Example.*

			ActorClassConfig ActorClass1 {
				Attr attribute1 = 4
			}

			ActorInstanceConfig LogSys/subsysRef/actor1 {
				Attr attribute1 = 7
			}
		}
		```
	'''
	uses Attribute
	stable
;

Feature LogicalModel
	description '''The LogicalModel describes the logical structure and behavior of a ROOM application'''
	text '''
		The ROOM model defines DataTypes, ProtocolClasses, ActorClasses, SubSystemClasses and LogicalSystems.
		Thereby the three latter form a hierarchy. The LogicalSystem is the top level element of the structure. 
		It contains references to SubSystemClass elements. The SubSystemClass in turn contains 
		references to ActorClass elements which again contain (recursively) references to 
		ActorClass elements. The complete structural hierarchy implies a tree which has the 
		LogicalSystem as root and where each reference stands for a new node with possibly further 
		branches.
	'''
	contains LogicalSystem
	contains SubSystemClass
	contains ActorClass
	contains ProtocolClass
	contains DataType
	contains AnnotationType
	
	stable
	;

Feature LogicalSystem
	description '''The LogicalSystem is the topmost structural class. It assembles a distributed system by means of sub systems'''
	text '''
		It describes the logical topology of your distributed system and is composed of sub systems (SubSystemRefs). Thus it is the notationally root of every instance path or actor hierarchy.
	'''
	help '''
		```room
		/** Documentation */
		LogicalSystem systemName {
			SubSystemRef ...
		}
		```
	'''
	contains SubSystemRef
	contains Annotation
	stable
;

Feature ActorClass
	description '''An actor is the basic structural building block for building systems with ROOM'''
	
	text '''
		An ActorClass consists of three main parts:
		
		- **Interface** (external interface) specifies the communication to 'outside' actors and consists of Ports.
		- **Structure** (internal interface) contains Ports, Attributes and ActorRefs. These elements are accessible from the Behavior part of the actor (in contrary to the external interface above). An ActorClass can be composed of other actors again by declaring ActorRefs. Also this part declares the connection of ports in form of Bindings and LayerConnections.
		- **Behavior** is described by the StateMachine. It can receive and send messages from the ports, declared in the Structure above. The Attributes can be used to store data during an state transition. Furthermore it is possible to declare Operations. They can be used to define reusable logic, that is invoked during a state transition.
		
		
		![ActorClass](images/040-ActorClass.png)

		```room
		 ActorClass ExampleActorClass {
			 Interface {
				 Port port1: ProtocolClass1
				 Port port4: ProtocolClass1
			 }
			 Structure {
				 external Port port1
				 conjugated Port port2: ProtocolClass1
				 conjugated Port port3: ProtocolClass1
				 
				 ActorRef ActorRef_A: ActorClass2
				 ActorRef ActorRef_B: ActorClass3
				 
				 Binding port2 and ActorRef_A.port5
				 // ...
			 }
			 Behavior {
				 // ...
			 }
		 }
		```
	'''
	
	example ''''''
	help |||
		```room
		// prefixes: abstract and (eventdriven, datadriven, async, sync)
		/** An eventdriven ActorClass by default */
		ActorClass ActorName {
			Interface {
				Port port1 ...
				SPP spp1 ...
			}
			/** Documentation */
			Structure {
				usercode1 ''' '''
				usercode2 ''' '''
				usercode3 ''' '''
				external Port port1
				Port internalPort2 ...
				ActorRef ...
				Attribute ...
				
				ServiceImplementation of spp1
				Binding ...
				LayerConnection ...
			}
			/** Documentation */
			Behavior {
				ctor ''' /* constructor */ '''
				dtor ''' /* destructor */ '''
				Operation ...
				StateMachine ...
			}
		}
		```
	|||
	
	contains ExecutionType
	contains ActorRef
	contains Port
	contains SAP
	contains SPP
	contains ServiceImplementation
	contains Binding
	contains LayerConnection
	contains Attribute
	contains Operation
	contains StateMachine
	contains Annotation
	uses Inheritance
	stable
;

Feature SubSystemClass
	description '''A SubSystem is the topmost building block of the executable part of an system'''
	text '''
		It represents a class for an logical node in a distributed system. An instantiation translates to an executable application, that runs on a node or process.
		A SubSystemClass is the structural starting point of an ROOM application. Thus it declares the topmost actor instances (ActorRefs).
	'''
	help '''
		```room
		/** Documentation */
		SubSystemClass SubSystemName {
			ActorRef ...
			Binding ...
			LayerConnection ...
		
			LogicalThread threadName
			ActorInstanceMapping ...
		}
		```
	'''
	contains ActorRef
	contains Binding
	contains LayerConnection
	contains Annotation
	stable
;
	


Feature StateMachine
	description '''A StateMachine describes the state based, event driven behavior of an ActorClass'''
	text '''
		In ROOM each actor class can implement its behavior using a state machine. Events occurring at the end ports of an actor will
		be forwarded to and processed by the state machine. Events possibly trigger state transitions.
		
		ROOM state machines are hierarchical finite state machines. That means that each state in the state graph can contain another state graph.
		This is possible to arbitrary depth.

		A state graph consists of
		
		* states
		* transitions
		* transition points
		* choice points
		* initial point
		
		![PingPongReceiverFSM](images/300-PingPongReceiverFSM.png)
		
	'''
	help '''
		Open the **graphical diagram editor**:
		
		* Press `ALT+B` (having focus on an *ActorClass*)
		* Outline view -> Right click on an *ActorClass* -> Edit Behavior
		
		```room
		/** Documentation */
		StateMachine {
			...
		}
		```
	'''
	uses Inheritance
	contains StateGraphNode
	contains Transition
	stable
;

abstract Feature StateGraphNode
	description '''A StateGraphNode is an abstract node of the state graph'''
	text '''
		A StateGraphNode can be a State, a TransitionPoint, a ChoicePoint or an InitialPoint.
	'''
	uses Inheritance
	stable
;

abstract Feature State
	description '''A State can be a plain State or a RefinedState'''
	text '''
		A State can be a plain State or a RefinedState.
	'''
	uses Inheritance
	isA StateGraphNode
	stable
;

Feature SimpleState
	description '''A State is a node in the state graph representation of the state machine'''
	text '''
		A State has optional 'entry' and 'exit' codes. The entry code is executed when the state is entered, the exit code is executed
		when it is left. In the case of an data driven (also known as polled) state machine, there also is a 'do' action code.
		The do code is executed for the active state in each polling cycle.
		A state can have a sub state machine. Starting at the top level state machine the states with their optional sub state machines
		form a tree which is called a 'hierarchical state machine'.
		A state machine always is in exactly one state which can only be a leaf state, i.e. a state which has no sub state machine.
	'''
	help keyword "State" |||
		```room
		ActorClass Example {
			//...
			Behavior {
				StateMachine {
					Transition init: initial -> Standby
					Transition tr0: Standby -> Running {
						triggers {
							<timeout: to>
						}
					}
					Transition tr1: Running -> Stopped {
						triggers {
							<timeout: to>
						}
					}
					State Standby {
						entry '''
							to.startTimeout(200*10);'''
					}
					State Running {
						entry '''
							controllers.start();
							to.startTimeout(200*10);'''
					}
					State Stopped {
						entry '''controllers.stop();'''
					}
				}
			}
		}
		```
	|||
	uses Inheritance
	uses StateMachine
	isA State
	stable
;

Feature RefinedState
	description '''A RefinedState refines a State of one of the Actor's base class state machines'''
	text '''
		A State can be a plain State or a RefinedState.
	'''
	help |||
		```room
			RefinedState BaseState {
				exit '''// this is derived exit code'''
				subgraph {
					// add a sub state machine
					Transition init: initial -> state0 { }
					State state0
				}
			}
		```
	|||
	uses Inheritance
	uses StateMachine
	isA State
	stable
;

Feature ChoicePoint
	description '''a choice point is the state machine counterpart of a conditional statement'''
	text '''
		A ChoicePoint in ROOM has one incoming transition and an arbitrary number of outgoing transitions.
		One of the outgoing transitions has no condition (a ContinuationTransition). It is the default branch that is taken
		if none of the transition conditions evaluated to true. All other transitions going out from the ChoicePoint
		are CPBranchTransitions which have a mandatory condition (keyword 'cond'). The evaluation order of the conditions
		is not deterministic.
	'''
	help |||
		```room
			StateMachine {
				State state0
				State state1
				State state2
				State state3
				TransitionPoint tr4
				ChoicePoint cp0
				Transition init0: initial -> state0
				Transition tr0: state0 -> state1 {
					triggers {
						<in1: p0>
					}
				}
				Transition tr1: state1 -> cp cp0 {
					triggers {
						<in1: p0>
					}
				}
				Transition tr2: cp cp0 -> state3
				Transition tr3: cp cp0 -> state2 {
					cond '''true'''
				}
				Transition tr5:  my tr4 -> state0 {
					triggers {
						<in2: p0>
					}
				}
			}
		```
	|||
	isA StateGraphNode
	uses ContinuationTransition
	stable
;

abstract Feature TrPoint
	description '''a TrPoint can be an EntryPoint, an ExitPoint or a TransitionPoint'''
	text '''text'''
	help |||a TrPoint is an abstract element|||
	isA StateGraphNode
	stable
;

Feature TransitionPoint
	description '''a transition point is the starting point of transitions that trigger for any state of this state machine'''
	text '''text'''
	help |||
		```room
			StateMachine {
				TransitionPoint tp1
				Transition tr1: my tp1 -> my tp1 {
					triggers {
						<msg: port>
					}
				}
			}
		```
	|||
	isA TrPoint
	stable
;

Feature EntryPoint
	description '''an entry point is an explicit entry point in a sub state machine to which transitions in the parent state graph can connect'''
	text '''text'''
	help |||
		```room
			StateMachine {
				State state0 {
					subgraph {
						State state0
						EntryPoint ep0
						ExitPoint ep1
						Transition tr0: my ep0 -> state0
						Transition tr1: state0 -> my ep1 {
							triggers {
								<in1: p0>
							}
						}
					}
				}
				State state1
				Transition init0: initial -> ep0 of state0
				Transition tr0: ep1 of state0 -> state1
			}
		```
	|||
	isA TrPoint
	stable
;

Feature ExitPoint
	description '''an exit point is an explicit exit point in a sub state machine from which transitions in the parent state graph can start'''
	text '''text'''
	help |||help|||
	isA TrPoint
	stable
;

Feature Transition
	description '''A Transition is an edge in the state graph representation of the state machine'''
	text '''
		A transition connects StateGraphNodes in a state graph. A transition is allowed to connect a state or a transition point with itself.
		Transition points can only be targets of transitions originating from the same transition point.
		The initial point is the source of exactly one transition. In the textual model it is present only in an implicit way.
	'''
	help |||
		```room
			Transition init: initial -> Standby
			Transition tr0: Standby -> Running {
				triggers {
					<timeout: to>
				}
			}
		```
	|||
	uses Inheritance
	stable
;

Feature InitialTransition
	description '''the initial transition is used to identify the initial state'''
	text '''The initial transition connects the initial point to a state. There can be at most one initial transition
		in a state machine. Under special circumstances the initial transition can be omitted.
	'''
	help |||Transition init: initial -> state0|||
	isA Transition
	stable
;

Feature GuardedTransition
	description '''the guarded transition is used by data driven state machines to trigger state transitions'''
	text '''In data driven state machines guarded transitions fire whenever the guard condition evaluates to true.
		The evaluation is performed in each polling cycle.
	'''
	help |||
		Transition tr: running -> running {
			guard '''data_counter_finish.finish == true && data_finish_flag == false'''
			action '''++counter;'''
		}
	|||
	idea
;

Feature ContinuationTransition
	description '''the continuation transition is a transition with just an optional action code'''
	text '''A continuation transition is used as default branch of a choice point or as outgoing transition of an entry point'''
	help '''
		State running {
			subgraph {
				EntryPoint ep0
				State active
				Transition tr0: my ep0 -> active
			}
		}
	'''
	isA Transition
	idea
;

Feature CPBranchTransition
	description '''a choice point branch transition is an outgoing transition from a choice point and is traversed if its conditions is evaluated to true'''
	text '''A choice point together with its outgoing transitions can be thought of as a if, else-if, else cascade in traditional
		programming languages. The choice point branch transition corresponds to an if clause while the final else is modeled as
		a continuation transition. Coming from a choice point, a choice point branch transition is traversed whenever its
		condition evaluates to true. No order of evaluations is guaranteed.
	'''
	help |||
		Transition tr3: cp cp0 -> state1 {
			cond '''0<=counter && counter<3'''
		}
	|||
	isA Transition
	idea
;

Feature TriggeredTransition
	description '''a triggered transition is used in event driven state machines to trigger state transitions'''
	text '''text'''
	help |||help|||
	isA Transition
	stable
;

Feature SubSystemRef
 	description '''A Sub System Reference is an instance of an SubSystemClass'''
 	text '''
		It represent a logical node in the structural view of a distributed system. An instantiation translates to an executable application, that runs on a node or process.
			
		To be executable, a SubSystemRef has first to be mapped to a physical node, which defines the executional properties.
		A physical node is denoted by a NodeClass and NodeRef in the PhysicalModel. The mapping is defined in the MappingModel.

	'''
 	help '''
		```room
		/** Documentation */
		SubSystemRef subSystemName: SubSystemClass1
		```
	'''
 	isOfType SubSystemClass
 	stable
;

abstract Feature Replication
	description '''Replication is mechanism for multi-instantiation for ActorRefs and Ports'''
	text '''
		ActorRefs and Ports can be instantiated several times under the same name. The notation is similar to arrays in programming languages.
		
		This possibility provides an elegant way of scaling of your system without redundancy.

		```room
		ActorRef sensor : Sensor 			// one instance
		ActorRef sensor[1] : Sensor			// one instance
		ActorRef sensorArray[5] : Sensor	// five instances  
		```
		
		Replication can also applied to Ports. One use case is to establish a communication with multiple actors through one port interface.
		```room
		Port service[5] : TimingService 	// five instances
		Port service[*] : TimingService		// automatic, as many as needed
		```
	'''
stable
;

Feature ActorRef
	description '''An ActorRef is an instance of an ActorClass'''
	text '''
		- ActorClass: The type of the ActorRef
		- Multiplicity: The number of instances. A number greater than one can be seen as an array of instances
		- Reference Type: Can be fixed or optional. Fixed requires an integer multiplicity and results in an static instantiation with an fixed number of instances during runtime . Optional denotes an dynamic instantiation, where ActorRefs can be created in arbitrary number during runtime. In this case, the multiplicity has to be set to '*'
	'''
	example '''
		```room
		SubSystemClass SubSystemExample {
			ActorRef mainActor : ActorClassExample
			
			LogicalThread default_thread
		}
		
		ActorClass ActorClassExample {
			Structure {
				ActorRef sender : Sender
				ActorRef receiver : Receiver
				
				Binding receiver.port and sender.port
			}
		}
		
		ActorClass ActorClassExampleReplicated {
			Structure {
				ActorRef sender[3]: Sender
				ActorRef receiver[3] : Receiver
				
				Binding receiver.port and sender.port
				/* Equivalent to:
				 *  Binding receiver[1].port and sender[1].port
				 *  Binding receiver[2].port and sender[2].port
				 * ....
				 */		
			}
		}
		```
		
		![ActorRef instance diagram](images/300-ActorRefInstanceDiagram.jpg)

		Instance hierarchy of ActorRef Example (*System(System)* not shown in code snippet)
		
	''' 
	help '''
		```room
		/** Documentation */
		ActorRef actorName: ActorClass1
		/** A replicated actor of size 4 */
		ActorRef actorName[4]: ActorClass1
		/** A dynamic actor */
		optional ActorRef actorName[*]: ActorClass1
		```
	'''
	isOfType ActorClass
	uses Replication
	property multiplicity values {"1..n", "*"}
	stable
;

Feature Binding
	description '''A Binding connects two Ports with each other'''
	text '''
		In essence, a binding is a abstraction for an underlying communication channel whose function is to convey messages from one port to the other.
		The precise semantics of these channels are not defined in the Binding. Instead, they are determined by the ProtocolClasses that are associated with the Ports at the end of the Binding.
		
		```room
		ActorClass ExampleActorClass {
			Structure {
				conjugated Port sender: ProtocolClass1
				ActorRef actorRef: ActorClass2
				
				Binding sender and actorRef.receiver
			}
		}
		```
	'''
	help '''
		```room
		Binding port1 and actorRef.port2
		Binding actorRef1.port1 and actorRef2.port2
		```
	'''
	uses Port endpoint1
	uses Port endpoint2
	stable
;

Feature LayerConnection
	description '''A LayerConnection associates a SPP to an ActorRef, resulting in an connection of all SAPs on its instance hierarchy'''
	text '''
		
		- An actor class can define a Service Provision Point (SPP) to publish a specific service, defined by a protocol class
		- An actor class can define a Service Access Point (SAP) if it needs a service, defined by a protocol class
		- For a given actor hierarchy, a LayerConnection defines which SAP will be satisfied by (connected to) which SPP
		
	'''
	help '''
		```room
		LayerConnection ref actorRef1 satisfied_by actorRef2.spp2
		LayerConnection relay_sap spp1 satisfied_by actorRef2.spp2
		```
	'''
	uses SAP SAPoint
	uses SPP SPPoint
	stable
;

Feature ExecutionType
	description '''Determines the execution type of an actor'''
	text '''
		Since from ROOM models executable code can be generated, it is important to define the way the actors are 
		executed and communicate with each other. The combination of communication and execution is called the 
		*execution model*. Therefore the ExecutionType of an actor and the CommunicationType of the ports has to be considered.

		The ExecutionType of an ActorClass specifies in which way its instance (ActorRef) should be executed:
		
		- **execution by receive event**: The message queue or the event dispatcher calls a **receive event** function of the message receiver and thereby executes the processing of the event.
		- **polled execution**: The objects are processed by a cyclic **execute** call
		- _**execution by function call**: The caller executes the called object via function call_ (not supported yet)
		- **mixture**: An asynchronous execution combines an event dispatcher and a polled execution.
		

		Thereby the ExecutionType determines the execution mode of the actor's logical thread:

		![Thread of Control](images/010-RoomIntroduction03.png)
				
		The actual execution of the underlying physical thread can be specified in the PhysicalModel in conjunction with the MappingModel.

		ExecutionType relates to the [CommunicationType][], e.g. if an actor uses data-driven ports, it should support an polled execution.
	'''
	example '''
		```room
		/** default is eventdriven */
		eventdriven ActorClass EventdrivenActor {
			// only event-driven Ports and ActorRefs allowed
		}
		
		datadriven ActorClass DatadrivenActor {
			// only data-driven Ports and ActorRefs allowed
		}
		
		async ActorClass MixedActor{
			// both data/event-driven Ports and ActorRefs allowed
		}
		```
	''' 
	uses CommunicationType
	property mode values { "eventdriven", "datadriven", "async", "sync" }
	
	stable
;

Feature CommunicationType 
	description '''The CommunicationType defines the communication semantics of a ProtocolClass'''
	text '''
		Since from ROOM models executable code can be generated, it is important to define the way the actors are executed and communicate with each other.
		The combination of communication and execution is called the *execution model*. Therefore the ExecutionType of an actor and the CommunicationType of the ports has to be considered.

		The CommunicationType of a ProtocolClass (and thus of a Port) specifies in which way the communication should happen:
		
		- **message driven** -- asynchronous, non blocking, no return value: Usually the message driven communication is implemented with message queues. Message queues are inherently asynchronous and enable a very good decoupling of the communicating parties.
		- **data driven** -- asynchronous, non blocking, no return value: In data driven communication sender and receiver often have a shared block of data. The sender writes the data and the receiver polls the data.
		- _**function call** -- synchronous, blocking, return value: Regular function call as known in most programming languages._ (not supported yet)

		CommunicationType relates with the [ExecutionType][] of an ActorClass, e.g. a data-driven port needs a cyclic thread, that polls the shared data.
	''' 
	example '''
		```room
		
		import etrice.api.types.*
		
		/** default is eventdriven */
		ProtocolClass EventdrivenProtocolClass1 {
			// explicit: eventdriven ProtocolClass EventdrivenProtocolClass {
			incoming {
				/** message without data */
				Message msg1()
				/** message with data */
				Message msg2(int32)
			}
			outgoing {
				/** eventdriven ProtocolClass can have message into two directions */
				Message msg4()
			}
		}
		
		datadriven ProtocolClass DatadrivenProtocolClass {
			incoming {
				/** a datadriven message needs data */
				Message signal1 (int32)
			}
			// datadriven ProtocolClass can only have incoming messages (signals)
		}
		
		//  sync is not supported yet
		//	sync ProtocolClass SyncProtcolClass { 
		//		
		//	}
		```
	'''
	property type values {"eventdriven", "datadriven", "sync"}
	stable
;

Feature ProtocolClass
	description '''A ProtocolClass defines messages and is the interface specification for a Port'''
	text '''
		A ProtocolClass provides a reusable interface specification for ports. It defines a set of incoming and outgoing Messages that can be exchanged between two ports.
		The exact semantics of a message is defined by the CommunicationType.
		Protocol classes have only textual notation.

		```room
		ProtocolClass SimpleProtocolClass {
			incoming {
				Message msg1(int32}
				Message msg2()
			}
			outgoing {
				Message msg3(DataClass1}
				Message msg4()
			}
		}
		```
	'''
	example '''
		```room
		import etrice.api.types.*
		
		// eventdriven ProtocolClass (asynchronous message passing, bidirectional)
		eventdriven ProtocolClass ProtocolClassEvt {
			// ProtocolClass ProtocolClassEvt { // same like above because eventdriven is default 
			incoming {
				// incoming means incoming for a regular port and outgoing for a conjugated port
				Message message1() // message without data
				Message message2(int32) // message with simple data
				Message message3(DMessageData) // message with complex data (DataClass)
		
			}
			outgoing {
			// outgoing means outgoing for a regular port and incoming for a conjugated port
				Message message1(int32) // incoming and outgoing Messages can have the same name to enable symmetric protocols
			}
		}
		
		// DataClass for sending complex data via message
		DataClass DMessageData {
			Attribute SomeData: int16
			Attribute SomeMoreData: int32
		}
		
		// datadriven ProtocolClass (asynchronous data flow, unidirectional)
		datadriven ProtocolClass ProtocolClassData {
			incoming {
				// incoming means incoming for a regular port and outgoing for a conjugated port
				Message value1(int32) // a datadriven message (signal) always needs data
				Message value2(int16) // datadriven message with simple data
				Message value3(DMessageData) // datadriven message with complex data (DataClass)
		
			}
			// no outgoing messages for datadriven ports allowed 
		}
		```
	'''
	help |||
		```room
		// prefixes: (eventdriven, datadriven, sync)
		/** An eventdriven ProtocolClass by default */
		ProtocolClass ProtocolName {
			usercode1 ''' '''
			usercode2 ''' '''
			usercode3 ''' '''
			incoming {
				Message messageName()
				Message messageName(int32)
			}
			outgoing {
				Message ...
			}
			regular PortClass {
				usercode1 ''' '''
				Attribute ...
				Operation ...
			}
			conjugated PortClass {
				...
			}
		}
		
		ProtocolClass ProtocolName extends ProtocolSuperClassName {
			// inherits all elements from super class
		}
		```
	|||
	contains CommunicationType
	contains Attribute
	contains Operation
	contains Annotation
	uses Inheritance
	
	stable
	;

abstract Feature DataType
	description '''A DataType can take 4 forms and types data elements like an Attribute or Operation argument'''
	stable
;

Feature PrimitiveType
	description '''A PrimitiveType is an abstraction of a target language's basic type (e.g. integer or boolean)'''
	example '''
		The eTrice built-in types can be found in the _org.eclipse.etrice.modellib_ project. In most cases the _Types.room_ is already included:

		```room
		// Follow import by Open Declaration (F3)
		import etrice.api.types.*
		```
	'''
	help '''
	```room
	// Java
	PrimitiveType boolean: ptBoolean -> boolean (Boolean) default "false"
	PrimitiveType int16: ptInteger -> short (Short) default "0"
	
	// c
	PrimitiveType boolean: ptBoolean -> boolean default "false"
	PrimitiveType int16: ptInteger -> int16 default "0"

	/** Documentation */
	PrimitiveType name: literalType -> targetName (castName) default "value"
	```
	'''
	isA DataType
	property targetName values {"identifier name"}
	stable
	;
	
Feature Enumeration
	description '''An EnumerationType declares an enumeration similar to most well-known languages'''
	example '''
		```room
		Enumeration EOnOff {
			Off = 0, // explicit value=0
			On = 1 // explicit value=1 
		}
		
		Enumeration EDay {
			SUN,
			MON,
			TUE,
			WED,
			THU,
			FRI,
			SAT // implicit enumeration 0..6
		}
		```
	'''
	help '''
		```room
		Enumeration EOnOff {
			Off,
			On
		}
		Enumeration EOnOff of int8 {
			Off = 0,
			On = 1
		}
		
		/** Documentation */
		Enumeration EnumName of PrimitiveType1 {
			// name1 = int
			// ...
		}
		```
	'''
	isA DataType
	property literals values {"name"}
	stable;

Feature DataClass 
	description '''A DataClass is a composition of Attributes'''
	text '''
		Intended to model a type that primarily consists of data, which is usually grouped together in some manner. DataClasses roughly translate to Java classes without interaction or C <em>struct</em>s.
		
		```room
		DataClass TCPConnectionData {
			Attribute IPAddr: string
			Attribute TcpPort: int32
		}
		```
	'''
	example |||
		```room
		DataClass SimpleDataClass {
			Attribute attribute1: uint16
			Attribute attribute2: uint32
		}

		DataClass DataClassExample {
			Attribute attribute1: uint32
			Attribute attribute2: SimpleDataClass
			Attribute attribute3: voidType ref
			
			Operation operation1(param1: uint32, param2: uint16): boolean '''
				return true;
			'''
		}
		```
	|||
	help |||
		```room
		/** Documentation */
		DataClass DataClassName {
			Attribute ... // nested DataClasses possible
			ctor ''' /* constructor */ '''
			dtor ''' /* destructor */ '''
			Operation ...
		}
		
		DataClass DataClassName extends DataSuperClassName {
			// inherits all elements from super class
			...
		}
		```
	|||
	isA DataType
	contains Attribute
	contains Operation
	contains Annotation
	uses Inheritance
	stable;

Feature ExternalType 
	description '''An ExternalType is used to make an target language type accessible in ROOM'''
	example |||
		```room
		// Include is needed when used (e.g. in ActorClassWithExternalType)
		ExternalType someStructType -> "struct FILE_HANDLE"
		
		ActorClass ActorClassWithExternalType{
			Structure {
				usercode1 '''
					// #include <___.h> /* User includes here*/
				'''
				Attribute someHandle : someStructType ref // needs include
			}
			Behavior {
				Operation operation1(param1: charPtr) '''
					// external calls or casts may need includes
					write(someHandle, param1);
				'''
			}
		}
		```
	|||
	help '''
		```room
		ExternalType voidType -> "void" default "NULL"
		
		/** Documentation */
		ExternalType typeName -> "targetName" default "value"
		```
	'''
	isA DataType
	property targetName values {"identifier name"}
	stable;

Feature Attribute
	description '''An Attribute is a member variable of a class'''
	text '''
		An Attribute can be be used to store arbitrary data. There are two common conceptual purpose of use:

		
		- model current system state (state machine variable)
		- store reference to more fine-grained components (e.g. c pointer to handle)
		
		Attributes can be defined in several ROOM classes.
	'''
	example '''
		```room
		import etrice.api.types.*
		
		DataClass SimpleDataClass {
			Attribute attribute1: int16
			Attribute attribute2: uint32
		}
		
		ActorClass ActorClassWithAttributes {
			Structure {
				/** attribute of a PrimitiveType */
				Attribute attribute1: int32
				/** attribute of a DataClass */
				Attribute attribute2: SimpleDataClass
			}
		}
		
		ActorClass ActorClassWithAttributes2 {
			Structure {
				/** attribute with multiplicity */
				Attribute arrayAttribute[8] : uint32
				/** attribute as a reference (void pointer) */
				Attribute refAttribue : voidType ref
			}
		}
		
		ActorClass ActorClassWithAttributeInitialization {
			Structure {
				Attribute attribute1: uint32 = "3"
				Attribute attribute2: SimpleDataClass = "{1, 2}"
				Attribute arrayAttribute[8] : uint32 = "0" // or {0,0,0, ...}
				Attribute refAttribue : voidType ref = "NULL" // set reference in constructor or in state machine
			}
		}
		```
	'''
	help '''
		```room
		/** a boolean attribute */
		Attribute attributeName: boolean
		/** an array attribute */
		Attribute attributeName[8]: int32 = "0"
		/** an external type attribute as reference */
		Attribute attributeName: voidType ref = "NULL"
		```
	'''
	isOfType DataType
	property defaultValueLiteral values { "target code"}
	property multiplicity values {"1..n"}
	property ref
	stable
	
	
;

Feature Operation
	description '''An Operation is a member function of a class'''
	text '''
		Operations can be used to define a piece of reusable logic. The definition consists of:
		
		- Arbitrary amount of arguments
		- Return type
		- User code body, which can access the structural part of the containing class (e.g. attributes)
		- 'override' keyword, replaces the logic of the inherited operation having the same signature
		
	'''
	example |||
		```room
		import etrice.api.types.*
		
		DataClass DataClassWithOperation {
			Attribute attribute1 : uint32
			
			Operation operation1(param1: uint32, param2: int32): boolean '''
				return attribute1 > (param1 - param2);
			'''
		}
		
		ActorClass ActorClassWithOperation {
			Structure {
				Attribute attribute1 : uint32
			}
			Behavior {
				Operation operation1(param1: uint32, param2: int32): boolean '''
					return attribute1 > (param1 - param2);
				'''
			}
		}
		
		ActorClass ActorClassWithOperation2 {
			Structure {
				usercode1 '''
					// #include <___.h> /* User includes here */
				'''
				Attribute someHandle : voidType ref
			}
			Behavior {
				Operation operation1(param1: charPtr) '''
					// external calls or casts may need includes
					write(someHandle, param1);
				'''
			}
		}
		```
	|||
	help |||
		```room
		/** A void operation */
		Operation operationName() '''
			user code here;
			// don't forget the ';' at line end 
		'''
		
		/** Operations can habe multiple parameters and one return type */
		Operation operationName(param1: int16, param2: int32) : boolean '''
			return param1 == param2;
		'''

		// 'override' replaces implementation of overriding operation,
		// becomes effective in entire inheritance hierarchy
		override Operation operationName(param: int32) : boolean ''' '''
		```
	|||
	uses DataType
	property returnType values { "DataType" }
	property arguments values { "name : DataType" }
	
	stable
;

abstract Feature Port
	description '''A Port is an instance of a ProtocolClass and the interface for an ActorClass'''
	text '''
		Once a ProtocolClass has been created, it can be used to define actor interfaces. This is accomplished by means of Ports. 
		A Port is a declaration that the set of messages defined by its ProtocolClass is now part of the actor's interface.
		It provides strong decoupling of ActorClasses from each other, thus enabling easy testability, reusability and deployment of actors to different threads or nodes.

		```room
		ActorClass Example {
			Structure{
				Port port0 : ProtocolClass1
			}
			Behavior {
				// send/receive message from port0
			}
		}
		```
		
		For communication between two actors to take place, a connection must be established between a port on one of the actors and a port on the other.
		One condition is, that both Ports have compatible ProtocolClasses. In most cases the Ports simply refer to the same protocol.
		In addition, a ProtocolClass has an imposed directionality - it defines one subset of messages as incoming and the complementary subset as outgoing.
		Which subset is labeled as incoming and outgoing is arbitrary, it simply depends on the point of view, that was taken when defining.
		Therefore Ports can be 'regular' and 'conjugated'. When two actors communicate by a connected pair of Ports, one Port has to be regular and the other conjugated.
		The ProtocolClass' incoming messages are on one side received by the regular Port and on the other sent by the conjugated Port (outgoing message vice versa).

		A connection of Ports is denoted by a Binding. 
	'''
	help '''
		```room
		/** generated doc */
		Port portName : ProtocolClass1
		/** generated doc */
		Port portName[4] : ProtocolClass1
		/** generated doc */
		Port conjugated portName : ProtocolClass1
		```
	'''
	isOfType ProtocolClass
	uses Replication
	property conjugated values { "regular", "conjugated"}
	property multiplicity values {"1..n", "*"}
	stable
;

Feature RelayPort
	description '''A RelayPort forwards its messages without exposing them to the internal interface of the ActorClass'''
	text '''
		```room
		ActorClass RelayPortExample{
			Interface {
				Port relayPort : PSimpleProtocol
			}
			Structure {
				ActorRef actorRef1 : SimpleActorClass2
				
				// relayPort can be directed to port of an ActorRef
				Binding relayPort and actorRef1.externalPort
			}
			Behavior {
				// relayPort not available !
			}
		}
		```
		![RelayPort](images/300-RelayPort.png)
	'''
	isA Port
	stable
;


Feature ExternalEndPort 
	description '''A ExternalEndPort is an interface Port, that is made accessible to the internal interface of an ActorClass'''
	text '''
		```room
		ActorClass ExternalEndPortExample {
			Interface {
				// externalEndPort is connect from 'outside' and thus needs a Binding from containing ActorClass
				Port externalEndPort : PSimpleProtocol
			}
			Structure {
				external Port externalEndPort
			}
			Behavior {
				// send/receive messages from externalEndPort
			}
		}
		```
	'''
	isA Port
	stable
;

Feature InternalEndPort
	description '''A InternalEndPort is an local Port, that is declared in the internal interface of an ActorClass'''
	text '''
		```room
		ActorClass InternalEndPortExample {
			Structure {
				Port internalEndPort : PSimpleProtocol
				ActorRef actorRef1 : SimpleActorClass
				
				// internalEndPort lives 'local' and
				// thus needs a Binding to port of a ActorRef
				Binding internalEndPort and actorRef1.externalPort2 
			}
			Behavior {
				// send/receive messages from internalEndPorts
			}
		}
		```
		![InternalEndPort](images/300-InternalEndPort.png)
	'''
	isA Port
	stable
;

Feature SAP
	description '''A Service Access Point is similar to a Port, but uses a LayerConnection for wiring'''
	text '''
		
		- An actor class can define a Service Provision Point (SPP) to publish a specific service, defined by a protocol class
		- An actor class can define a Service Access Point (SAP) if it needs a service, defined by a protocol class
		- For a given actor hierarchy, a LayerConnection defines which SAP will be satisfied by (connected to) which SPP
		
	'''
	help '''
		```room
		SAP sapName: ProtocolClass1
		```
	'''
	isOfType ProtocolClass
	stable
; 

Feature ServiceImplementation
	description '''The implementation of an Service Provision Point (SPP)'''
	text '''
	'''
	help '''
		```room
		Interface {
			SPP sppName: ProtocolClass1
		}
		Structure {
			ServiceImplementation of sppName
		}
		```
	'''
	uses SPP
	stable
;

Feature SPP
	description '''A Service Provision Point is the counterpart of a SAP'''
	text '''
		- An actor class can define a Service Provision Point (SPP) to publish a specific service, defined by a protocol class
		- An actor class can define a Service Access Point (SAP) if it needs a service, defined by a protocol class
		- For a given actor hierarchy, a LayerConnection defines which SAP will be satisfied by (connected to) which SPP
	'''
	help '''
		```room
		SPP sppName: ProtocolClass1
		```
	'''
	isOfType ProtocolClass
	stable
;


Back to the top