|
|
| (109 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| − | {{EMF_Compare}}
| + | This page has moved to http://www.eclipse.org/emf/compare/documentation/latest/developer/developer-guide.html |
| − | | + | |
| − | = Architecture =
| + | |
| − | | + | |
| − | == Comparison Process ==
| + | |
| − | | + | |
| − | [[Image:EMF Compare Process Full.png|thumb|center|800px]]
| + | |
| − | | + | |
| − | The comparison process of EMF Compare is explained in depth on the [[EMF_Compare#Overview|Overview]].
| + | |
| − | | + | |
| − | ==Project Architecture==
| + | |
| − | | + | |
| − | [[Image:EMF Compare 2 Architecture.png|center]]
| + | |
| − | | + | |
| − | EMF Compare is built on top of the Eclipse platform. We depend on the Eclipse Modeling Framework (EMF), the Eclipse Compare framework and, finally, Eclipse Team, the framework upon which the repository providers (EGit, CVS, Subversive...) are built.
| + | |
| − | | + | |
| − | The EMF Compare extensions target specific extensions of the modeling framework : UML, the Graphical Modeling Framework (and its own extensions, papyrus, ecoretools, ...).
| + | |
| − | | + | |
| − | Whilst we are built atop bricks that are tightly coupled with the eclipse platform, it should be noted that the core of EMF Compare can be run in a standalone application with no runtime dependencies towards Eclipse; as can EMF itself.
| + | |
| − | | + | |
| − | ==Default behavior and extensibility==
| + | |
| − | | + | |
| − | All main components of EMF Compare have been designed for extensibility. Some are only extensible when comparing models through your own actions, some can be customized globally for a given kind of model or metamodel... We'll outline the customization options of all 6 comparison phases in this section. (Any dead link? Report them on the [http://www.eclipse.org/forums/index.php/f/164/ forum]!)
| + | |
| − | | + | |
| − | ===Model Resolving===
| + | |
| − | | + | |
| − | ===Match===
| + | |
| − | | + | |
| − | Before we can compute difference between two versions of a same Object, we must determine which are actually the "same" Object. For example, let's consider that my first model contains a Package P1 which itself contains a class C1; and that my second model contains a package P1 which contains a class C1. It may seem obvious for a human reader that "P1" and "C1" are the same object in both models. However, since their features might have changed in-between the two versions (for example, the "C1" might now be abstract, or it could have been converted to an Interface), this "equality" is not that obvious for a computer.
| + | |
| − | | + | |
| − | The goal of the "Match" phase is to discover which of the objects from model 2 match with which objects of model 1. In other words, this is when we'll say that two objects are one and the same, and that any difference between the two sides of this couple is actually a difference that should be reported as such to the user.
| + | |
| − | | + | |
| − | By default, EMF Compare matches your elements through their identifier if they have one, and uses a distance mechanism for all elements that have none.
| + | |
| − | | + | |
| − | EMF Compare "finds" the identifier of given object through a basic function that can be found in [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/eobject/IdentifierEObjectMatcher.java#n268 IdentifierEObjectMatcher.DefaultIDFunction]. In short, if the object is a proxy, its identifier is its URI fragment. Otherwise its functional ID (in ecore, an attribute that serves as an identifier) takes precedence over its XMI ID (the identifier it was given in the XMI file). If the object is not a proxy and has neither functional nor XMI identifier, then the default behavior will simply pass that object over to be matched through distance algorithms.
| + | |
| − | | + | |
| − | = Using the Compare Services =
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | == Introduction ==
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | All the following examples will use a simple (some would say "stupid") domain model used to keep personal information, here
| + | |
| − | | + | |
| − | contact lists.
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | Here is the diagram:
| + | |
| − | | + | |
| − | [[Image:AddressBookMM.png]]<br>
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | The whole comparison process is divided in two phases :
| + | |
| − | | + | |
| − |
| + | |
| − | | + | |
| − | # matching both versions of the elements and providing a match model.
| + | |
| − | #computing the diff (delta) model from this match.
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | When comparing (using the user interface) two models conformed to the AddressBook metamodel you'll get:
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | [[Image:AddressBookComparaison1.png]]
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | This is an emfdiff model displayed using the emf compare editor. Both match and delta information are kept in this model, let's have
| + | |
| − | | + | |
| − | a further look on the match part:
| + | |
| − | | + | |
| − | <br> [[Image:AddressBookMatch.png]]
| + | |
| − | | + | |
| − | The match model weave elements from both versions of the model.
| + | |
| − | | + | |
| − | <br> [[Image:AddressBookMatchDetail.png]]
| + | |
| − | | + | |
| − | <br> From this match model EMF compare is able to compute the delta (diff):
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | [[Image:AddressBookDiffDetail.png]]
| + | |
| − | | + | |
| − | <br> <br>
| + | |
| − | | + | |
| − | == Getting the differences of two models ==
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | Getting these differences using some code is easy, here is the snippet::
| + | |
| − | | + | |
| − | <br>
| + | |
| − | <pre>private DiffModel getDiff(AddressBook v1, AddressBook v2) throws Exception {
| + | |
| − | Map options = new HashMap();
| + | |
| − | MatchModel match = MatchService.doContentMatch(v1, v2, options);
| + | |
| − | // ...
| + | |
| − | </pre>
| + | |
| − | And you'll get the Match model which you can browse like any other EMF model.
| + | |
| − | | + | |
| − | Let's now produce the diff from this match information::
| + | |
| − | | + | |
| − | <br>
| + | |
| − | <pre> DiffModel diff = DiffService.doDiff(match);
| + | |
| − | return diff;
| + | |
| − | }</pre>
| + | |
| − |
| + | |
| − | | + | |
| − | Both Diff and Match services leverage the Eclipse architecture to find the best match/diff engine from the file extension.
| + | |
| − | | + | |
| − | But EMF Compare can be used to get the differences of two models within Eclipse or out of Eclipse (standalone mode) and using it in standalone mode you'll loose the ability of "auto-picking" the right match/diff engine considering the file extension : you'll have to call the engines yourself. Here the generic one::
| + | |
| − | | + | |
| − | <br>
| + | |
| − | <pre>private DiffModel getDiff(AddressBook v1, AddressBook v2) throws Exception {
| + | |
| − | Map options = new HashMap();
| + | |
| − | MatchModel match = new GenericMatchEngine().contentMatch(v1,v2,options);
| + | |
| − | DiffModel diff = new GenericDiffEngine().doDiff(match);
| + | |
| − | return diff;
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | The generic match engine can be parameterized thanks to some options available in the MatchOptions interface:
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | {| width="800" border="1" align="center" cellpadding="1" cellspacing="1"
| + | |
| − | |-
| + | |
| − | | Name
| + | |
| − | | Description
| + | |
| − | | Type
| + | |
| − | |-
| + | |
| − | | OPTION_DISTINCT_METAMODELS
| + | |
| − | | If set to true, the engine will be able to compare two models from different metamodel and find similarities.
| + | |
| − | | Boolean
| + | |
| − | |-
| + | |
| − | | OPTION_IGNORE_ID
| + | |
| − | | If set to true, the engine will ignore the Ecore ID's and will consider the elements data to match them.
| + | |
| − | | Boolean
| + | |
| − | |-
| + | |
| − | | OPTION_IGNORE_XMI_ID
| + | |
| − | | If set to true, the engine will ignore the XMI ID's and will consider the elements data to match them.
| + | |
| − | | Boolean
| + | |
| − | |-
| + | |
| − | | OPTION_SEARCH_WINDOW
| + | |
| − | | The search window is the number of elements the engine will consider at the same time, the bigger it is, more precise is the result, but slower is the process.
| + | |
| − | | Integer
| + | |
| − | |-
| + | |
| − | | OPTION_PROGRESS_MONITOR
| + | |
| − | | If set with an IProgressMonitor instance, this one will| IProgressMonitor be used to monitor the match process.
| + | |
| − | | IProgressMonitor
| + | |
| − | |}
| + | |
| − | | + | |
| − |
| + | |
| − | <blockquote> please note that all these calls can be done with 3 models, left, right and the ancestor one. Then you'll be able to detect conflicts. <br></blockquote>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | == Merging the differences ==
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | Once you get the differences you can merge them. You can merge every detected delta from the diff model using the merge service::
| + | |
| − | | + | |
| − | <br>
| + | |
| − | <pre>AddModelElement add = DiffHelper.isAdded(alice, changes);
| + | |
| − | MergeService.merge(add, false);
| + | |
| − | </pre>
| + | |
| − | Here is a quick view of all the diff elements:
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | !images/DiffMM.jpg!
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | == Using EMF Compare in standalone mode ==
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | You can setup your environment to use EMF Compare in standalone mode. The will looks like this ::
| + | |
| − | | + | |
| − | <br>
| + | |
| − | <pre>/**
| + | |
| − | * This application will try and launch an headless model comparison.
| + | |
| − | *
| + | |
| − | * @author Cedric Brun <a href="mailto:cedric.brun@obeo.fr">cedric.brun@obeo.fr</a>
| + | |
| − | */
| + | |
| − | public final class ExampleLauncher {
| + | |
| − | /**
| + | |
| − | * This class doesn't need to be instantiated.
| + | |
| − | */
| + | |
| − | private ExampleLauncher() {
| + | |
| − | // prevents instantiation
| + | |
| − | }
| + | |
| − |
| + | |
| − | /**
| + | |
| − | * Launcher of this application.
| + | |
| − | *
| + | |
| − | * @param args
| + | |
| − | * Arguments of the launch.
| + | |
| − | */
| + | |
| − | public static void main(String[] args) {
| + | |
| − | if (args.length == 2 && new File(args[0]).canRead() && new File(args[1]).canRead()) {
| + | |
| − | // Creates the resourceSet where we'll load the models
| + | |
| − | final ResourceSet resourceSet = new ResourceSetImpl();
| + | |
| − | // Register additionnal packages here. For UML2 for instance :
| + | |
| − | // Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap().put(UMLResource.FILE_EXTENSION,
| + | |
| − | // UMLResource.Factory.INSTANCE);
| + | |
| − | // resourceSet.getPackageRegistry().put(UMLPackage.eNS_URI, UMLPackage.eINSTANCE);
| + | |
| − |
| + | |
| − | try {
| + | |
| − | System.out.println("Loading resources.\n"); //$NON-NLS-1$
| + | |
| − | // Loads the two models passed as arguments
| + | |
| − | final EObject model1 = ModelUtils.load(new File(args[0]), resourceSet);
| + | |
| − | final EObject model2 = ModelUtils.load(new File(args[1]), resourceSet);
| + | |
| − |
| + | |
| − | // Creates the match then the diff model for those two models
| + | |
| − | System.out.println("Matching models.\n"); //$NON-NLS-1$
| + | |
| − | final MatchModel match = MatchService.doMatch(model1, model2, Collections
| + | |
| − | .<String, Object> emptyMap());
| + | |
| − | System.out.println("Differencing models.\n"); //$NON-NLS-1$
| + | |
| − | final DiffModel diff = DiffService.doDiff(match, false);
| + | |
| − |
| + | |
| − | System.out.println("Merging difference to args[1].\n"); //$NON-NLS-1$
| + | |
| − | final List<DiffElement> differences = new ArrayList<DiffElement>(diff.getOwnedElements());
| + | |
| − | // This will merge all references to the right model (second argument).
| + | |
| − | MergeService.merge(differences, true);
| + | |
| − |
| + | |
| − | // Prints the results
| + | |
| − | try {
| + | |
| − | System.out.println("MatchModel :\n"); //$NON-NLS-1$
| + | |
| − | System.out.println(ModelUtils.serialize(match));
| + | |
| − | System.out.println("DiffModel :\n"); //$NON-NLS-1$
| + | |
| − | System.out.println(ModelUtils.serialize(diff));
| + | |
| − | } catch (IOException e) {
| + | |
| − | e.printStackTrace();
| + | |
| − | }
| + | |
| − |
| + | |
| − | // Serializes the result as "result.emfdiff" in the directory this class has been called from.
| + | |
| − | System.out.println("saving emfdiff as \"result.emfdiff\""); //$NON-NLS-1$
| + | |
| − | final ModelInputSnapshot snapshot = DiffFactory.eINSTANCE.createModelInputSnapshot();
| + | |
| − | snapshot.setDate(Calendar.getInstance().getTime());
| + | |
| − | snapshot.setMatch(match);
| + | |
| − | snapshot.setDiff(diff);
| + | |
| − | ModelUtils.save(snapshot, "result.emfdiff"); //$NON-NLS-1$
| + | |
| − | } catch (IOException e) {
| + | |
| − | // shouldn't be thrown
| + | |
| − | e.printStackTrace();
| + | |
| − | } catch (InterruptedException e) {
| + | |
| − | e.printStackTrace();
| + | |
| − | }
| + | |
| − | } else {
| + | |
| − | System.out.println("usage : ExampleLauncher <Model1> <Model2>"); //$NON-NLS-1$
| + | |
| − | }
| + | |
| − | }
| + | |
| − | }</pre><div><br></div>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | = Tutorials =
| + | |
| − | | + | |
| − | *[[Setting up a development environment for EMF Compare|Setting up a development environment for EMF Compare]]
| + | |
| − | *[[Comparing XML files with EMF Compare|Comparing XML files with EMF Compare]]
| + | |
| − | *[http://model-driven-blogging.blogspot.com/2011/06/comparing-pomxml-files-while-waiting.html Comparing pom.xml files with EMF Compare]
| + | |
| − | | + | |
| − | You'll find a few more tutorials on the Eclipse Online Help once you installed EMF Compare
| + | |
| − | | + | |
| − | *Architecture
| + | |
| − | *Using the Compare Services
| + | |
| − | *Adapting the Comparison Process to your Ecore Model
| + | |
| − | *Adding new actions to the export menu
| + | |
| − | | + | |
| − | Additional UI APIs:
| + | |
| − | | + | |
| − | *[[EMF Compare/API Viewer FilteringGrouping|Create a viewer from the result of a model comparison (ComparisonSnapshot)]] to show:
| + | |
| − | **The structural differences
| + | |
| − | **The effect of filtering and grouping parameters
| + | |
| − | *[[EMF Compare/API GetVisibleDiffElements|Request the viewer to retrieve only the visible differences, according to the viewer filtering configuration]]
| + | |
| − | *[[EMF Compare/API LayerDifferences|Retrieve the compared graphical models (resource set), filled by the difference decorators]]
| + | |
| − | *[[EMF Compare/API OpenEditorWithSelection|Open an EMF Compare editor from two model versions (CompareEditorInput) and select the structural differences related to the model object identifiers in parameters]]
| + | |
| − | *[http://model-driven-blogging.blogspot.com/2011/10/model-transformation-preview.html Using EMF Compare to preview changes]
| + | |
| − | *[http://model-driven-blogging.blogspot.com/2010/06/forecasts-comparison-for-world.html Create an action to compare Objects from an editor]
| + | |
| − | *[http://model-driven-blogging.blogspot.com/2011/12/do-you-want-to-discard-this-editors.html Handling editor's reload conflicts using EMF Compare]
| + | |
| − | | + | |
| − | ''Feel free to add any tutorial or documentation on the wiki, we'll integrate them back in the online help.''
| + | |
| − | | + | |
| − | [[Category:EMF Compare]]
| + | |
