Papyrus/Toolsmith/Project Builder

Toolsmiths Project Builder (Work-in-progress)

This page describes the Papyrus Plug-in Builder features. This builder can be applied to an Eclipse Plug-in contributing Papyrus Toolsmiths customizations, to ensure its well-formedness.

Bugzilla tickets corresponding to this work are tracked here: Bug 568494: Toolsmith UX Improvements

Builder

The builder is not applied by default. It must be installed on Eclipse plug-ins that contribute extensions to Papyrus. To do so, right click on one or several Plug-ins, Configure > Convert to Papyrus plug-in.

The builder also needs to be enabled. As it is not always relevant, and might unnecessarily increase build time, it needs to be explicitly enabled in the preferences. Go to Window > Preferences > Papyrus > Papyrus Plugin Builder, and check "Activate the Papyrus Plugin builder".

Profiles

TODO: Configure the plug-in to deploy a profile; static profile vs dynamic profile; validation rules

Element Types

TODO: Generate *.elementtypesconfiguration model from a Profile; validation rules

In Papyrus, the creation and edition of element relies on the GMF Runtime "Element Types" API. An ElementType is a higher-level concept on top of EMF EClasses, used for creation and editing of inter-related elements (Such as base UML Elements, stereotyped UML Elements, or multiple related UML Element such as Associations + AssociationEnds).

For custom UML Profiles, Papyrus provides a tool to automatically generate an "ElementTypesConfiguration" model from a Profile. This model will contain one ElementTypeConfiguration (SpecializationTypeConfiguration) for each Stereotype in the profile, which can be used to create stereotyped elements (e.g. from the palette). This model can also be used to add rules ("advice") that will be invoked when the element is modified.

Creation

To generate the *.elementtypesconfiguration model from an existing Profile:

• Open the Profile with the Papyrus Editor
• In the Model Explorer, right click on the Profile > Generate Tooling Model > Element Types...
• Specify a filename for the ElementTypeSet and select the target folder
• Press Finish

If the folder is part of an Eclipse Plug-in, the Wizard will configure the plug-in automatically (Adding extension points, required plug-in dependencies, ...)

Element Types Configurations Model

References:

• Bug 568782 Allow specification of AdviceBindingConfiguration as children of ElementTypes
• Bug 568853 Add "MatchAndApply" Stereotype Matcher

Core

Element Types Configurations Model

• Added Generalizations
  • ContainerConfiguration adds a generalization to ConfigurationElement
  • AbstractMatcherConfiguration adds a generalization to ConfigurationElement
• Changed Associations
  • A_elementTypeConfigurations_owningSet
    • make a navigable end ElementTypeConfiguration::owningSet in the composition association from ElementTypeSetConfiguration to ElementTypeConfiguration
  • A_adviceBindingsConfigurations_owningSet
    • make a navigable end AbstractAdviceBindingConfiguration::owningSet in the composition association from ElementTypeSetConfiguration to ElementTypeConfiguration
  • A_containerConfiguration_containedType
    • make a navigable end ContainerConfiguration::containedType subsets ConfigurationElement::owningType
    • existing end SpecializationTypeConfiguration::containerConfiguration subsets ElementTypeConfiguration::ownedConfigurations
      • Note that this changes the serialization of configuration models when saved with this new schema. Older versions of Papyrus will not be able to read the models after saving. However, existing models will load because the existing <containerConfiguration> elements in the XMI are mapped to the subset. On save, those references are "moved" to <ownedConfigurations> elements
  • A_matcherConfiguration_matchedType
    • make a navigable end AbstractMatcherConfiguration::matchedType subsets ConfigurationElement::owningType
    • existing end SpecializationTypeConfiguration::matcherConfiguration subsets ElementTypeConfiguration::ownedConfigurations
      • Note that this changes the serialization of configuration models when saved with this new schema. Older versions of Papyrus will not be able to read the models after saving. However, existing models will load because the existing <matcherConfiguration> elements in the XMI are mapped to the subset. On save, those references are "moved" to <ownedConfigurations> elements
  • A_editHelperAdviceConfiguration_target
    • existing end AbstractEditHelperAdviceConfiguration::target now subsets ConfigurationElement::owningType
    • existing end SpecializationTypeConfiguration::editHelperAdviceConfiguration subsets ElementTypeConfiguration::ownedConfigurations
      • Note that this changes the serialization of configuration models when saved with this new schema. Older versions of Papyrus will not be able to read the models after saving. However, existing models will load because the existing <editHelperAdviceConfiguration> elements in the XMI are mapped to the subset. On save, those references are "moved" to <ownedConfigurations> elements
