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 "GMF: Synchronized Container Use Cases"

(Synchronized links)
(Bugzilla entries)
 
(32 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Preface ==
 
== Preface ==
In the current state GMF supports two modes of diagram code generation - synchronized and non-synchronised. Toolsmith is able to switch between these two modes by changing GenDiagram.synchronized property. There were a number of discussions concerning diagram behavior in different situations according to the current mode. The idea of this document is to summarize existing requirements to simplify upcoming features development. Once this document will be finalized, corresponding changes should be introduced into the code generator and the runtime part if necessary.
+
In the current state, GMF supports two modes of diagram code generation - synchronized and non-synchronized. A toolsmith is able to switch between these two modes by changing the GenDiagram.synchronized property. There have been a number of discussions concerning diagram behavior in different situations according to the current mode. The idea of this document is to summarize the existing requirements to simplify upcoming feature development. Once this document is finalized, corresponding changes will be introduced into the code generator and the runtime, if necessary.
  
This document will cover common use cases for different type of synchronized/non-synchronized diagrams from the end-user point of view and highlight corresponding places in code generator/runtime to be used to in corresponding conditions.
+
This document will cover common use cases for different types of synchronized/non-synchronized diagrams from the end-user point of view, and highlight corresponding places in code generator/runtime to be used in corresponding conditions.
  
 
== Definitions ==
 
== Definitions ==
  
''synchronized element'' – diagram node or diagram itself always representing actual domain (semantic) model contents. i.e. all the child diagram nodes recognized from the underlying domain model.
+
''synchronized element'' – a diagram or diagram node that always represents the actual domain (semantic) model contents (i.e. all the child diagram nodes recognized from the underlying domain model).
  
''canonical container'' – synchronized element.
+
''canonical container'' – a synchronized element, including contained elements.
  
''non-synchronized element'' – diagram node or diagram itself representing only selected child diagram nodes recognized from the domain model.
+
''non-synchronized element'' – a diagram or diagram node representing only selected child diagram nodes recognized from the domain model.
  
''synchronized diagram'' – diagram itself, all the diagram nodes and sub-nodes are ''synchronized elements''
+
''synchronized diagram'' – a diagram itself, all the diagram nodes and sub-nodes are ''synchronized elements''
  
''element-based link'' – diagram link associated with the element in a domain model connecting link source with link target domain model elements.
+
''element-based link'' – a diagram link associated with the element in a domain model connecting link source with link target domain model elements.
  
''reference-only link'' – diagram link representing reference in a domain model. This reference contained in a link source domain model element and pointing to the link target domain model element.
+
''reference-only link'' – a diagram link representing a reference in a domain model. This reference is contained in a link source domain model element and points to the link target domain model element.
  
''CanonicalEditPolicy'' - abstract class in GMF runtime implementing EditPolicy and encapsulating set of functionality useful for synchronizing diagram element contents with the domain model element contents.  
+
''pure-design element'' - a diagram or diagram node without link to the underlying domain model (View.getElement() == null and not ''reference-only link'')
 +
 
 +
''CanonicalEditPolicy'' - an abstract class in the GMF runtime implementing EditPolicy and encapsulating a set of functionality useful for synchronizing diagram element contents with the domain model element contents.  
  
 
''CanonicalConnectionEditPolicy'' – abstract subclass of ''CanonicalEditPolicy'' supporting outgoing element-based diagram links synchronization.
 
''CanonicalConnectionEditPolicy'' – abstract subclass of ''CanonicalEditPolicy'' supporting outgoing element-based diagram links synchronization.
  
== Synchronized elements ==
+
== Synchronized diagram ==
Each ''synchronized element'' should always represent up to date content of the corresponding domain model element. Following cases should be covered:
+
This type of the diagram will be generated if GenDiagram.synchronized == true in the .gmfgen model. Updating code (''CanonicalEditPolicy'' subclasses) should be generated for each type of the ''synchronized element'' available on this diagram.
  
- domain model was changed in external editor in a way that new child diagram element could be recognized (new child domain element added) - diagram editor content should be updated with new child diagram element on next diagram opening.
+
By default, this diagram and all the contained nodes and links are ''synchronized elements''. A Toolsmith can switch off synchronization for any diagram element/diagram by attaching CanonicalStyle with isCanonical() == false to the corresponding diagram element (see below). If the synchronization process should be switched off for all the elements of some particular type, then a corresponding style could be attached to each View instance created by the corresponding ViewFactory. Hint: this could be done by customizing corresponding template.
  
- domain model was changed externally in a way that existing child diagram  element should be removed (child domain element removed) – corresponding child diagram element should be removed on next diagram opening.
+
=== Synchronized elements ===
 +
Each ''synchronized element'' should always represent up-to-date content of the corresponding domain model element. The following cases should be covered:
  
- domain model was changed by user code, new child diagram element could be recognized diagram editor content should be updated with new diagram element on receiving corresponding EMF notification.
+
- domain model was changed in external editor in a way that a new child diagram element could be recognized (new child domain element added) - diagram editor content should be updated with new child diagram element on next diagram opening.
  
- domain model was changed by user code, child diagram element removed corresponding child diagram element should be removed on receiving corresponding EMF notification.
+
- domain model was changed by user code in a way that a new child diagram element could be recognized – diagram editor content should be updated with new diagram element on receiving corresponding EMF notification.
  
- if same domain model element could be represented on diagram as a different diagram elements (node-1 or node-2) based on domain model properties and domain model was changed externally/by user code in a way existing domain model element should change diagram representation (not be recognized as node-1 anymore, but should be recognized as node-2) – existing node-1 should be replaced by node-2 on next diagram opening/receiving EMF notification. Node-2 should get size/position of node-1 and all the rest of applicable Styles.
+
- domain model was changed externally or by user code in a way that existing child diagram element should be removed (child domain element removed) – corresponding child diagram element should be removed on next diagram opening or corresponding EMF notification.
  
- if this ''synchronized element'' was just created by update process (''CanonicalEditPolicy'') and some child diagram elements could be recognized from the underlying domain model element then update should be triggered for this ''synchronized element'' to create corresponding diagram elements. In other words, on any model changes diagram should be updated to always represent actual domain model content.
+
- if the same domain model element can be represented on a diagram as different diagram elements (node-1 or node-2) based on domain model properties, and the domain model was changed externally or by user code in a way that the existing domain model element should change the diagram representation (not be recognized as node-1 anymore, but should be recognized as node-2) – the existing node-1 should be replaced by node-2 on next diagram opening or by receiving EMF notification. Node-2 should get the size/position of node-1 and all the rest of its applicable Styles.
  
- Notation model element represented by this ''synchronized element'' adorned with CanonicalStyle – it should be possible to switch on/off synchronization with domain model by calling CanonicalStyle.setCanonical(). If the synchronization was switched on then this ''synchronized element'' should be immediately synchronized with the model.
+
- if a ''synchronized element'' was just created by an update process (''CanonicalEditPolicy'') and some child diagram elements could be recognized from the underlying domain model element, then an update should be triggered for this ''synchronized element'' in order to create the corresponding diagram elements. In other words, on any model changes the diagram should be updated to always represent current domain model content.
  
== Synchronized links ==
+
- notation model element represented by this ''synchronized element'' adorned with CanonicalStyle – it should be possible to switch on/off synchronization with the domain model by calling CanonicalStyle.setCanonical(). If the synchronization was switched on, then this ''synchronized element'' should be immediately synchronized with the model. If the synchronization was switched off, then this element should behave like ''non-synchronized element''.
  
Each ''synchronized element'' should perform outgoing links synchronization in addition to child elements synchronization. Following cases should be covered:
+
- Delete action for any ''synchronized element'' should remove corresponding element/reference (for reference-only links) from the domain model.
  
- domain model was changed externally/by user code in a way that new link from this diagram element could be recognized - diagram editor content should be updated with new link on next diagram opening/receiving EMF notification. It is important to correctly process the situation then new link was added into domain model together with the new link destination node, so both elements should be created on diagram. Not created link destination node could be a sub-node of diagram node parent’s sibling node.
+
=== Links synchronization ===
  
- domain model was changed externally/by user code in a way that existing link should be removed from diagram– corresponding link should be removed on next diagram opening/receiving EMF notification.
+
Each ''synchronized element'' should perform outgoing link synchronization (both ''element-based links'' and ''reference-only links'') in addition to child elements synchronization. Following cases should be covered:
  
- if same domain model element (or even reference!) could be represented on diagram as a different links (link-1 or link-2) based on domain model properties and domain model was changed externally/by user in a way existing link-1 should be replaced by link-2 – corresponding diagram update should be performed on next diagram opening/receiving EMF notification. Newly created link-2 should get all bending/connection points of link-1 and all the rest of applicable Styles.
+
- domain model was changed externally or by user code in a way that a new link from this diagram element could be recognized - diagram editor content should be updated with new link on next diagram opening/receiving EMF notification. It is important to correctly process the situation when a new link was added to domain model together with the new link destination node so both elements should be created on diagram. Note that a created link destination node could be a sub-node of diagram node parent’s sibling node. (*)
  
- if this ''synchronized element'' was just created by update process (''CanonicalEditPolicy'') and some outgoing links could be recognized from the underlying domain model then update should create all the necessary links.
+
- domain model was changed externally or by user code in a way that an existing link should be removed from diagram – corresponding link should be removed on next diagram opening/receiving EMF notification.
  
- if this ''synchronized element'' is a link and some other links could be created starting from this link then corresponding outgoing links should be updated in accordance with domain model content and so forth. If this ''synchronized element'' adorned with CanonicalStyle then it should be possible to switch on/off synchronization of outgoing links with domain model by calling CanonicalStyle.setCanonical(). If the synchronization was switched on all the outgoing links should be immediately synchronized with the model.
+
- if same domain model element (or even reference!) could be represented on diagram as a different link (link-1 or link-2) based on domain model properties and domain model was changed externally or by user code in a way existing link-1 should be replaced by link-2 – corresponding diagram update should be performed on next diagram opening/receiving EMF notification. Newly created link-2 should get all bending/connection points of link-1 and all the rest of its applicable Styles.
 +
 
 +
- if a ''synchronized element'' was created by an update process (''CanonicalEditPolicy'') and some outgoing link can be recognized from the underlying domain model, then update should create all the necessary links.
 +
 
 +
- if a ''synchronized element'' is a link and some other links can be created starting from this link, then the corresponding outgoing links should be updated in accordance with the domain model content, and so forth. If this ''synchronized element'' is adorned with a CanonicalStyle, then it should be possible to switch on/off the synchronization of outgoing links with the domain model by calling CanonicalStyle.setCanonical(). If synchronization is switched on, all the outgoing links should be immediately synchronized with the model.
 +
<br><br>
 +
 
 +
(*) Illustration:
 +
 
 +
1. initial diagram diagram structure:
 +
node TopNode {
 +
    node SubNode {
 +
    }
 +
    node SubNodeSibling {
 +
    }
 +
}
 +
 
 +
2. final diagram structure:
 +
node TopNode {
 +
    node SubNode {
 +
      node LinkSource {
 +
          link MyLink {
 +
            destination LinkTarget;
 +
          }
 +
      }
 +
    }
 +
    node SubNodeSibling {
 +
      node LinkTarget {
 +
      }
 +
    }
 +
}
 +
 
 +
Diagram updater should correctly process this situation and update diagram from state 1. to state 2. MyLink is a link connecting LinkSource with LinkTarget. Source and Target nodes of the link have same "grandfather". (Source and Target of the link are "cousins" :-) )
 +
 
 +
