Papyrus-RT/Developer/Design/0.9/UML-RT-Implementation

UML-RT Semantics in Eclipse UML

This document describes the implementation of UML-RT semantics in Papyrus as a customization of the Eclipse UML2 implementation of UML.

Most of the APIs and other code described herein are implemented in a new bundle org.eclipse.papyrusrt.umlrt.uml. Critically, this bundle is designed (and required) to operate in a "pure Java" context, that is, without the Eclipse or any OSGi run-time running. Changes in other bundles are required to integrate these into Papyrus-RT; those will be called out in the text below.

Development of this feature is tracked in bug 467545, with attendant git branches, Gerrit patches, and blocking/related bugs. Builds of the feature branch are produced here. Use caution when trying these builds! Do not use them on models that you care about without adequate backup. There are bugs, particularly in undo/redo, which usually is intended to provide a safeguard.

Demonstrative videos are posted from time to time on YouTube:

• First prototype of incremental redefinition
• Brief addendum to the above
• First prototype of Capsule Structure Diagram inheritance
• Incremental refinement distinguishing view inheritance from semantic inheritance
• First prototype of exclusion of inherited elements in capsule structure diagrams

Incremental Redefinition

The key concept in UML-RT that distinguishes it, besides the profile, from UML is the notion of incremental redefinition. This recognizes that a redefining element can leave some of its attributes unset so that they shall be interpreted as being inherited from the redefined element. This is accomplished by means of subclasses of the UML2 implementation classes for the various redefinable elements. These implement an internal interface InternalUMLRTElement that defines various operations for inheriting values of unset features from the redefined element, setting the redefined element, and more. The custom implementation classes use these common internal APIs to override the basic UML features inherited from Eclipse UML2.

UML-RT Implementation Classes

These custom implementation classes also override the methods implementing standard UML well-formedness constraints to account for UML-RT requirements, especially for type compatibility in protocols, connector ends, etc.

Stand-alone Configuration

For configuration of a ResourceSet to work with UML-RT models, a static utility class UMLRTResourcesUtil is provided as an analogue to UMLResourcesUtil from the UML2 API (the former actually uses the latter for core UML set-up). The init(ResourceSet) API performs all of the registrations required to install the UML-RT support described in this document in a resource set.

UML Extensions

When a generalization relationship is established between capsules or protocols, or a redefinition relationship between state machines, then inheritance of elements is activated that is managed in part by extensions to the UML metamodel. These essentially are structural features of model elements that are stored in separate companion objects (extensions) made accessible through the elements, themselves. So, in a sense they are like features that may be added to metaclasses by package merge, only there is no actual merge; but in practice they are much more like stereotypes, except that they are more deeply integrated into the elements by way of the custom implementation classes.

The extensions are modelled as a metamodel umlext with metaclasses that mirror the extended metaclasses in name and generalization relationships. One important use case for the extensions is to store implicit redefinitions of inherited elements for the cases where they are neither excluded nor configured differently in any attribute as compared to the inherited element. These implicit redefinitions are stored in extension attributes as depicted in the diagram below. The implementation classes, for example ClassImpl, are instrumented to forward access to these features via Ecore reflection to the extension object. This makes it possible, for example, to extend the ownedMember superset in the ClassImpl to include the implicitAttribute and implicitConnector properties. This ripples to other derived unions such as ownedElement.

UML Extensions

The extension elements are stored in a special resource maintained in the resource set, called the extension extent. This resource, therefore, indirectly contains any "virtual elements" that are these implicit members or other model content. It also maintains an adapter on every element contained within it that, when some concrete change is made to it (thus effecting an incremental redefinition of some inherited element), reifies the object by moving it and any stereotype applications it may have into the user model (in the appropriate containment reference, of course).

Façade API

The org.eclipse.papyrusrt.umlrt.uml package contains a suite of classes that provide a façade API exposing the UML-RT model structure in a friendly way, primarily target to extenders. Instances of the façade classes correspond one-to-one with the core element of the UML representation of each UML-RT concept; this association is maintained by means of an EMF Adapter attached to the UML element.

