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.

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.

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

With introduction of dynamic_package 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 org.eclipse.gmf.codegen/plugin.xml 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 org.eclipse.gmf.internal.codegen.util.GMFGenResource.X). Using EMF reflection, we just reuse and extend the idea of EcoreUtil.Copier to work with dynamic_packages available (see org.eclipse.gmf.internal.common.migrate.FilteringCopier).

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

• initializers -> FeatureValueSpec cr 138440

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