== Non-Synchronized diagrams ==
 +
This type of the diagram will be generated if GenDiagram.synchronized == false in .gmfgen model. No synchronization code should be generated for elements of this diagram. Only selected by user subset of ''non-synchronized elements'' should be represented on this diagram. Any ''non-synchronized element'' created on this diagram from the toolbar should be immediately visualized on diagram. In addition it should be possible to:
 +
 
 +
- invoke “Import child elements” popup menu action on each ''non-synchronized element'' (diagram node or diagram itself). This action will show the dialog with all the child diagram elements recognized from the model element associated with this ''non-synchronized element'', but invisible on diagram currently. It should be possible to select any number of diagram elements from this dialog and add corresponding ''non-synchronized elements'' to this diagram. Ideal solution is to show tree of the direct child elements and their children. This tree should be equipped with checkboxes allowing to add the element with all it’s children or selected subset of child elements.
 +
 
 +
- invoke “Import outgoing link” popup menu action on each ''non-synchronized element''. This action should show dialog listing all the links recognized from domain model, outgoing from this ''non-synchronized element'' and invisible on current diagram. It should be possible to add selected links to the diagram. Note: ''non-synchronized element'' could be a link.
 +
 
 +
- Delete any ''non-synchronized element'' from view should remove this element from the diagram and keep domain model unchanged.
 +
 
 +
