Papyrus-RT/Developer/Design/0.8/Codegen Architecture Details

Transformation Architecture Detailed Description

Overview

The code generator input is a UML2 model (org.eclipse.uml2) with the UML-RT profile applied to it. The output is a CDT project (C++).

More precisely, the input to the generator is a list of UML2 elements that have changed. When invoked from within Papyrus, the tool keeps track of which elements have changed since the last generation.

There are two intermediate meta-models:

1. xtUMLrt: a meta-model that simplifies UML-RT and contains a common core shared with xtUML.
2. Cpp: a meta-model of a sub-set of C++.

The overall generation process is depicted in the following diagram:

The rationale for the intermediate models is as follows:

• The xtUMLrt meta-model is intended to simplify UML2, in order to simplify the generator itself, while allowing customization, isolating the generator from the toolset, and providing a common language that allows its eventual extension to support xtUML.
• The Cpp meta-model isolates the generator from issues such as formatting, body/header file generation, file regeneration avoidance, CDT project and makefile generation, etc.

The core of the code generator consists of separate sub-generators for different kinds of elements. Namely:

• Capsules
• (Passive) classes
• Protocols
• State machines
• Deployment composition/structure

With the exception of the state machine generator, these translate an xtUMLrt model directly into a C++ model. The state machine generator performs some further intermediate steps on the xtUMLrt model before generating the C++ model. These steps are detailed below.

Plugins

The following tables provide a description of the features and plugins that form the code generator.

Features/Releng	Description
org.eclipse.papyrusrt.releng	Feature packaging
org.eclipse.papyrusrt	The top-level feature that groups all plugins
org.eclipse.papyrusrt.codegen-feature	The code generator feature (separately installable)
org.eclipse.papyrusrt.rts-feature	The RTS feature (separately installable)

Plugins	Description
org.eclipse.papyrusrt.codegen	The top-level plug-in that provides the Activator
org.eclipse.papyrusrt.codegen.cpp	The core of the generator. Includes Capsule, Class and Protocol generators
org.eclipse.papyrusrt.codegen.cpp.rts	Cpp model representation of the RTS elements
org.eclipse.papyrusrt.codegen.cpp.statemachines.flat	State machine generator (from flat state machines)
org.eclipse.papyrusrt.codegen.cpp.structure	Deployment structure generator
org.eclipse.papyrusrt.codegen.lang	Base for language-specific plugins
org.eclipse.papyrusrt.codegen.lang.cpp	The Cpp intermediate meta-model
org.eclipse.papyrusrt.codegen.statemachines.flat	State machine flattener
org.eclipse.papyrusrt.codegen.statemachines.flat.model	Extensions to the xtUMLrt meta-model for SM generation
org.eclipse.papyrusrt.codegen.papyrus	Papyrus integration
org.eclipse.papyrusrt.codegen.standalone	Standalone generator (does not require Eclipse instance running)
org.eclipse.papyrusrt.protocoleditor	Papyrus protocol editor
org.eclipse.papyrusrt.rts	The RTS (a clone of the umlrt.rts git repository) and UML-RT runtime model library
org.eclipse.papyrusrt.utils	Utilities used by several plugins
org.eclipse.papyrusrt.codegen.cpp.profile	New C++ profile
org.eclipse.papyrusrt.xtumlrt.common.model	The common xtUMLrt meta-model (intermediate representation)
org.eclipse.papyrusrt.xtumlrt.umlrt.model	The UML-RT-specific extensions to the common xtUMLrt meta-model
org.eclipse.papyrusrt.xtumlrt.xtuml.model	The xtUML-specific extensions to the common xtUMLrt meta-model
org.eclipse.papyrusrt.xtumlrt.platform.model	Base for platform/target specific meta-models
org.eclipse.papyrusrt.xtumlrt.platform.cpp.model	Extensions for C++ generation

Tests	Description
org.eclipse.papyrusrt.codegen.lang.cpp.test	Unit tests for the Cpp intermediate metamodel
org.eclipse.papyrusrt.codegen.lang.test	Unit tests for the base lang plugins

The generator core

The core consists of the following classes. Most are in the org.eclipse.papyrusrt.codegen.cpp plugin.

• The "generator starter" (UMLRTGenerator)

This class is the one that begins the generation process from the UI or the standalone, and invokes the "generation director" (below).

• The "generation director" (CppCodeGenerator):

This class drives the generation process. More on this below.

• The "C++ code pattern" (CppCodePattern):

This class provides an interface to the C++ language meta-model, as it is used in this transformation.

It produces and keeps track of which C++ element has been generated for any given (xtumlrt) model element.

• The translator from UML2 to xtUMLrt (UML2xtumlrtModelTranslator):

This translates UML2 model elements into xtUMLrt model elements and keep track of which source elements gave rise to intermediate xtUMLrt elements.

• The "model change tracker" (UML2ChangeTracker):

Responsible of keeping track of model changes in order to enable incremental generation

• The element generator base class (AbstractCppGenerator):

This is the base class for individual code generators for specific UML-RT elements.

• The GeneratorManager:

