plugins/org.eclipse.app4mc.amalthea.model.help/docu/dev_model_details.textile

h2. Model Details

h3. Qualified name

The following image shows the logical dependency between the name segments and describe the used notations. The details differ in terms of delimiters and encoding of the segments.

!../pictures/dev_model_qualified_name.png!


h3. Unique ID generation

AMALTHEA uses a named based schema to reference other elements inside of a model.
A custom implementation is used instead of the standard EMF mechanism, which uses an index based implementation.
The target element id is identified by the following schema:

bc. 
java.net.URLEncoder.encode(<name of element>, StandardCharsets.UTF_8.toString)) + "?type=" + <element>.eClass.name

Samples:

Refering to a Runnable element with name foo in a RunnableCall looks like the following snippet:

bc. 
<items xsi:type="am:RunnableCall" runnable="foo?type=Runnable" />


h3. Interfaces and base objects

Several interfaces and abstract classes are defined in the common model.
They provide basic common functionality for all objects, which are extending it, like the possibility to add __CustomAttributes__ or __Tags__. Tags are available at different elements with the purpose to group them together or to annotate them.

!(scale)../pictures/model_common_interfaces_base_objects.png!


h3. Derived references

Some derived references are introduces to simplify a multi-level navigation. They are read only.

| |{text-align:center}. Reference | |
| @ISystem@ |>. *innerPorts* &#8594; | @QualifiedPort@ |
| @HwStructure@ |>. *innerPorts* &#8594; | @HwPort@ |
| @HwPath@ |>. *source* &#8594; | @ProcessingUnit@ |
| @HwPath@ |>. *destination* &#8594; | @HwDestination@ |
| @TaskScheduler@ |>. *childSchedulers* &#8594; | @TaskScheduler@ |
| @TaskScheduler@ |>. *parentScheduler* &#8594; | @TaskScheduler@ |


h3. Transient back pointers

AMALTHEA maintains a number of back pointers in the model. These transient references of an object 'point back' to the object referring to it. 

h4. Container references

Container references provide an easier access to the eContainer of an object.

The following references are specified as opposite references and can be modified.
By the prefix "containing" they clearly indicate that a containment is changed.

| | Container reference |>. Containment reference | |
| @Component@ |{color:green}. &#8592; *containingComponent* |>. *ports* &#8594; | @ComponentPort@ |
| @EnumMode@ |{color:green}. &#8592; *containingMode* |>. *literals* &#8594; | @ModeLiteral@ |
| @HwFeatureCategory@ |{color:green}. &#8592; *containingCategory* |>. *features* &#8594; | @HwFeature@ |
| @HwAccessElement@ |{color:green}. &#8592; *containingAccessElement* |>. *accessPath* &#8594; | @HwAccessPath@ |
| @RunnableCall@ |{color:green}. &#8592; *containingCall* |>. *arguments* &#8594; | @CallArgument@ |
| @ISystem@ |{color:green}. &#8592; *containingSystem* |>. *componentInstances* &#8594; | @ComponentInstance@ |
| @ISystem@ |{color:green}. &#8592; *containingSystem* |>. *connectors* &#8594; | @Connector@ |
| @Namespace@ |{color:green}. &#8592; *previousSegment* |>. *nextSegments* &#8594; | @Namespace@ |
| @Runnable@ |{color:green}. &#8592; *containingRunnable* |>. *parameters* &#8594; | @RunnableParameter@ |
| @ComponentInterface@ |{color:green}. &#8592; *containingInterface* |>. *subInterfaces* &#8594; | @SubInterface@ |

The following references are specified as opposite references.

| | Container reference (read only) |>. Reference | |
| @ProcessingUnit@ |{color:green}. &#8592; *source* |>. *accessElements* &#8594; | @HwAccessElement@ |
| @TaskScheduler@ |{color:green}. &#8592; *child* |>. *parentAssociation* &#8594; | @SchedulerAssociation@ |


The following container references are a special case. Because of the nested structure of sub elements the access to a dedicated container object is computed by traversing multiple eContainer references.

| | Container reference (read only) |>. Containment reference | |
| @Runnable@ |{color:green}. &#8592; *containingRunnable* |>. *activityGraph ...* &#8594; | @ActivityGraphItem@ |
| @Process@ |{color:green}. &#8592; *containingProcess* |>. *activityGraph ...* &#8594; | @ActivityGraphItem@ |
| @ActivityGraph@ |{color:green}. &#8592; *containingActivityGraph* |>. *items ...* &#8594; | @ActivityGraphItem@ |
| @Runnable@ |{color:green}. &#8592; *containingRunnable* |>. *...* &#8594; | @DataDependency@ |


h4. References (via inverse index)

The inverse index allows easier and faster navigation, at the expense of greater memory consumption.
The index is built on demand. 

The data model has some intermediate objects to express the call of a runnable or the access to a label.
These objects are containments of __Task__ or __Runnable__ and can have additional attributes. The back pointers support an easy way to answer queries like "Which tasks call runnable x ?" or "Which functions read label y ?".

