Map a concept onto the tool
A «Concept» names something in the stakeholders' words. A «ConceptMapping» says which elements of the model are its individuals. This page builds one mapping, and one for an Attribute or a Relation.
Create the mapping
- In the Enabler's «ImplementationPackage», create a Concept Mapping and name it after the Concept.
- Draw an «Implements» from the mapping to the Concept.
mappedConcepton the mapping andmappingson the Concept now show the link. - Write the
rationaleon the «Implements» when the choice was not the obvious one: why Block rather than Class, why this package.
Say what the individuals are
The tags compose with AND. Set the fewest that select exactly the elements you mean.
| You mean | Set |
|---|---|
| every element carrying one stereotype | stereotype alone; the metaclass follows from the stereotype |
| every element of one metaclass, stereotyped or not | metaclasses alone |
| one metaclass among several a stereotype extends | both; metaclasses narrows |
| only the elements under one package | scope, one or more owners, read transitively |
| specializations of the stereotype, or sub-metaclasses, as well | includeSubtypes, off by default |
| a condition none of the above states | filter |
With the default, a mapping to Class selects the elements whose metaclass is Class and nothing
more. Setting includeSubtypes to true also selects every element whose metaclass specializes
Class in the tool: Activity, Component, StateMachine and Stereotype among them, and every carrier
of a stereotype that specializes the one in stereotype. A stereotyped Class, a SysML Block among them, carries Class as
its metaclass, so a mapping to Class selects it whatever includeSubtypes says, and only the
stereotype tag narrows the mapping to the carriers.
filter names an OpaqueBehavior the runtime calls once per candidate that passed the other tags;
the candidate stays when the behavior answers true. Write it in the tool:
- In the «ImplementationPackage», beside the mapping, create an Opaque Behavior and name it
after the condition, such as
Is Leaf Block. - Give it two parameters:
element : Element [1], direction in, typed by the metaclassElementof the UML2 Metamodel; andresult : Boolean [1], direction return. - Set the body's language to Structured Expression and build the expression in the editor. Set
its contextual variable to the parameter
element, the candidate the runtime passes, rather thanTHIS, which does not stand for the candidate. - Set the mapping's
filtertag to the behavior.
The candidate is always an Element, whatever the mapping's metaclasses say, so the parameter stays
typed Element; one behavior then serves every mapping that states the same condition. A behavior
that throws, answers anything but a Boolean, or that the tool cannot run makes the mapping yield
nothing, and one line naming the mapping is written in the log under Touchstone.
A mapping with a metaclass and a stereotype that metaclass cannot carry, such as Class with a
stereotype extending Activity, is well-formed and always empty. Check the stereotype's base metaclass
when individuals stays empty.
Say OR with two mappings
One mapping is one conjunction. A Concept whose individuals are, say, every Block or every «Function» Activity takes one of two forms:
- Two «ConceptMapping»s implementing the same Concept, one per kind. The Concept's individuals are the union.
- Two specializing Concepts, each with one mapping. Choose this form when the two kinds have different rules or serve different objectives, since a rule then constrains one of them.
Map an Attribute or a Relation
- Under the Concept's mapping, or beside it in the package, create an Attribute Mapping or a Relation Mapping and draw «Implements» to the Attribute or Relation.
- Set one of the four tags:
| The value or the target is held by | Set |
|---|---|
a property of the mapped metaclass, such as Class::ownedAttribute | metaProperty |
a tag of a stereotype, such as SysML's satisfiedBy | tag |
| a derived property a customization defines | derivedProperty |
| a navigation none of the above states, a path with intermediate filters | query, a behavior taking the individual and answering the value or the targets |
Set exactly one of the four. A mapping placed under a Concept's mapping applies to that mapping's individuals only; one placed in the package applies to every individual of the Concept.
A Relation's mapping navigates from the source Concept's element to the target Concept's elements.
An Attribute's mapping reads a value. query is written like a filter: an Opaque Behavior with the
in-parameter element : Element [1], the individual, and a return parameter result typed Element [0..*] for a Relation or the Attribute's type [0..*] for an Attribute; the body a Structured
Expression whose contextual variable is element. A query whose return parameter stays [1]
answers nothing for an individual with several values: the tool cannot pass more than one value
through a single-valued return, so the mapping yields nothing for that individual and writes one
line under the Touchstone log category, naming the mapping. The runtime reads whatever the behavior
answers as a collection: nothing, one value or many. A Relation keeps only the targets that are
individuals of its type Concept.
Write a behavior in code
A condition or a navigation the expression editor cannot state goes in a plugin of your own. The
behavior keeps the parameters above; its body's language is Binary and its body is the fully
qualified name of a class implementing com.nomagic.magicdraw.expressions.ParameterizedExpression
with one method, getValue(element: Element, context: ValueContext), returning Boolean for a
filter or the value or targets for a query. The plugin's Main.init() registers its classloader with
EvaluationConfigurator.getInstance().registerBinaryImplementers(Main::class.java.classLoader), or
the tool reports the class as not found. Touchstone's own derived properties, individuals among
them, are written this way; CustomizationShapeTest shows how a test ties the class to the expression.
Check the mapping
Open the Concept's specification window: individuals lists the elements its mappings select, as
the model stands. It is computed each time the window shows it, so a mapping over a large scope
takes a moment. _Topic_ Concept Mappings and _Topic_ Attribute and Relation Mappings list every
mapping with its tags and the element it implements. _Topic_ Ontology Implementation shows, as a
matrix, which Concepts, Attributes and Relations have a mapping and which have none.
An empty individuals on a Concept whose mapping names a metaclass and a stereotype that metaclass
cannot carry, such as Class with a stereotype extending Activity, is the expected answer; check
the stereotype's base metaclass.