This tracks generator instances for different types of elements.

It is a base class for Eclipse-based and stand-alone generator managers.

• The actual model element generator classes for: [^1]
  • Basic (Passive) classes (BasicClassGenerator)
  • Serializable (Passive) classes (SerializableClassGenerator)
  • Capsules (CapsuleGenerator)
  • Protocols (ProtocolGenerator)
  • State Machines (StateMachineGenerator)
  • Deployment composition/structure (CompositionGenerator)
• Utility classes

The following diagram shows the class diagram with the general structure of the code generator:

The generation director (CppCodeGenerator) is instantiated and run from the UMLRTGenerator in either the org.eclipse.papyrusrt.codegen.papyrus plugin (if executed within the Eclipse GUI) or from the org.eclipse.papyrusrt.codegen.standalone (if executed standalone).

The "generator starter" (UMLRTGenerator)

This class has a generate method that receives a list or target EObject elements, expected to be instances of org.eclipse.uml2.uml.Element. Roughly, it does the following:

1. Determine the set of related elements that have changed in the editor and add them to a set of changes
2. Determine the folder where the code for the elements should be generated (and create a CDT project if needed)
3. Translate each UML element to xtUMLrt (the intermediate representation)
4. Invoke the CppCodeGenerator.generate method on the target list
5. Write (M2T) the resulting Cpp models to their target folders

There are two versions of this class. One in org.eclipse.papyrusrt.papyrus, invoked from within Papyrus, and one in org.eclipse.papyrusrt.standalone, invoked from the stand-alone generator.

This class contains references to:

• UML2xtumlrtModelTranslator
• UML2ChangeTracker
• CppCodePattern
• CppCodeGenerator

The "generation director" (CppCodeGenerator)

This class has the main method generate that performs the generation.

The input is a list of target xtUMLrt model elements (typically translated from UML2 by the UI or the standalone generator). This input is passed to the constructor of CppCodeGenerator.

The generate process itself performs the following steps:

1. Eliminate from the target list, elements which have been explicitly marked as "not to be generated".
2. "Collection": creates an instance of each code generator class (AbstractCppGenerator sub-classes) according to the type of element. This computes on the fly the transitive closure of affected elements. One generator instance is created for each model element.
   • For Model or Package elements, it recursively collects the generators for Entities (Classes and Capsules) as well as Protocols in the model/package.
   • For Protocols (non-built-in system protocols), creates a ProtocolGenerator and Capsule generators for each capsule in the model which has a port typed by the protocol.
   • For StructType elements, creates a BasicClassGenerator
   • For Capsule elements, creates a CapsuleGenerator, and a StateMachineGenerator or an EmptyStateMachineGenerator (if it has no state machine). Furthermore, if the capsule has been marked as the "top" capsule, it creates a CompositionGenerator, to create the deployment structure.
3. Prune the list of generators to exclude those corresponding to elements that have already been generated and have not changed (according to the change-set)
4. Generation: invokes the generate method on each individual generator instance. The result for each element is an element in the C++ model.
5. Consume (clean) the set of changed elements

The M2T step is performed by the UMLRTGenerator class of either the org.eclipse.papyrusrt.papyrus plugin, if it is executed from within Papyrus, or from the org.eclipse.papyrusrt.standalone plugin, if it is invoked from the stand-alone generator.

The "C++ code pattern" (CppCodePattern)

This class provides an interface to the Cpp meta-model and is used to share C++ model elements generated by different parts of the generator.

It mostly provides methods to create C++ model elements on demand for specific types of xtUMLrt model elements and contexts. These are stored in tables for future reference so that the same C++ model element is returned for the same xtUMLrt model element. This allows the generation of target C++ model elements to occur in any order, which means that code generators can be invoked in any order as they will obtain the C++ model elements when needed.

For example, suppose that there is a Capsule C1 with a port typed with a Protocol P1 in the model. If the input list of target elements is [P1,C1], then ProtocolGenerator.generate is invoked first on P1, which will in turn invoke the CppCodePattern.getCppClass method to obtain the C++ class model element for P1. Then, CapsuleGenerator.generate is invoked on C1, which will generate the code for its ports, and when doing so, it will try to obtain the C++ class for P1 from the CppCodePattern, and since it was already computed for P1, it obtains the same C++ model element. If the input list of target elements was [C1,P1], the C++ class for P1 will be created when the CapsuleGenerator is translating C1 and tries to obtain the corresponding C++ class for the protocol, while the execution of ProtocolGenerator.generate will obtain that class as it has already been computed.

The translator from UML2 to xtUMLrt (UML2xtumlrtModelTranslator)

TBA

The "model change tracker" (UML2ChangeTracker)

TBA

The model element generators

BasicClassGenerator

TBA

SerializableClassGenerator

TBA

CapsuleGenerator

TBA

ProtocolGenerator

TBA

StateMachineGenerator

TBA

CompositionGenerator

TBA

---

[1]: The generators for state machines and the overall model composition are defined in the org.eclipse.papyrusrt.codegen.statemachines and org.eclipse.papyrusrt.codegen.structure plugins respectively.