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 [[EMF_Compare/FAQ/1.3|dedicated page]].

=Users=

=Users=

Line 5:

Line 7:

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

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

−

'''A''' : EMF compare uses a content-type to know whether it should be used for comparison. This content-type will initially register itself against *.ecore and *.uml files. You may add your own extension using the <tt>Preferences view / Global / Content-types</tt> and adding your file extension in the "EMF Compare" content-type.

+

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

−

[[Image:EMFComparePreferences-content-type.png]]

+

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

+

+

[[Image:EMF Compare XMI Content Type.png]]

====How to force text comparison?====

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

'''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''' : You can force text comparison of those "locked" model files by adding their extension to the "text" content type in the same way as what is explained above.

+

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

+

+

[[Image:EMF Compare Text Comparison.png]]

====EMF Compare compatibility?====

====EMF Compare compatibility?====

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

'''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. We've also used EMF Compare successfully with both JDK 1.6 and JDK 1.7 early builds. As for Eclipse; as mentionned above, EMF Compare makes intensive use of JDK 1.5 features. These have been introduced with EMF 2.3 which isn't compatible with Eclipse < 3.3, EMF Compare is therefore only compatible with Eclipse 3.3 and higher.

+

'''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 [[EMF_Compare#Compatibility|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 [[EMF_Compare/User_Guide#Installing_EMF_Compare|Installation instruction]] present a set of update sites useable to install.

+

The [http://www.eclipse.org/emf/compare/downloads/ Download page] lists more specific update sites if you wish to try one of the latest integration builds.

=Developers=

=Developers=

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

==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 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''' : Using the "EMF Compare" content-type defined with EMF Compare, here is a sample from a plugin.xml:

+

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

'''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 [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.compare/examples/org.eclipse.emf.compare.examples.standalone/?root=Modeling_Project here]. See README file of this example in order to get it to run

==How can I use EMF Compare programmatically?==

==How can I use EMF Compare programmatically?==

−

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

+

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

−

'''A''' : The example project mentionned above ([[http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.compare/examples/org.eclipse.emf.compare.examples.standalone/?root=Modeling_Project 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.

+

'''A''' : Many samples of how to compare objects can be found within [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare.tests the unit tests of EMF Compare] (see also [[EMF_Compare/Contributor_Guide#Checking_out_the_code|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) :

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 have more information in the following scientific paper : http://www.upgrade-cepis.org/issues/2008/2/upg9-2Brun.pdf [Link is broken!]

+

List<Diff> differences = comparison.getDifferences();

+

for (Diff diff : differences) {

+

// handle the difference

+

}

+

}

+

</source>

−

We're open to suggestion to enhance this generic behavior but we are also

+

==Can EMF Compare be used standalone?==

−

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

+

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

−

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

+

'''A''': Yes, the core of EMF Compare is developed primarily for standalone, the integration with Eclipse being built on top of that. All of the classes and utilities located in the ''org.eclipse.emf.compare'' plugin are pure Java with no dependency towards Eclipse, and can thus safely be used within a Java application running outside of Eclipse.

−

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

+

The following is the minimal set of dependencies you will need for 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?

'''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().

+

'''A''' : The differencing process of EMF Compare is based on equality helpers. For data types, this depends upon the return value of these data types' ''equals(Object)'' method. It will thus fail to determine whether two objects match if their ''equals(Object)'' methods has not been overriden in the custom data type's instance class. Remember to also override ''hashCode()'' when overriding ''equals(Object)''. A Typical example of this is [https://bugs.eclipse.org/bugs/show_bug.cgi?id=226152 bug 226152].

+

+

Another way around this problem would be to contribute your own equality helper to EMF Compare so that it knows how to compare these kind of data types. That could be done through the EMFCompare builder :

'''Q''' : I need to call EMF Compare programmatically from within my own plugin, but I'd like to be able to show my users a comparison editor. Is there a way?

+

+

'''A''' : Since EMF Compare 2.1.0M4, there is. As the answer to this question is a little complex, it deserves [[EMF_Compare/How_To_Open_Compare_Dialog_With_Comparison|its own page]].

+

+

==Can I use custom identifiers for my objects?==

+

'''Q''' : I have my own custom elements, and I'd like to tell EMF Compare what to use to uniquely identify them. For example, their name.

+

+

'''A''' : EMF Compare internally uses a function in order to compute the identifier of an EObject. You can override this function with your own, or compose your own with it so that EMF Compare will use your function for your elements, and fall back to the default behavior for any other element it needs to match.

+

+

How to do this is outlined on the [[EMF_Compare/Developer_Guide#Match|Developer Guide]].

+

+

==Can I ignore differences on a specific reference, or ignore ordering differences?==

+

'''Q''' : I want to ignore all differences on a given structural feature, can I tell EMF Compare not to look at these features?<br/>

+

'''Q''' : EMF Compare detects many ''ordering'' differences on my models, but I do not care about them. Is there a way to ignore all ordering changes?

+

+

'''A''' : You can override the ''FeatureFilter'' to tell EMF Compare that some references should be ignored, there is an example doing just that in the [[EMF_Compare/Developer_Guide#Changing_the_FeatureFilter|Developer Guide]].

−

See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=226152 bug #226152] for an example of such problems.

+

[[Category:EMF Compare]][[Category:FAQ]]

Revision as of 09:30, 10 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:

Can EMF Compare be used standalone?

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

A: Yes, the core of EMF Compare is developed primarily for standalone, the integration with Eclipse being built on top of that. All of the classes and utilities located in the org.eclipse.emf.compare plugin are pure Java with no dependency towards Eclipse, and can thus safely be used within a Java application running outside of Eclipse.

The following is the minimal set of dependencies you will need for EMF Compare.

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 : The differencing process of EMF Compare is based on equality helpers. For data types, this depends upon the return value of these data types' equals(Object) method. It will thus fail to determine whether two objects match if their equals(Object) methods has not been overriden in the custom data type's instance class. Remember to also override hashCode() when overriding equals(Object). A Typical example of this is bug 226152.

Another way around this problem would be to contribute your own equality helper to EMF Compare so that it knows how to compare these kind of data types. That could be done through the EMFCompare builder :

Can I programmatically open a comparison editor or dialog?

Q : I need to call EMF Compare programmatically from within my own plugin, but I'd like to be able to show my users a comparison editor. Is there a way?

A : Since EMF Compare 2.1.0M4, there is. As the answer to this question is a little complex, it deserves its own page.

Can I use custom identifiers for my objects?

Q : I have my own custom elements, and I'd like to tell EMF Compare what to use to uniquely identify them. For example, their name.

A : EMF Compare internally uses a function in order to compute the identifier of an EObject. You can override this function with your own, or compose your own with it so that EMF Compare will use your function for your elements, and fall back to the default behavior for any other element it needs to match.

Can I ignore differences on a specific reference, or ignore ordering differences?

Q : I want to ignore all differences on a given structural feature, can I tell EMF Compare not to look at these features?Q : EMF Compare detects many ordering differences on my models, but I do not care about them. Is there a way to ignore all ordering changes?

A : You can override the FeatureFilter to tell EMF Compare that some references should be ignored, there is an example doing just that in the Developer Guide.