View source for Graphical Modeling Framework/Migration

===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 are 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.

[[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 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''.

With introduction of <tt>dynamic_package</tt> extension point in EMF 2.4, which makes it possible to distribute/publish models without generated implementation code easily, model migration becomes straightforward and easy to use. To understand older user resources, we register our URIs of obsolete models with this point prior to making any complicated changes and changing URI. You can have a look at <tt>org.eclipse.gmf.codegen/plugin.xml</tt> for example. Having these .ecores registered, we can use ResourceFactories with special ResourceHandlers, that are able to read old models and convert them into latest version in memory (see <tt>org.eclipse.gmf.internal.codegen.util.GMFGenResource.X</tt>). Using EMF reflection, we just reuse and extend the idea of <tt>EcoreUtil.Copier</tt> to work with <tt>dynamic_package</tt>s available (see <tt>org.eclipse.gmf.internal.common.migrate.FilteringCopier</tt>).

===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]

[[Category: Modeling]]