Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EMF DiffMerge/Model Patch"
(→Introduction) |
|||
| Line 4: | Line 4: | ||
[[File:EMF_DiffMerge_Patch_UseCases.png|600px]] | [[File:EMF_DiffMerge_Patch_UseCases.png|600px]] | ||
| + | |||
| + | === Creating a patch from a difference === | ||
| + | |||
| + | The user has two versions of the same model (either because he modified the model or because the model is version controlled and a new version is available). He uses a tool (such as EMF Diff/Merge) to compare the two versions and to derive the difference between them. Once the difference is available, he want to store the difference in the form of a patch. | ||
| + | |||
| + | === Applying a patch on a model === | ||
| + | |||
| + | The user has a model and wants to apply a stored patch on it. In order to ensure proper configuration of the model, it is expected that the user starts from a state where the model and all its dependencies are already loaded into memory. Then the user also selects the patch to be applied. In some cases the user wants to examine the effects of the application before it is committed to the model, so the patch application process should include a phase where the original and the modified models are compared with a tool (such as EMF Diff/Merge). Additionally, if the patch contains changes that cannot be applied, the user should get feedback on the rejected part of the patch. | ||
| + | |||
| + | === Reversing a patch on a model === | ||
| + | |||
| + | Instead of applying a patch, the user wants to revert the changes in a patch. The reversing is done exactly like applying, but all changes are inverted. | ||
| + | |||
| + | === Examining a patch independently from a model === | ||
| + | |||
| + | The user may want to open a patch and examine its contents without loading an instance model that could be used to apply the patch. The user should be able to see every information stored by the patch, including the list of entries and their details. Additionally, it would be possible to enhance the examination with the following: | ||
| + | * Use an object locator to resolve identifiers of metamodel elements (types, features) | ||
| + | * Load an instance model and use an object locator to resolve identifiers of model elements (contexts, target) | ||
| + | |||
| + | === Selecting a partial patch === | ||
| + | |||
| + | The user has a model and a patch, but does not want to apply all the changes in the patch. Instead, the user would like to select a part of the patch that can be stored or applied as a patch itself. The selection may be done by explicitly removing some entries from the patch or by providing one or more filters that match some entries and not others. Filtering can be done on any detail of an entry, such as entry type, change type, context object or other property. Furthermore complex filters may be constructed from simple filters through boolean operations (and, or, not), while specific filters could be provided by the user that evaluates entries using any kind of computation. | ||
== Model patch workflows == | == Model patch workflows == | ||
Revision as of 12:41, 14 March 2017
Introduction
The modelpatch tool can create modelpatches based on the difference of two models, and it can later apply these patches on models.
Creating a patch from a difference
The user has two versions of the same model (either because he modified the model or because the model is version controlled and a new version is available). He uses a tool (such as EMF Diff/Merge) to compare the two versions and to derive the difference between them. Once the difference is available, he want to store the difference in the form of a patch.
Applying a patch on a model
The user has a model and wants to apply a stored patch on it. In order to ensure proper configuration of the model, it is expected that the user starts from a state where the model and all its dependencies are already loaded into memory. Then the user also selects the patch to be applied. In some cases the user wants to examine the effects of the application before it is committed to the model, so the patch application process should include a phase where the original and the modified models are compared with a tool (such as EMF Diff/Merge). Additionally, if the patch contains changes that cannot be applied, the user should get feedback on the rejected part of the patch.
Reversing a patch on a model
Instead of applying a patch, the user wants to revert the changes in a patch. The reversing is done exactly like applying, but all changes are inverted.
Examining a patch independently from a model
The user may want to open a patch and examine its contents without loading an instance model that could be used to apply the patch. The user should be able to see every information stored by the patch, including the list of entries and their details. Additionally, it would be possible to enhance the examination with the following:
- Use an object locator to resolve identifiers of metamodel elements (types, features)
- Load an instance model and use an object locator to resolve identifiers of model elements (contexts, target)
Selecting a partial patch
The user has a model and a patch, but does not want to apply all the changes in the patch. Instead, the user would like to select a part of the patch that can be stored or applied as a patch itself. The selection may be done by explicitly removing some entries from the patch or by providing one or more filters that match some entries and not others. Filtering can be done on any detail of an entry, such as entry type, change type, context object or other property. Furthermore complex filters may be constructed from simple filters through boolean operations (and, or, not), while specific filters could be provided by the user that evaluates entries using any kind of computation.
Model patch workflows
Patch recording from difference
The recording based on two versions of a model which versions are compared with EMF Diff/Merge. One of the versions will be the reference model and the other will be the target model. We create patch which can use to "upgrade" the target model to the reference model.
The EMF Diff/Merge calculates differences between the reference and target. The Patch Recorder processes the output of EMF Diff/Merge. It converts differences calculated by EMF Diff/Merge to patch entries, and - if necessary - it creates extra entries to save old features of objects and set new which are not represented in differences.
Patch application
There is two way for patch application:
- You can directly apply the patch (or its reverse).
- Patch will be applied over a copy of the model and you can explicitly select and merge changes through the compare view of EMF Diff/Merge.
Both ways support graceful degradation (report rejected entries). Patch modifications (filtering and reverse) are not parts of any of them, modifications are done on patch level, before application.
Direct patch application means that Patch Applier applies the patch directly over the selected model.
If you want patch application and comparison with EMF Diff/Merge the Patch Applier creates a deep copy from the selected model and applies sequentially all entries of the patch over this copy. The patched copy and the selected model are passed to EMF Diff/Merge which calculates differences for the changes. Necessary changes can be selected and merged explicitly through EMF Diff/Merge.
Model patch representation
The Patch Representation contains an ordered collection of model patch entries and metadata information, such as author and time stamp. Model patch entries represent elementary model changes. Every entry has a direction (ADD or REMOVE) and a context identifier which identifies the modifiable element. We use three type of entries: (1) element entries, (2) attribute entries and (3) reference entries. Element entries represent an object creation (ADD) or an object removal (REMOVE). An element entry also stores the type of the element (as String) in both cases. We store the type even in case of removal to ensure the reversibility of the entry (if reverse patch is applied, a new object should be created). The two other type of entries (attribute and reference) represent modification of feature values. Both of them store the identifier of the feature which is modified and have an optional index attribute which represents the position of the value if the feature value is a collection. While an attribute entry stores the data type value as a string, the reference entry stores the identifier of the referenced object.
Architecture
The following figure illustrates the modules of the model patch framework and their most important dependencies. The framework is divided into three parts: Patch Representation, Runtime API and Model Patch User Interface (UI). The Patch Representation ('patch') is completely standalone, without dependencies to Eclipse, EMF or EMF Diff/Merge. The Runtime API depends on EMF, EMF Diff/Merge and VIATRA runtime. The user interface extends the EMF Diff/Merge UI plug-in. There are persistence modules for storing patches in JSON and EMF model formats (the latter can be persisted to XMI).
Links
- Download (requires EMF Diff/Merge 0.7.0)
- Bugzilla: for reporting bugs
- Source repository: the Git repository of source files
- Gerrit access: the project on Eclipse Gerrit
- Build job: the location where the project is being built
- EMF Diff/Merge: the host project that also provides the technological foundations upon which the Co-Evolution technology is based