This adapter provides the necessary coördination of the façade structure with the UML model as the latter changes with the user's edits and also maintains the UML extensions of model elements, including virtual redefinitions where necessary, amongst potentially other content.

The initial prototype of the façade API consists of these classes:

• UMLRTModel — corresponds to a Resource in the editor's ModelSet
• UMLRTPackage — corresponds to a Package, including the root Model, that is not a «protocolContainer» package
• UMLRTCapsule — corresponds to a Class stereotyped as «capsule»
• UMLRTPort — corresponds to a Port stereotyped as «rtPort»

The façades provide direct access to and modification of the most important properties of their UML-RT concepts. For example, names of elements, types of ports (as UMLRTProtocols), etc. The UMLRTCapsule maintains a single list of UMLRTPorts that synthesizes regular owned ports, redefining ports, virtual redefining ports (from the UML extension), and excluded ports. Other details can be obtained from the corresponding UML model element, which each façade object provides via a toUML() operation. Notification of changes is not supported; this must be done at the UML level.

Other façade classes planned for capsule structure include

• UMLRTCapsulePart — properties of a capsule stereotyped as «capsulePart»
• UMLRTProtocol — a Collaboration stereotyped as «protocol»
• UMLRTMessage — an Operation of in/out/inout direction as determined by the «rtMessageSet» Interface that defines it
• UMLRTConnector — a Connector in a capsule that is stereotyped as «rtConnector»
• etc.

The UMLRT prefix is applied to these façade class names to distinguish them clearly from the similarly named Java interfaces in the UML-RT Profile, e.g. Capsule, Protocol, CapsulePart, RTPort. Although it is not strictly necessary (the names are distinguished by their package namespace, anyways), it is convenient for readability of code to see at a glance that it is working in UML-RT terms, not UML terms, especially in sophisticated Papyrus-RT plug-ins and derived DSMLs that mix both APIs together.

Integration in Papyrus-RT

The UMLRTLanguage class in the org.eclipse.papyrusrt.umlrt.core bundle that plugs into the ILanguageService uses the UMLRTResourcesUtil to install the UML-RT implementation of the UML metamodel in place of the Eclipse UML2 UML implementation in the ModelSet-local package registry. It also bootstraps the UML-RT façade API on the model with its listeners that react to structural changes to keep the UML-RT semantics up-to-date and hooks into the TransactionalEditingDomain to ensure that undo/redo transactions do not interfere with the reification of virtual redefinition elements.

The org.eclipse.papyrusrt.umlrt.tooling.modelexplorer bundle adds a new EMF Facet customization model, Structure.custom, that enhances the Model Explorer presentation to show virtual redefinitions in the UML extension features of their namespaces. This is done by means of a generic GetExtensionFeatureQuery facet-query that takes an extension feature (an EStructuralFeature from the UML Extension metamodel) and retrieves its value from the context object, if that object is one from the UML-RT implementation that supports extension.

Capsule Structure Diagram Inheritance

For the visualization of inherited features in the Capsule Structure Diagrams, I have decided not to use the synchronization framework (org.eclipse.papyrus.infra.sync) introduced in the Papyrus Mars release. Prototyping work with this framework showed that it is simply too unwieldy, prone to failure of undo/redo, and that it is in large part obviated by work done in bug 467545 on an implementation of UML-RT semantics in the UML metamodel. So, inheritance in the diagrams is implemented by means of a coördination of GEF edit policies:

• Canonical Edit Policy: the Papyrus-RT visual children strategy uses the UML-RT façade API to find and return inherited elements
• Inheritance Edit Policy: (NEW) manages three aspects of inherited elements:
  • tracking of the visuals of the inherited elements from the capsule structure diagram in which they are defined
  • transience (non-persistence) of the views of inherited elements
  • reification of redefining elements when their presentation is customized in the inheriting diagram
• Applied Stereotype Comment Edit Policy: specialized in Papyrus-RT to omit the comment view for inherited elements