General presentation

The Profile Migration Tool is mainly base on the difference between the old profile and the new profile. Base on this difference we can get a list of migration action we will apply in the model.

Migration

Quick overview

Globally to do the migration the program is in 4 step:

1. Get the treeNode: the treeNonde correspond to differences between the profile V1 and V2.
2. Initialize the atomicMigratorList: this is the list of IAtomiMigrators. To initialize this list we run into the treeNode and for each node we will test if it is corresponding to a IAtomicMigrator, to do this we use the MigratorFactory.
3. Reapply the profile: we reapply the profile using UML default behavior (many of automatic actions of migration are done by the reapplying the profile). See UML 2.5 Package#applyProfile(Profile).
4. Migrate the model: we run into the atomicMigratorList and for each IAtomicMigrator we call the migrationAction() method.

Get differences

To get differences between the profile V1 and the profile V2 we use EMF Compare. However the output (Comparison) of EMF Compare is not really understandable. This output is interpreted by the class org.eclipse.papyrus.profile.migration.internal.utils.DifferenceTreeBuilder(Comparison) the method buildMatchTree() get a TreeNode from the comparison. The treeNode is much understandable since this element represent differences in a tree form and remove every elements which are not changed. For example, here we are in the left the output of EMF Compare, where there is every element of the model even if there are matching. In the right you can see the TreeNode, there is here only modified elements.

List of actions

After getting the TreeNode corresponding to differences between the profile V1 and V2 we initialize the list of IAtomicMigrator.

To initialize the atomicMigratorList we will check for each node of the treeNode if there is a corresponding migrator. To do that we will ask the MigratorFactory by the method instantiateMigrator(TreeNode). This method check for each known migrator if the treeNode in parameter is valid for the migrator.

This way we get a list of IAtomicMigrator, this list represent every difference between model where the too; have an action to do.

Migration

To do the migration, we need the list of IAtomicMigrator. We run into it and for each IAtomicMigrator we call the migrationAction() method.

UI

There is a separate plug-in for the UI part of the tool: org.eclipse.papyrus.profile.migration.ui. This plug-in manage with preference and pop-up display during the migration.

Preference

The preference page control if pop-up are display or not during the migration. During the execution, we keep in memory files that the user select (as profile before modification), and the preference page allow the user to remove which are keep file in cache if he want.

Dialogs

How to add a migrator

1. Create the migrator class which shall implement the IAtomicMigrator and shall have a static method like isValid(TreeNode) this is the method that the migratorFactory will call to determine if the treeNode correspond to this migrator of not. This method should return true if the treeNode correspond to this migrator.
2. Add an entry in the MigratorFactory. When the MigratorFactory is modified, 3 file should be modified in the same time:
   • org.eclipse.papyrus.profile.migration.factory.IMigratorFactory
   • org.eclipse.papyrus.profile.migration.factory.MigratorFactory
   • org.eclipse.papyrus.profile.migration.internal.factory.MigratorFactory

To keep in mind when you are coding the migration action:

• Think to sub stereotype application (if it is necessary):
  • use StereotypeApplicationRegistry.getAllStereotypeApplicationDescriptors(Stereotype) and not getStereotypeApplicationDescriptors
  • use descriptor.getStereotype() and not directly the stereotype (because the saved stereotype could be the super stereotype)
• Think to update registry of StereotypeApplicationDescriptor (StereotypeApplicationRegistry.stereotypeApplicationList) ex:
  • if a stereotype application is remove: we should delete the descriptor to avoid that a migrator try to migrate a delete stereotype application
  • if the stereotype of a stereotype application is change: we should update the descriptor otherwise following migrators will try to access the old stereotype application

Connection to Papyrus

The Profile Migration Tool is connected to Papyrus by the extensionPoint: org.eclipse.papyrus.uml.tools.profileApplicationDelegates. This extension point replace the action of reapplying profile when Papyrus detect a difference of version between the applying profile and the other one.