| | Back pointer (read only) |>. Reference | |
| @LabelAccess@ |{color:green}. &#8592; *labelAccesses* |>. *data* &#8594; | @Label@ |
| @ChannelAccess@ |{color:green}. &#8592; *channelAccesses* |>. *data* &#8594; | @Channel@ |
| @SemaphoreAccess@ |{color:green}. &#8592; *semaphoreAccesses* |>. *semaphore* &#8594; | @Semaphore@ |
| @RunnableCall@ |{color:green}. &#8592; *runnableCalls* |>. *runnable* &#8594; | @Runnable@ |

All elements with memory representation (e.g. labels, runnables) can be mapped to a memory via a MemoryMapping. The back pointers provides a list of all mapping elements that refer to a specific memory or a specific MemoryElement.

| | Back pointer (read only) |>. Reference | |
| @MemoryMapping@ |{color:green}. &#8592; *mappings* |>. *memory* &#8594; | @Memory@ |
| @MemoryMapping@ |{color:green}. &#8592; *mappings* |>. *abstractElement* &#8594; | @AbstractMemoryElement@ |

Labels and runnables can be located in exactly one section. The back pointer provides a list of all elements that are assigned to a specific section.

| | Back pointer (read only) |>. Reference | |
| @Label@ |{color:green}. &#8592; *labels* |>. *section* &#8594; | @Section@ |
| @Runnable@ |{color:green}. &#8592; *runnables* |>. *section* &#8594; | @Section@ |

CustomEvent and InterProcessStimulus can have explicit triggers. The pointer is established from CustomEventTrigger and InterProcessTrigger. The back pointers provides easier access to the triggering runnables / processes.

| | Back pointer (read only) |>. Reference | |
| @CustomEventTrigger@ |{color:green}. &#8592; *explicitTriggers* |>. *event* &#8594; | @CustomEvent@ |
| @InterProcessTrigger@ |{color:green}. &#8592; *explicitTriggers* |>. *stimulus* &#8594; | @InterProcessStimulus@ |

Components define lists of included software elements (e.g. labels, runnables, semaphores). The back pointer provides access to all referring components.

| | Back pointer (read only) |>. Reference | |
| @Component@ |{color:green}. &#8592; *referringComponents* |>. *labels* &#8594; | @Label@ |
| @Component@ |{color:green}. &#8592; *referringComponents* |>. *runnables* &#8594; | @Runnable@ |
| @Component@ |{color:green}. &#8592; *referringComponents* |>. *processes* &#8594; | @AbstractProcess@ |
| @Component@ |{color:green}. &#8592; *referringComponents* |>. *semaphores* &#8594; | @Semaphore@ |
| @Component@ |{color:green}. &#8592; *referringComponents* |>. *osEvents* &#8594; | @OsEvent@ |

Allocations refer to a scheduler (Scheduler, TaskScheduler, InterruptController). The back pointer provides access from the scheduler to the allocations.

| | Back pointer (read only) |>. Reference | |
| @SchedulerAllocation@ |{color:green}. &#8592; *schedulerAllocations* |>. *scheduler* &#8594; | @Scheduler@ |
| @RunnableAllocation@ |{color:green}. &#8592; *runnableAllocations* |>. *scheduler* &#8594; | @Scheduler@ |
| @TaskAllocation@ |{color:green}. &#8592; *taskAllocations* |>. *scheduler* &#8594; | @TaskScheduler@ |
| @ISRAllocation@ |{color:green}. &#8592; *isrAllocations* |>. *controller* &#8594; | @InterruptController@ |

Some other useful back references.

| | Back pointer (read only) |>. Reference | |
| @Process@ |{color:green}. &#8592; *affectedProcesses* |>. *stimuli* &#8594; | @Stimulus@ |
| @ITaggable@ |{color:green}. &#8592; *taggedObjects* |>. *tags* &#8594; | @Tag@ |
| @SchedulerAssociation@ |{color:green}. &#8592; *childAssociations* |>. *parent* &#8594; | @TaskScheduler@ |
| @INamespaceMember@ |{color:green}. &#8592; *memberObjects* |>. *namespace* &#8594; | @Namespace@ |
| @IComponentStructureMember@ |{color:green}. &#8592; *memberObjects* |>. *structure* &#8594; | @ComponentStructure@ |
| @HwConnection@ |{color:green}. &#8592; *connections* |>. *port1* &#8594; | @HwPort@ |
| @HwConnection@ |{color:green}. &#8592; *connections* |>. *port2* &#8594; | @HwPort@ |


h4. Implementation

**Xcore:**

A derived back pointer is computed by %*AmaltheaIndex.getInverseReferences(...)*%.
The visiblity in the generated code and in the user interface is controlled by %*@GenModel*% annotations.

Example

bc.. 
class Runnable extends AbstractMemoryElement
{	...	
	// back pointer (readonly)
	@GenModel(documentation="<p><b>Returns an <em>immutable</em> list of callers (RunnableCalls).</b></p>")
	@GenModel(propertyCategory="Read only", propertyFilterFlags="org.eclipse.ui.views.properties.expert")
	refers transient readonly volatile derived RunnableCall[] runnableCalls get {
		AmaltheaIndex.getInverseReferences(this, AmaltheaPackage.eINSTANCE.runnable_RunnableCalls,
			#{AmaltheaPackage.eINSTANCE.runnableCall_Runnable} )
	}
p. 

h4. User Interface

!../pictures/impl/model_transient_backpointer_ui.png!