- Delete from model action should remove both ''non-synchronized element'' and corresponding element/reference (for ''reference-only links'') from the domain model.
 +
 
 +
=== Non-Synchronized elements ===
 +
Each ''non-synchronized element'' should still listen for the domain model changes to support the following cases:
 +
 
 +
- domain model was changed externally or by user code in a way that existing diagram  element should be removed (domain element removed) – corresponding diagram element should be removed on next diagram opening or corresponding EMF notification.
 +
 
 +
- if the same domain model element can be represented on diagram as a different diagram elements (node-1 or node-2) based on domain model properties and the domain model was changed externally or by user code in a way that the existing domain model element should change the diagram representation (not be recognized as node-1 anymore, but should be recognized as node-2) – the existing node-1 should be replaced by node-2 on next diagram opening or by receiving EMF notification. Node-2 should get the size/position of node-1 and all the rest of applicable Styles.
 +
 
 +
=== Non-Synchronized links ===
 +
Each link on non-synchronized diagram should be updated in case of following changes in domain model:
 +
 
 +
- if same domain model element (or even reference!) can be represented on diagram as a different link (link-1 or link-2) based on domain model properties and domain model was changed externally or by user code in a way that existing link-1 should be replaced by link-2 – corresponding diagram update should be performed on next diagram opening or by receiving EMF notification. Newly created link-2 should get all the bending/connection points of link-1 and all the rest of its applicable Styles.
 +
 
 +