• Added Associations
  • A_ownedConfigurations_owningType
    • 1-to-many composition from ElementTypeConfiguration to ConfigurationElement that unifies all owned configurations in a single property. This association is subsetted by others in the ElementTypeConfiguration class and its subclasses
    • owningType has multiplicity [0..1] because some configurations are owned directly by the ElementTypeSetConfiguration (such as, in all cases, ElementTypeConfigurations themselves)
  • A_ownedAdvice_owningTarget
    • 1-to-many composition from ElementTypeConfiguration to AbstractAdviceBindingConfiguration, containing private advice bindings that apply only to the particular type (and its specializations, depending on the advice binding inheritance)
    • ElementTypeConfiguration::ownedAdvice subsets ElementTypeConfiguration::ownedConfigurations
    • AbstractAdviceBindingConfiguration::owningTarget subsets ConfigurationElement::owningType
    • AbstractAdviceBindingConfiguration::owningTarget also subsets AbstractAdviceBindingConfiguration::target so that the target element type is the owning type if the advice binding is owned
  • A_elementTypeSet_allAdviceBindings
    • 1-to-many association from ElementTypeSetConfiguration to AbstractAdviceBindingConfiguration
    • derived navigable end ElementTypeSetConfiguration::allAdviceBindings computes all AbstractAdviceBindingConfigurations directly contained (via ElementTypeSetConfiguration::adviceBindingsConfigurations) and indirectly contained (via ElementTypeConfiguration::ownedAdvice)
    • derived navigable end AbstractAdviceBindingConfiguration::elementTypeSet computes the set configuration that is either the owner (via AbstractAdviceBindingConfiguration::owningSet) or the owner of the type configuration that is the AbstractAdviceBindingConfiguration::owningType
• Added Constraints
  • AbstractAdviceBindingConfiguration::apply_to_all_types
    • OCL: applyToAllTypes = target.oclIsUndefined()
    • requires the applyToAllTypes property to be true or false as the target property is null or references some element-type configuration, respectively
    • when evaluated by model validation in the Element Types Configurations Editor (which is now re-generated for live validation support), violation of this constraint is reported as an error because the purpose of the applyToAllTypes property is the developer's assertion that the target is intentionally set or unset
    • when evaluated by model validation in the loading of the Element Types Configurations Registry, violations of the constraint are reported as warnings. This ensures that existing models, which will all violate the constraint until updated if they have advice bindings with unset targets, will not be rejected from the registry for backwards compatibility.
      • the registry is update to log all validation warnings, even if there are no errors, so that developers can see in the logs that their models need to be updated to address the new constraint
• Other notes
  • All existing models extending the Element Types Configurations model (in Core and UML layers) are re-generated so that the code correctly inherits and supports the new properties in these classes
  • The EMF.Edit layer for the Element Types Configurations model is updated to present the subsets of the ElementTypeConfiguration::ownedElements property as child properties in the tree editor. This ensures that the editor does not suggest creation commands for inappropriate children (such as nested element-type configurations or configuration sets)

UML Layer

Stereotype Matcher Configuration Model

• Added Classes
  • StereotypeMatcherAdviceConfiguration
    • generalization to StereotypeApplicationMatcherConfiguration
    • generalization to AbstractAdviceBindingConfiguration
    • instances of this class are both matcher configuration and advice binding configuration to specify in one element the configuration of a stereotype-based SpecializationTypeConfiguration. The matcher matches existing UML model elements by the applied stereotype and the advice applies the stereotype on creation of new UML model elements. The purpose is to streamline the definition of stereotype-based element types for the most common use cases in UML Profiles, especially the generation of element type configuration models from profiles
• Other notes
  • In order to ensure proper support for the associations (especially subset constraints) inherited from the core Element Types Configurations Model, the Stereotype Matcher model is exported to UML and that UML is now used as the source for code generation via the genmodel
  • 

    Multiple Configuration Roles
    As a single instance of the new StereotypeMatcherAdviceConfiguration, contained in an element type via ElementTypeConfiguration::ownedConfigurations, will be present in two of its subsets (ElementTypeConfiguration::ownedAdvice and SpecializationTypeConfiguration::matcherConfiguration), it appears twice in the tree under its owning element type. The EMF.Edit layer for the Element Types Configurations model wraps such objects to indicate the multiple roles that they play in the model

Validation

Model Rules

Element Types Configurations

Core constraints:

• AbstractAdviceBindingConfiguration::apply_to_all_types
  • OCL: applyToAllTypes = target.oclIsUndefined()
  • see detailed description