Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Graphical Modeling Framework/Models/GMFMap"

m
 
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{GMF}}
 +
 +
The .gmfmap files is the glue between all other definition models: it maps EObjects with Graphical Elements and tools; and it is the file that defines the possible relationships in the editor (links, containment...)
 +
 +
== Metamodel ==
 +
 +
[[Image:Mapping.png|thumb|center|400px|GMF Graphical items metamodel]]
 +
 
== Scenarios ==
 
== Scenarios ==
* Show children elements from non-containment feature
+
=== Show children elements from non-containment feature ===
*: Generally, '''Containment Feature''' of '''Node Reference''' specifies where to put newly created child to, while '''Children Feature''' is there to find out where to take children from to display them. It's quite often that these two are the same, hence '''Children Feature''' defaults to value of '''Containment Feature'''.  
+
* Generally, the '''Containment Feature''' of a '''Node Reference''' specifies where to put a newly created child, while '''Children Feature''' specifies where to take children from in order to display them. It's quite often that these two are the same, hence '''Children Feature''' defaults to value of '''Containment Feature'''.  
*: To show children from feature different from the one they are contained with, simply set it as '''Children Feature'''. You'll need to specify '''Containment Feature''' as well.
+
* To show children from feature that is different from the one they are contained in, simply set it as '''Children Feature'''. Note that you'll need to specify '''Containment Feature''' as well.
  
* Endless/recursive hierarchies
+
=== Endless/recursive hierarchies ===
*: '''ChildReference''' not necessarily owns node mapping, it's possible to point to existing '''NodeMapping''', defined elsewhere. Reusing '''NodeMapping''' allows to create endless hierarchies of elements, e.g. ''StateMachine'' owns ''State'' (via ''states'' containment ref), and ''State'' owns other ''State''s (via ''substates'' containment). To get endless ''State'' hierarchy define '''TopNodeReference''' with ''states'' set as '''Containment Feature''', which owns '''NodeMapping''' (referencing ''State'' and appropriate diagram node and palette element). '''ChildReference''' of the '''NodeMapping''' specifies ''substates'' as '''Containment Feature''' and the owning '''NodeMapping''' as its '''Referenced Child'''. That's it.
+
* '''ChildReference''' not necessarily owns node mapping, it's possible to point to existing '''NodeMapping''', defined elsewhere. Reusing '''NodeMapping''' allows to create endless hierarchies of elements, e.g. ''StateMachine'' owns ''State'' (via ''states'' containment ref), and ''State'' owns other ''State''s (via ''substates'' containment). To get endless ''State'' hierarchy define '''TopNodeReference''' with ''states'' set as '''Containment Feature''', which owns '''NodeMapping''' (referencing ''State'' and appropriate diagram node and palette element). '''ChildReference''' of the '''NodeMapping''' specifies ''substates'' as '''Containment Feature''' and the owning '''NodeMapping''' as its '''Referenced Child'''. That's it.
 +
* [[news://news.eclipse.org/e97uq0$ffj$1@utils.eclipse.org Newsgroup post]] with set of models illustrating this approach (there's no domain model, still, the concept of '''NodeMapping''' reuse is depicted).
  
* Use same creation tool to create various diagram elements
+
=== Use same creation tool to create various diagram elements ===
*: Few mappings can point to same tool definition in the .gmftool model. Transformation (.gmfmap -> .gmfgen) is smart enough to recognize that and creates only one tool capable of creating several metamodel types. It's not possible to use the same tool to create both nodes and links, though.
+
* Multiple mappings can point to same tool definition in the .gmftool model. Transformation (.gmfmap -> .gmfgen) is smart enough to recognize this case and creates only one tool capable of creating several metamodel types. It's not possible to use the same tool to create both nodes and links, however.
  
* Specialize domain element
+
=== Specialize domain element ===
*: Sometimes you may '''EClass''' is not sufficient and there's need to further nail down what domain element to use. For example, ECore diagram's aggregation and association references - '''EReference''' with '''containment''' attrubute set to '''true''' should be visualized differently from those with '''containment''' set to '''false'''. In such case add '''Constraint''' to as '''MappingEntry.domainSpecialization'''. Though constraint may not be the best term, it's just what specialization is about - constrain domain element to particular kind. OCL is default language to express specialization, although Java and few others are supported.  
+
* Sometimes you may find that '''EClass''' is insufficient, and there is a need to more specifically define what domain element to use. For example, ECore diagram's aggregation and association references - '''EReference''' with '''containment''' attribute set to '''true''' should be visualized differently from those with '''containment''' set to '''false'''. In this case, add a '''Constraint''' to as '''MappingEntry.domainSpecialization'''. Although constraint may not be the best term, it's just what specialization is about - constrain domain element to particular kind. OCL is the default language to express specialization, although Java and others are supported.  
*:Note, with specialized domain elements there's often need to perform initializations that set appropriate attributes on element creation, see next session for details
+
* Note: with specialized domain elements there's often a need to perform initializations that sets the appropriate attributes on element creation. See the section on feature initialization.
  
* Initialize domain element
+
=== Init Diagram File Action doesn't work with nested container! ===
 +
* Imagine a simple domain model with '''Entity''' and '''Container''' elements, both non-abstract classes. '''Container''' has a containment reference to and extends '''Entity''' (think of well known GoF ''Composite'' pattern). A '''GMFMap''' model then defines a '''NodeMapping''' for '''Container''', and two child references, one for '''Entity''', another for a nested '''Container'''. Both child references use the same containment reference. With that, creating a diagram from palette works fine, although the init diagram file action appears not to go any deeper than the first level (i.e. nothing below the nested container is shown). Plus (and this is another sign of the problem), the nested container itself looks like an '''Entity''' and not like '''Container'''. The reason is the action can't tell '''Container''' from '''Entity''' without explicit help from you as the model author. To resolve this, add a '''Constraint''' to the '''Entity''' mapping with an ''oclIsTypeOf'' expression (e.g. ''self.oclIsTypeOf(metamodel::Entity)''). With this constraint, the generated code will be capable of distinguishing between the two elements.
 +
* In case you don't want to use OCL and would prefer to do it in code, the method XXXVisualIDRegistry.isNode<MetaclassName>_<VisualID>() is the place to put it.
  
* Constrain link creation
+
=== Initialize domain element ===
 +
* ''tbd''
  
* Validating domain model during edit ('Live' constraints)
+
=== Constrain link creation ===
 +
* ''tbd''
  
 +
=== Validating domain model during edit ('Live' constraints) ===
 +
* ''tbd''
  
 
== Why? ==
 
== Why? ==
# '''TopNodeReference''' and '''ChildReference'''. The major difference is that top node references may only own child '''NodeMapping''', not reuse existing as it seems confusing to allow for that. If you like to reuse some child '''NodeMapping''' for top node, you can do it other way round, i.e. reuse top node for child. Reusing another top node is not possible (are there models with different containments/children features for same elements to justify this use-case?). Also, there's no much sense to define compartments for diagam immediate children (hmm, that might be enhancement request, though I never saw such uses...), hence another difference from '''ChildReference'''. Last, '''TopNodeReference''' has no parent node.
+
# '''TopNodeReference''' and '''ChildReference'''. The major difference is that top node references may only own child '''NodeMapping''', not reuse existing elements as it seems confusing to allow for that. If you would like to reuse some child '''NodeMapping''' for a top node, you can do it the other way round, i.e. reuse top node for child. Reusing another top node is not possible (are there models with different containments/children features for same elements to justify this use-case?). Also, there's not much sense in defining compartments for a diagram's immediate children (hmm, that might be enhancement request, although I never saw such uses...), hence another difference from '''ChildReference'''. Lastly, a '''TopNodeReference''' has no parent node.
 
# '''EClass''', not ElementType/whatever as domainElement?
 
# '''EClass''', not ElementType/whatever as domainElement?
 
  
 
== GMFMap's POI (points of interest) ==
 
== GMFMap's POI (points of interest) ==
Line 39: Line 53:
 
*: Shows actual node mapping taken as child (either from '''ownedChild''' or '''referencedChild''')
 
*: Shows actual node mapping taken as child (either from '''ownedChild''' or '''referencedChild''')
 
*: There's no much sense to set both ownedChild and referencedChild properties.
 
*: There's no much sense to set both ownedChild and referencedChild properties.
 
=== Label Mapping Properties ===
 
* View Pattern - <code>java.text.MessageFormat</code>
 
* Edit Pattern - <code>java.text.MessageFormat</code>
 

Latest revision as of 11:31, 19 July 2012



GMF
Website
Download
Dev Builds
Update Site releases milestones
Community
Mailing ListNewsgroupIRC
Bugzilla
Open
Help Wanted
Bug Day
Source
GMF Notation: View CVS repo

GMF Runtime: View CVS repo
GMF Tooling: View Git Repo, GitHub


The .gmfmap files is the glue between all other definition models: it maps EObjects with Graphical Elements and tools; and it is the file that defines the possible relationships in the editor (links, containment...)

Metamodel

GMF Graphical items metamodel

Scenarios

Show children elements from non-containment feature

  • Generally, the Containment Feature of a Node Reference specifies where to put a newly created child, while Children Feature specifies where to take children from in order to display them. It's quite often that these two are the same, hence Children Feature defaults to value of Containment Feature.
  • To show children from feature that is different from the one they are contained in, simply set it as Children Feature. Note that you'll need to specify Containment Feature as well.

Endless/recursive hierarchies

  • ChildReference not necessarily owns node mapping, it's possible to point to existing NodeMapping, defined elsewhere. Reusing NodeMapping allows to create endless hierarchies of elements, e.g. StateMachine owns State (via states containment ref), and State owns other States (via substates containment). To get endless State hierarchy define TopNodeReference with states set as Containment Feature, which owns NodeMapping (referencing State and appropriate diagram node and palette element). ChildReference of the NodeMapping specifies substates as Containment Feature and the owning NodeMapping as its Referenced Child. That's it.
  • [Newsgroup post] with set of models illustrating this approach (there's no domain model, still, the concept of NodeMapping reuse is depicted).

Use same creation tool to create various diagram elements

  • Multiple mappings can point to same tool definition in the .gmftool model. Transformation (.gmfmap -> .gmfgen) is smart enough to recognize this case and creates only one tool capable of creating several metamodel types. It's not possible to use the same tool to create both nodes and links, however.

Specialize domain element

  • Sometimes you may find that EClass is insufficient, and there is a need to more specifically define what domain element to use. For example, ECore diagram's aggregation and association references - EReference with containment attribute set to true should be visualized differently from those with containment set to false. In this case, add a Constraint to as MappingEntry.domainSpecialization. Although constraint may not be the best term, it's just what specialization is about - constrain domain element to particular kind. OCL is the default language to express specialization, although Java and others are supported.
  • Note: with specialized domain elements there's often a need to perform initializations that sets the appropriate attributes on element creation. See the section on feature initialization.

Init Diagram File Action doesn't work with nested container!

  • Imagine a simple domain model with Entity and Container elements, both non-abstract classes. Container has a containment reference to and extends Entity (think of well known GoF Composite pattern). A GMFMap model then defines a NodeMapping for Container, and two child references, one for Entity, another for a nested Container. Both child references use the same containment reference. With that, creating a diagram from palette works fine, although the init diagram file action appears not to go any deeper than the first level (i.e. nothing below the nested container is shown). Plus (and this is another sign of the problem), the nested container itself looks like an Entity and not like Container. The reason is the action can't tell Container from Entity without explicit help from you as the model author. To resolve this, add a Constraint to the Entity mapping with an oclIsTypeOf expression (e.g. self.oclIsTypeOf(metamodel::Entity)). With this constraint, the generated code will be capable of distinguishing between the two elements.
  • In case you don't want to use OCL and would prefer to do it in code, the method XXXVisualIDRegistry.isNode<MetaclassName>_<VisualID>() is the place to put it.

Initialize domain element

  • tbd

Constrain link creation

  • tbd

Validating domain model during edit ('Live' constraints)

  • tbd

Why?

  1. TopNodeReference and ChildReference. The major difference is that top node references may only own child NodeMapping, not reuse existing elements as it seems confusing to allow for that. If you would like to reuse some child NodeMapping for a top node, you can do it the other way round, i.e. reuse top node for child. Reusing another top node is not possible (are there models with different containments/children features for same elements to justify this use-case?). Also, there's not much sense in defining compartments for a diagram's immediate children (hmm, that might be enhancement request, although I never saw such uses...), hence another difference from ChildReference. Lastly, a TopNodeReference has no parent node.
  2. EClass, not ElementType/whatever as domainElement?

GMFMap's POI (points of interest)

Node and Link Mapping

These elements tie visual, tooling and metamodel element together. It's essentially a diagram element, with visual icon to show, tool to create and domain element to back up. Node Mappings are kept separate from Node References because same diagram element (described with Node Mapping) may appear in different parent-child relationships (both domain and visual).

Concept of Node References

  • Containment Feature
    - EReference with containment attribute set to true.
  • Children Feature
    - generally, non-containment EReference, the same as Containment Feature unless explicitly set. Usually, this feature is read-only filtering view to values in Containment Feature(Think of EClass.eAttributes and EClass.eOperations - both EOperation and EAttribute are owned via eClass.eStructuralFeatures). Though this EReference may be containment reference different from Containment Feature, it doesn't sound like reasonable use-case
  • Child
    Shows actual node mapping taken as child (either from ownedChild or referencedChild)
    There's no much sense to set both ownedChild and referencedChild properties.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.