Jump to: navigation, search

Difference between revisions of "Graphical Modeling Framework/Migration"

 
Line 1: Line 1:
Metamodels change between major GMF releases and so user models should be transformed to conform to the new schema. When metamodel is changed so it is not compatible anymore we increment version number in package namespace uri of the metamodel. When model is being loaded this is used to trigger migration. There is also an action available from model file context menu to migrate the model.
+
===What is it all about===
  
===Extending Migration===
+
Like everything else in the world, GMF metamodels evolve as time goes. New GMF features born often require some place to be reflected within the metamodel so users were able to configure them. As long as there are just addings to the metamodel, older-based xmls are no problem to handle, setting just blank or default values to new elements. But there’s nothing perfect. In more complicated cases when metamodel have been restructured or truncated someway, older-based xml became invalid for the point of ordinary loader. Actually, we may simple ignore all foreign elements, but that is not what is going to make everybody happy, cause it loses data. Instead, we have provided a migration facility, which reorganizes the model accordingly new scheme on the fly, not corrupting settings that were made, and removing only those elements, that really are obsolete and useless for the metamodel. Fortunately, we could deal with it well, as we are operating definite gmfmap, gmfgen and gmftool metamodels and all the transformations happened to them during their lifetime are known. Otherwise, that task might happen to be too complicated, as there are still too many unclear issues around ecore2ecore and ecore2xml transformations, which are proposed in EMF to be used for model version transformations.
  
This section is for developers that introduce changes in GMF models and have to reflect these changes in migration.
+
===Using Migration===
  
Related classes:
+
Therefore, when you use an instance of gmf model it is being instantiated with the help of special migration resource, which controls all possible metamodel divergences, and always builds correct model in memory.
*''MigrationResource'' resource capable of loading older models and transforming them on the fly.
+
 
*''MigrationConfig'' configuration and handler that actually converts model
+
Since there were any transformations had to be made to correctly build your model from the resource given, you will see the red-cross error sign, saying that problems have been encountered, and the message found under the details list with a warning of an old GMF version discovered and prompting you to migrate.
 +
 
 +
[[image: warning.png]]
 +
 
 +
However, your model instantiated should be completely usable, migrated, and conforming actual metamodel state, and you can browse it from the Selection tab of the GMF model editor. Despite that, if you will make no changes and close that editor, none of the migration changes going to be applied. Your resource will be left unchanged, thus compatible with the old metamodel you have used. Therefore, as you open it another time, same error will appear.
 +
 
 +
Finally, we have come to the idea of Migrate action. It is the one you were warned of in the resource error details message. Migrate action is available with your model file context menu (it is called ''Migrate to GMF 2.0''). As we have mentioned earlier, model transformation is provided by always building correct model during xml load on the fly anyway, so the only thing this action is capable of is just saving that instantiated model. You will be offered to chose a new name for migrated result, to still be able roll back using old gmf versions with source version of file.  
 +
 
 +
[[image: dialog.png]]
 +
 
 +
<font color="darkblue">'''Note'''</font>, that same effect of migration you get saving any changes to the instantiated model from Selection tab of the editor that has opened with migration warning!
 +
 
 +
===Implementation Details===
 +
 
 +
In GMF2.0 M7 and right afterwards once more migration mechanism was completely rewritten. This text describes the newest one, which may differ from yours in current gmf version.
 +
 
 +