- domain model was changed externally or by user code in a way that an existing link should be removed from diagram– corresponding link should be removed on next diagram opening/receiving EMF notification.
 +
 
 +
== Pure-design elements ==
 +
Not synchronisation or updating code should be generated for this type of the elements. In particular: ''CanonicalEditPolicy'' should neither be generated nor installed for the corresponding EditPart, CanonicalStyle should not be created by corresponding ViewFactory.
  
== Non-Synchronized elements ==
 
== Useing code generator to generate element synchronization ==
 
=== GenDiagram.synchronized property ===
 
=== Switching On/Off Synchronization ===
 
 
== HREFs ==
 
== HREFs ==
 +
=== Bugzilla entries ===
 +
 +
[http://bugs.eclipse.org/bugs/show_bug.cgi?id=150257 <strike>#150257</strike>]
 +
 +
[http://bugs.eclipse.org/bugs/show_bug.cgi?id=150408 #150408]
 +
 +
[http://bugs.eclipse.org/bugs/show_bug.cgi?id=133505 #133505]
 +
 +
[http://bugs.eclipse.org/bugs/show_bug.cgi?id=148275 #148275]
 +
 +
[http://bugs.eclipse.org/bugs/show_bug.cgi?id=180786 #180786]
 +
 +
[http://bugs.eclipse.org/bugs/show_bug.cgi?id=184130 #184130]
 +
 +
=== Newsgroup threads ===
 +
http://dev.eclipse.org/newslists/news.eclipse.modeling.gmf/msg05117.html

Latest revision as of 11:01, 30 April 2007

Preface

In the current state, GMF supports two modes of diagram code generation - synchronized and non-synchronized. A toolsmith is able to switch between these two modes by changing the GenDiagram.synchronized property. There have been a number of discussions concerning diagram behavior in different situations according to the current mode. The idea of this document is to summarize the existing requirements to simplify upcoming feature development. Once this document is finalized, corresponding changes will be introduced into the code generator and the runtime, if necessary.

This document will cover common use cases for different types of synchronized/non-synchronized diagrams from the end-user point of view, and highlight corresponding places in code generator/runtime to be used in corresponding conditions.

Definitions

synchronized element – a diagram or diagram node that always represents the actual domain (semantic) model contents (i.e. all the child diagram nodes recognized from the underlying domain model).

canonical container – a synchronized element, including contained elements.

non-synchronized element – a diagram or diagram node representing only selected child diagram nodes recognized from the domain model.

synchronized diagram – a diagram itself, all the diagram nodes and sub-nodes are synchronized elements

element-based link – a diagram link associated with the element in a domain model connecting link source with link target domain model elements.

reference-only link – a diagram link representing a reference in a domain model. This reference is contained in a link source domain model element and points to the link target domain model element.

pure-design element - a diagram or diagram node without link to the underlying domain model (View.getElement() == null and not reference-only link)

CanonicalEditPolicy - an abstract class in the GMF runtime implementing EditPolicy and encapsulating a set of functionality useful for synchronizing diagram element contents with the domain model element contents.

CanonicalConnectionEditPolicy – abstract subclass of CanonicalEditPolicy supporting outgoing element-based diagram links synchronization.

Synchronized diagram

This type of the diagram will be generated if GenDiagram.synchronized == true in the .gmfgen model. Updating code (CanonicalEditPolicy subclasses) should be generated for each type of the synchronized element available on this diagram.

By default, this diagram and all the contained nodes and links are synchronized elements. A Toolsmith can switch off synchronization for any diagram element/diagram by attaching CanonicalStyle with isCanonical() == false to the corresponding diagram element (see below). If the synchronization process should be switched off for all the elements of some particular type, then a corresponding style could be attached to each View instance created by the corresponding ViewFactory. Hint: this could be done by customizing corresponding template.

Synchronized elements

Each synchronized element should always represent up-to-date content of the corresponding domain model element. The following cases should be covered:

- domain model was changed in external editor in a way that a new child diagram element could be recognized (new child domain element added) - diagram editor content should be updated with new child diagram element on next diagram opening.

- domain model was changed by user code in a way that a new child diagram element could be recognized – diagram editor content should be updated with new diagram element on receiving corresponding EMF notification.

- domain model was changed externally or by user code in a way that existing child diagram element should be removed (child domain element removed) – corresponding child diagram element should be removed on next diagram opening or corresponding EMF notification.

- if the same domain model element can be represented on a diagram as different diagram elements (node-1 or node-2) based on domain model properties, and the domain model was changed externally or by user code in a way that the existing domain model element should change the diagram representation (not be recognized as node-1 anymore, but should be recognized as node-2) – the existing node-1 should be replaced by node-2 on next diagram opening or by receiving EMF notification. Node-2 should get the size/position of node-1 and all the rest of its applicable Styles.

- if a synchronized element was just created by an update process (CanonicalEditPolicy) and some child diagram elements could be recognized from the underlying domain model element, then an update should be triggered for this synchronized element in order to create the corresponding diagram elements. In other words, on any model changes the diagram should be updated to always represent current domain model content.

- notation model element represented by this synchronized element adorned with CanonicalStyle – it should be possible to switch on/off synchronization with the domain model by calling CanonicalStyle.setCanonical(). If the synchronization was switched on, then this synchronized element should be immediately synchronized with the model. If the synchronization was switched off, then this element should behave like non-synchronized element.

- Delete action for any synchronized element should remove corresponding element/reference (for reference-only links) from the domain model.

Links synchronization

Each synchronized element should perform outgoing link synchronization (both element-based links and reference-only links) in addition to child elements synchronization. Following cases should be covered:

- domain model was changed externally or by user code in a way that a new link from this diagram element could be recognized - diagram editor content should be updated with new link on next diagram opening/receiving EMF notification. It is important to correctly process the situation when a new link was added to domain model together with the new link destination node so both elements should be created on diagram. Note that a created link destination node could be a sub-node of diagram node parent’s sibling node. (*)

- domain model was changed externally or by user code in a way that an existing link should be removed from diagram – corresponding link should be removed on next diagram opening/receiving EMF notification.

- if same domain model element (or even reference!) could be represented on diagram as a different link (link-1 or link-2) based on domain model properties and domain model was changed externally or by user code in a way existing link-1 should be replaced by link-2 – corresponding diagram update should be performed on next diagram opening/receiving EMF notification. Newly created link-2 should get all bending/connection points of link-1 and all the rest of its applicable Styles.

- if a synchronized element was created by an update process (CanonicalEditPolicy) and some outgoing link can be recognized from the underlying domain model, then update should create all the necessary links.

- if a synchronized element is a link and some other links can be created starting from this link, then the corresponding outgoing links should be updated in accordance with the domain model content, and so forth. If this synchronized element is adorned with a CanonicalStyle, then it should be possible to switch on/off the synchronization of outgoing links with the domain model by calling CanonicalStyle.setCanonical(). If synchronization is switched on, all the outgoing links should be immediately synchronized with the model.

(*) Illustration:

1. initial diagram diagram structure:

node TopNode {
   node SubNode {
   }
   node SubNodeSibling {
   }
}

2. final diagram structure:

node TopNode {
   node SubNode {
      node LinkSource {
         link MyLink {
            destination LinkTarget;
         }
      }
   }
   node SubNodeSibling {
      node LinkTarget {
      }
   }
}

Diagram updater should correctly process this situation and update diagram from state 1. to state 2. MyLink is a link connecting LinkSource with LinkTarget. Source and Target nodes of the link have same "grandfather". (Source and Target of the link are "cousins" :-) )

Non-Synchronized diagrams

This type of the diagram will be generated if GenDiagram.synchronized == false in .gmfgen model. No synchronization code should be generated for elements of this diagram. Only selected by user subset of non-synchronized elements should be represented on this diagram. Any non-synchronized element created on this diagram from the toolbar should be immediately visualized on diagram. In addition it should be possible to:

- invoke “Import child elements” popup menu action on each non-synchronized element (diagram node or diagram itself). This action will show the dialog with all the child diagram elements recognized from the model element associated with this non-synchronized element, but invisible on diagram currently. It should be possible to select any number of diagram elements from this dialog and add corresponding non-synchronized elements to this diagram. Ideal solution is to show tree of the direct child elements and their children. This tree should be equipped with checkboxes allowing to add the element with all it’s children or selected subset of child elements.

- invoke “Import outgoing link” popup menu action on each non-synchronized element. This action should show dialog listing all the links recognized from domain model, outgoing from this non-synchronized element and invisible on current diagram. It should be possible to add selected links to the diagram. Note: non-synchronized element could be a link.

- Delete any non-synchronized element from view should remove this element from the diagram and keep domain model unchanged.

- Delete from model action should remove both non-synchronized element and corresponding element/reference (for reference-only links) from the domain model.

Non-Synchronized elements

Each non-synchronized element should still listen for the domain model changes to support the following cases:

- domain model was changed externally or by user code in a way that existing diagram element should be removed (domain element removed) – corresponding diagram element should be removed on next diagram opening or corresponding EMF notification.

- if the same domain model element can be represented on diagram as a different diagram elements (node-1 or node-2) based on domain model properties and the domain model was changed externally or by user code in a way that the existing domain model element should change the diagram representation (not be recognized as node-1 anymore, but should be recognized as node-2) – the existing node-1 should be replaced by node-2 on next diagram opening or by receiving EMF notification. Node-2 should get the size/position of node-1 and all the rest of applicable Styles.

Non-Synchronized links

Each link on non-synchronized diagram should be updated in case of following changes in domain model:

- if same domain model element (or even reference!) can be represented on diagram as a different link (link-1 or link-2) based on domain model properties and domain model was changed externally or by user code in a way that existing link-1 should be replaced by link-2 – corresponding diagram update should be performed on next diagram opening or by receiving EMF notification. Newly created link-2 should get all the bending/connection points of link-1 and all the rest of its applicable Styles.

- domain model was changed externally or by user code in a way that an existing link should be removed from diagram– corresponding link should be removed on next diagram opening/receiving EMF notification.

Pure-design elements

Not synchronisation or updating code should be generated for this type of the elements. In particular: CanonicalEditPolicy should neither be generated nor installed for the corresponding EditPart, CanonicalStyle should not be created by corresponding ViewFactory.

HREFs

Bugzilla entries

#150257

#150408

#133505

#148275

#180786

#184130

Newsgroup threads

http://dev.eclipse.org/newslists/news.eclipse.modeling.gmf/msg05117.html

Copyright © Eclipse Foundation, Inc. All Rights Reserved.