Revision as of 09:45, 7 January 2013

This FAQ will be aimed at EMF Compare 2 and subsequent versions. Since this version largely differs from the previous 1.* stream, answers related to version 1 cannot apply in most case. For specific questions about the 1.* stream, please see the dedicated page.

Users

Which files should be compared via EMF Compare ?

Q : My model is compared as a text-file, how can EMF compare know the files it should handle ?

A : EMF Compare will be triggered for any files that is recognized as an EMF model. There is no specific content-type for EMF Compare; any content-type that has the ecore XMI type as its base will be recognized as a file which comparison should be done with EMF Compare.

You may add your own extension using the Preferences view / General / Content-types and adding your file extension in the "XMI" content-type.

How to force text comparison?

Q : uml, ecore and emfdiff models are "locked" as model files in the aforementioned "EMF Compare" content-type. I want to compare two uml files as text, is there a way to do so?

A : There is no way to force textual comparison of EMF files. You can, however, switch back to a plain text comparison through the drop-down menu that is diplayed between the two halves of the compare editor :

EMF Compare compatibility?

Q : Which Java/Eclipse versions can EMF Compare run on?

A : EMF Compare is built against JDK 1.5 and makes use of the features it introduced such as foreach and generics. It is therefore incompatible with a JDK < 1.5. EMF Compare can also be used with both JDK 1.6 and JDK 1.7.

We strive to keep the compatibility chart updated so that you can determine which version of EMF Compare can be used in conjunction with your Eclipse of choice.

Where can I find EMF Compare?

Q : Where can I download the latest version of EMF Compare?

A : The Installation instruction present a set of update sites useable to install. The Download page lists more specific update sites if you wish to try one of the latest integration builds.

Developers

How can I programmatically add my model file extension in EMF Compare so that it is called automatically ?

Q : How can I programatically add my model file extension to EMF Compare so that it is called automatically ?

A : You can do so using the exore XMI content-type, here is a sample from a plugin.xml:

<extension
    point="org.eclipse.core.contenttype.contentTypes">
  <file-association
      content-type="org.eclipse.emf.ecore.xmi"
      file-extensions="uml"
      file-names="*"/>
</extension>

How to use EMF Compare programmatically?

Q : How can I use EMF Compare programmatically, to compare either files or "in-memory" objects?

A : Many samples of how to compare objects can be found within the unit tests of EMF Compare (see also how to checkout the source code). Here is a sample that should cover the basic use case (the class with this method should have a dependency towards the org.eclipse.emf.compare plugin) :

public void compare(File model1, File model2) {
	URI uri1 = URI.createFileURI("path/to/first/model.xmi");
	URI uri2 = URI.createFileURI("path/to/second/model.xmi");
 
	Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl());
 
	ResourceSet resourceSet1 = new ResourceSetImpl();
	ResourceSet resourceSet2 = new ResourceSetImpl();
 
	resourceSet1.getResource(uri1, true);
	resourceSet2.getResource(uri2, true);
 
	IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2);
	Comparison comparison = EMFCompare.builder().build().compare(scope);
 
	List<Diff> differences = comparison.getDifferences();
	for (Diff diff : differences) {
		// handle the difference
	}
}

Q : Is EMF Compare able to compare "in-memory" objects, and can it be run without Eclipse ?

A: Yes, an example Java project doing just that is accessible on CVS here. See README file of this example in order to get it to run

How can I use EMF Compare programmatically?

Q : How can I use EMF Compare programmatically? Is there any example for such use cases?

A : The example project mentionned above ([org.eclipse.emf.compare.examples.standalone]) should prove useful as an example for this issue. The following code snippet allows for loading, matching, differencing, then merging two models.

// Loading models
EObject model1 = ModelUtils.load(model1, resourceSet);
EObject model2 = ModelUtils.load(model2, resourceSet);
 
// Matching model elements
MatchModel match = MatchService.doMatch(model1, model2, Collections.<String, Object> emptyMap());
// Computing differences
DiffModel diff = DiffService.doDiff(match, false);
// Merges all differences from model1 to model2
List<DiffElement> differences = new ArrayList<DiffElement>(diff.getOwnedElements());
MergeService.merge(differences, true);

What kind of "strategies" use EMF compare ?

Q : What kind of "strategies" use EMF compare ? On which research work is it based ?

A : The emf compare generic engine is based on several research work and on experimentations. The paper being the most "near" the emf compare behavior is probably "UMLDiff: An Algorithm for Object-OrientedDesign Differencing" by Zhenchang Xing and Eleni Stroulia. Other reseach work have been used and a lot of them use the same kind of general behavior: A comparison in 2 phases, the first being the matching phase and the second the differencing phase. The matching is done computing comparison metrics and getting an "overall" rank of matching for two nodes while browsing both versions of the model. These metrics may change considering the research work, here in the generic engine we use 4 metrics :

• type similarity : analysing the metamodel element
• name similarity : looking for an attribute which have chances to be the name and comparing it
• value similarity : analysing the whole attributes values
• relations similarity : using the relations the element has with others.

Using these 4 metrics the comparison engine provide good correctness (most especially comparing models from DSM/DSL's metamodels) and efficiency when comparing big models (~=100 000 elements).

Once the matching phase is done, the matching model is browsed by the differencing engine computing "added", "deleted" or updated elements from that. If you save a comparison as an emfdiff model you'll be able to browse the match and diff model and you'll get the similarity ranking for each couple of elements.

You can find more information in the article: Model Differences in the Eclipse Modelling Framework by Cédric Brun and Alfonso Pierantoniofo in the 2008 Issue 2 Cepis Upgrade Journal: http://www.cepis.org/upgrade/index.jsp?p=0&n=2148&a=3058

We're open to suggestion to enhance this generic behavior but we are also open to other methods : we want this component to be a testbed for other algorithms and comparison techniques, any Eclipse plugin may contribute its own matching and differencing engine for generic or specific purpose and it would be quite interesting to compare the results from different engines on different models.

These strategies will probably evolve in the next releases (see following question).

What evolution should we expect on the global EMF compare strategies ?

Q : What evolution should we expect on the global EMF compare strategies ?

A : We are trying to get better results with generic comparison algorithm through other methods coming from the research world. An initiative about model transformation/weaving and comparison is taking place in Europe an you may expect that the EMF compare implementation will evolve toward these works.

Model Transformation initiative

Custom data types are always marked as modified by EMF Compare

Q : A model based on a custom meta-model always shows elements of a custom data type as being changed. How can I have EMF Compare behave correctly?

A : EMF Compare's differencing process is based on the return value of equals() and will then fail to determine if two objects are equals if the equals() method hasn't been overriden in the custom data type's instance class. Remember to also override hashCode() when overriding equals().

See bug #226152 for an example of such problems.