Difference between revisions of "Graphical Modeling Framework/Migration"

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.

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

• 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