Touchstone
How-to guides

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

  1. In the Enabler's «ImplementationPackage», create a Concept Mapping and name it after the Concept.
  2. Draw an «Implements» from the mapping to the Concept. mappedConcept on the mapping and mappings on the Concept now show the link.
  3. Write the rationale on 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 meanSet
every element carrying one stereotypestereotype alone; the metaclass follows from the stereotype
every element of one metaclass, stereotyped or notmetaclasses alone
one metaclass among several a stereotype extendsboth; metaclasses narrows
only the elements under one packagescope, one or more owners, read transitively
specializations of the stereotype, or sub-metaclasses, as wellincludeSubtypes, off by default
a condition none of the above statesfilter

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:

  1. In the «ImplementationPackage», beside the mapping, create an Opaque Behavior and name it after the condition, such as Is Leaf Block.
  2. Give it two parameters: element : Element [1], direction in, typed by the metaclass Element of the UML2 Metamodel; and result : Boolean [1], direction return.
  3. 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 than THIS, which does not stand for the candidate.
  4. Set the mapping's filter tag 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

  1. 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.
  2. Set one of the four tags:
The value or the target is held bySet
a property of the mapped metaclass, such as Class::ownedAttributemetaProperty
a tag of a stereotype, such as SysML's satisfiedBytag
a derived property a customization definesderivedProperty
a navigation none of the above states, a path with intermediate filtersquery, 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.

On this page