Since [https://bugs.eclipse.org/bugs/show_bug.cgi?id=187811 cr 187811] (and [https://bugs.eclipse.org/bugs/show_bug.cgi?id=188768 cr 188768] right afterwards) migration works very straightforward and easy to use. GMF models are opened with resource, that is customized with special migration ''XMLHelper'', called ''MigrationHelper'', which, in turn, delegates special behavior handling to its ''MigrationDelegate''. ''MigrationDelegateImpl'' is a class which can deal with features renaming and deletion, types narrowing and renaming. You can find all the common code for migration within '''org.eclipse.gmf.internal.common.migrate''' package. GMF Gen and GMF Map models just provide specific delegate to register and handle each its own known problems. For further details just refer to ''org.eclipse.gmf.internal.codegen.util.MigrationDelegate.java'' and ''org.eclipse.gmf.internal.map.util.MigrationDelegate.java''.
 +
 
 +
 
 +
===List of metamodel changes happened===
 +
 
 +
For migration support of every metamodel change we certainly have own Bugzilla (for example, like this one [https://bugs.eclipse.org/bugs/show_bug.cgi?id=123240 cr 123240]), and most of those are collected in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=187811 cr 187811].
 +
 
 +
However, it would be very handy to have some place to gather them altogether with an ability of modifying and extending such list. So let it be this wiki page, for instance.
 +
 
 +
====GMF Map Model====
 +
 
 +
=====Narrowed abstract types=====
 +
FeatureSeqInitializer
 +
*initializers -> FeatureValueSpec [https://bugs.eclipse.org/bugs/show_bug.cgi?id=138440 cr 138440]
 +
 
 +
MappingEntry
 +
*labelMappings -> FeatureLabelMapping [https://bugs.eclipse.org/bugs/show_bug.cgi?id=161380 cr 161380]
 +
 
 +
=====Complex structure changes=====
 +
FeatureLabelMapping with no features as LabelMapping [https://bugs.eclipse.org/bugs/show_bug.cgi?id=161380 cr 161380]
 +
 
 +
====GMF Gen Model====
 +
 
 +
=====Removed attributes=====
 +
EditorCandies
 +
*diagramFileCreatorClassName
 +
*preferenceInitializerClassName
 +
 
 +
ProviderClassNames
 +
*abstractParserClassName
 +
*structuralFeatureParserClassName
 +
*structuralFeaturesParserClassName
 +
*paletteProviderClassName
 +
*paletteProviderPriority
 +
*propertyProviderClassName
 +
*propertyProviderPriority
 +
 
 +
EditPartCandies
 +
*referenceConnectionEditPolicyClassName
 +
*externalNodeLabelHostLayoutEditPolicyClassName
 +
 
 +
TypeLinkModelFacet
 +
*createCommandClassName
 +
 
 +
=====Renamed attributes=====
 +
FeatureLabelModelFacet
 +
*metaFeature -> metaFeatures
 +
 
 +
=====Narrowed abstract types=====
 +
GenFeatureSeqInitializer
 +
*initializers -> GenFeatureValueSpec [https://bugs.eclipse.org/bugs/show_bug.cgi?id=138440 cr 138440]
 +
 
 +
=====Renamed types=====
 +
*CompositeFeatureLabelModelFacet -> FeatureLabelModelFacet
 +
 
 +
=====Complex structure changes=====
 +
 
 +
GenAuditContainer and GenAuditRule structures [https://bugs.eclipse.org/bugs/show_bug.cgi?id=185372 cr 185372]
 +
 
 +
requiredPluginIDs moved to GenPlugin [https://bugs.eclipse.org/bugs/show_bug.cgi?id=123240 cr 123240]

Revision as of 12:33, 24 May 2007

What is it all about

Like everything else in the world, GMF metamodels evolve as time goes. New GMF features born often require some place to be reflected within the metamodel so users were able to configure them. As long as there are just addings to the metamodel, older-based xmls are no problem to handle, setting just blank or default values to new elements. But there’s nothing perfect. In more complicated cases when metamodel have been restructured or truncated someway, older-based xml became invalid for the point of ordinary loader. Actually, we may simple ignore all foreign elements, but that is not what is going to make everybody happy, cause it loses data. Instead, we have provided a migration facility, which reorganizes the model accordingly new scheme on the fly, not corrupting settings that were made, and removing only those elements, that really are obsolete and useless for the metamodel. Fortunately, we could deal with it well, as we are operating definite gmfmap, gmfgen and gmftool metamodels and all the transformations happened to them during their lifetime are known. Otherwise, that task might happen to be too complicated, as there are still too many unclear issues around ecore2ecore and ecore2xml transformations, which are proposed in EMF to be used for model version transformations.

Using Migration

Therefore, when you use an instance of gmf model it is being instantiated with the help of special migration resource, which controls all possible metamodel divergences, and always builds correct model in memory.

Since there were any transformations had to be made to correctly build your model from the resource given, you will see the red-cross error sign, saying that problems have been encountered, and the message found under the details list with a warning of an old GMF version discovered and prompting you to migrate.

Warning.png

However, your model instantiated should be completely usable, migrated, and conforming actual metamodel state, and you can browse it from the Selection tab of the GMF model editor. Despite that, if you will make no changes and close that editor, none of the migration changes going to be applied. Your resource will be left unchanged, thus compatible with the old metamodel you have used. Therefore, as you open it another time, same error will appear.

Finally, we have come to the idea of Migrate action. It is the one you were warned of in the resource error details message. Migrate action is available with your model file context menu (it is called Migrate to GMF 2.0). As we have mentioned earlier, model transformation is provided by always building correct model during xml load on the fly anyway, so the only thing this action is capable of is just saving that instantiated model. You will be offered to chose a new name for migrated result, to still be able roll back using old gmf versions with source version of file.

Dialog.png

Note, that same effect of migration you get saving any changes to the instantiated model from Selection tab of the editor that has opened with migration warning!

Implementation Details

In GMF2.0 M7 and right afterwards once more migration mechanism was completely rewritten. This text describes the newest one, which may differ from yours in current gmf version.

Since cr 187811 (and cr 188768 right afterwards) migration works very straightforward and easy to use. GMF models are opened with resource, that is customized with special migration XMLHelper, called MigrationHelper, which, in turn, delegates special behavior handling to its MigrationDelegate. MigrationDelegateImpl is a class which can deal with features renaming and deletion, types narrowing and renaming. You can find all the common code for migration within org.eclipse.gmf.internal.common.migrate package. GMF Gen and GMF Map models just provide specific delegate to register and handle each its own known problems. For further details just refer to org.eclipse.gmf.internal.codegen.util.MigrationDelegate.java and org.eclipse.gmf.internal.map.util.MigrationDelegate.java.


List of metamodel changes happened

For migration support of every metamodel change we certainly have own Bugzilla (for example, like this one cr 123240), and most of those are collected in cr 187811.

However, it would be very handy to have some place to gather them altogether with an ability of modifying and extending such list. So let it be this wiki page, for instance.

GMF Map Model

Narrowed abstract types

FeatureSeqInitializer

MappingEntry

  • labelMappings -> FeatureLabelMapping cr 161380
Complex structure changes

FeatureLabelMapping with no features as LabelMapping cr 161380

GMF Gen Model

Removed attributes

EditorCandies

  • diagramFileCreatorClassName
  • preferenceInitializerClassName

ProviderClassNames

  • abstractParserClassName
  • structuralFeatureParserClassName
  • structuralFeaturesParserClassName
  • paletteProviderClassName
  • paletteProviderPriority
  • propertyProviderClassName
  • propertyProviderPriority

EditPartCandies

  • referenceConnectionEditPolicyClassName
  • externalNodeLabelHostLayoutEditPolicyClassName

TypeLinkModelFacet

  • createCommandClassName
Renamed attributes

FeatureLabelModelFacet

  • metaFeature -> metaFeatures
Narrowed abstract types

GenFeatureSeqInitializer

  • initializers -> GenFeatureValueSpec cr 138440
Renamed types
  • CompositeFeatureLabelModelFacet -> FeatureLabelModelFacet
Complex structure changes

GenAuditContainer and GenAuditRule structures cr 185372

requiredPluginIDs moved to GenPlugin cr 123240