Jump to: navigation, search

Difference between revisions of "EMF Compare/How To Open Compare Dialog With Comparison"

(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
This is only valid for the 2.0 release stream.
+
This is only valid since release 2.1M4.  
  
In this page you will learn how to open a dialog displaying the result of a comparison.
+
In this page you will learn how to open a dialog displaying the result of a comparison.  
  
== Preparing the input ==
+
== Preparing the input ==
  
The first thing to do is to implement your own class of [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareEditorInput.html CompareEditorInput].
+
The first thing to do is to choose an EMF Compare sub-implementation of the class of [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareEditorInput.html CompareEditorInput].  
  
You must override two methods :
+
Two implementations are provided:  
  
* ''prepareInput(IProgressMonitor)'', that must return the Comparison object (result from the EMFCompare computation) adapted as an [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2Fstructuremergeviewer%2FIDiffElement.html IDiffElement]
+
*''ComparisonEditorInput'', that should be use when you want to display a pre-computed Comparison (the results of EMFCompare).
* ''createDiffViewer(Composite)'', that must return a new instance of EMFCompareStructureMergeViewer.
+
*''ComparisonScopeEditorInput'', that should be use when you want to open the compare editor or dialog and to let it perform the comparison.
  
Here is a sample implementation that you can reuse as is :
+
Both are available from the '''org.eclipse.emf.compare.ide.ui''' plug-in, in the package '''org.eclipse.emf.compare.ide.ui.internal.editor'''. This is still provisional API so we may break it any time.
  
<pre>
+
== Preparing the configuration ==
/**
+
* A custom implementation of the editor input.
+
  */
+
class EMFCompareEditorInput extends CompareEditorInput {
+
  
private final Comparison comparison;
+
When instantiating an EMF Compare specific implementation of CompareEditorInput, you have to give it at least three paramaters:
  
private final AdapterFactory adapterFactory;
+
*a [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareConfiguration.html CompareConfiguration]. This is a standard CompareConfiguration (no specific implementation needed) so you just instantiated it like this:
  
/**
+
<source lang="java">
* Constructor.
+
CompareConfiguration configuration = new CompareConfiguration();
*
+
</source>
* @param configuration
+
*            the compare configuration
+
* @param comparison
+
*            the comparison
+
*/
+
public CustomCompareEditorInput(CompareConfiguration configuration) {
+
super(configuration);
+
this.comparison = (Comparison)configuration.getProperty(EMFCompareConstants.COMPARE_RESULT);
+
this.adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);  
+
}
+
  
/**
+
*an EMFCompareEditingDomain. It is not an implementation of [http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/edit/domain/EditingDomain.html EditingDomain] from EMF. It shares similar concepts (it has a command stack, it can create some commands) but is much simpler. You can create it through the factory method:
* {@inheritDoc}
+
*
+
* @see org.eclipse.compare.CompareEditorInput#prepareInput(org.eclipse.core.runtime.IProgressMonitor)
+
*/
+
@Override
+
protected Object prepareInput(IProgressMonitor monitor) throws InvocationTargetException,
+
InterruptedException {
+
return adapterFactory.adapt(this.comparison, IDiffElement.class);
+
}
+
  
/**
+
<source lang="java">
* {@inheritDoc}
+
// ancestor may be null
*  
+
ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);
* @see org.eclipse.compare.CompareEditorInput#createDiffViewer(org.eclipse.swt.widgets.Composite)
+
</source>
*/
+
 
@Override
+
You can even give your own command(s) stack(s) if you need to know about executed merge commands.
public Viewer createDiffViewer(Composite parent) {
+
 
return new EMFCompareStructureMergeViewer(parent, getCompareConfiguration());
+
* An [http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/common/notify/AdapterFactory.html AdapterFactory] used by the framework to adapt EObjects to be nicely displayed. Most of the time, a [http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/edit/provider/ComposedAdapterFactory.html ComposedAdapterFactory] with the global registry is sufficient as created in the example below:
};
+
 
 +
<source lang="java">
 +
AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);
 +
</source>
 +
 
 +
Depending on the choosen sub-implementation of CompareEditorInput, you may need to provide additional parameters.
 +
 
 +
=== ComparisonEditorInput ===
 +
 
 +
You must provide a Comparison object, the result of the comparison computation of EMFCompare.
 +
 
 +
<source lang="java">
 +
EMFCompare comparator = EMFCompare.builder().build();
 +
Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor));
 +
</source>
 +
 
 +
=== ComparisonScopeEditorInput ===
 +
 
 +
You must provide the comparator (instance of EMFCompare) and the scope of the comparison.
 +
 
 +
<source lang="java">
 +
EMFCompare comparator = EMFCompare.builder().build();
 +
IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor);
 +
</source>
 +
 
 +
== Opening the compare UI  ==
 +
 
 +
Then, you can call the black magic method from Eclipse Compare framework. You have two choices. You may either open the compare UI wihtin a modal dialog or within an editor. Just call one of the two following methods:
 +
 
 +
* [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareUI.html&anchor=openCompareEditorOnPage(org.eclipse.compare.CompareEditorInput,%20org.eclipse.ui.IWorkbenchPage) CompareUI.openCompareEditorOnPage(CompareEditorInput, IWorkbenchPage)], to open an editor.
 +
*[http://help.eclipse.org/juno/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/compare/CompareUI.html#openCompareDialog(org.eclipse.compare.CompareEditorInput) CompareUI.openCompareDialog(CompareEditorInput)], to open a modal dialog.
 +
 
 +
== End-to-end examples ==
 +
 
 +
=== With pre-computed comparison ===
 +
 
 +
<source lang="java">
 +
public void compare(Notifier left, Notifier right, Notifier ancestor) {
 +
    EMFCompare comparator = EMFCompare.builder().build();
 +
    Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor));
 +
 
 +
    ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);
 +
    AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);
 +
    CompareEditorInput input = new ComparisonEditorInput(new CompareConfiguration(), comparison, editingDomain, adapterFactory);
 +
 
 +
    CompareUI.openCompareDialog(input); // or CompareUI.openCompareEditor(input);
 
}
 
}
</pre>
+
</source>
  
== Preparing the configuration ==
+
=== With a comparison scope ===
  
When instantiating an EMFCompareEditorInput, you have to give him a [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareConfiguration.html CompareConfiguration]. This is a standard CompareConfiguration (no specific implementation needed). But you need to fill two EMFCompare specific properties:
+
<source lang="java">
*EMFCompareConstants.COMPARE_RESULT, the comparison itself.
+
public void compare(Notifier left, Notifier right, Notifier ancestor) {
*EMFCompareConstants.EDITING_DOMAIN, an EMFCompareEditingDomain. It is not an implementation of [http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/edit/domain/EditingDomain.html EditingDomain] from EMF. It shares similar concepts (it has a command stack, it can create some commands) but is much more simpler.
+
    EMFCompare comparator = EMFCompare.builder().build();
 +
    IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor));
  
Here is a code sample on how to create a CompareConfiguration suitable for EMFCompareEditorInput. The left, right and ancestor variables are the notifiers (EObject, Resource or ResourceSet) that have been given to EMFCompare to compute the Comparison (stored in the comparison variable).  
+
    ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);
 +
    AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);
 +
    CompareEditorInput input = new ComparisonScopeEditorInput(new CompareConfiguration(),  
 +
        editingDomain, adapterFactory, comparator, scope);
 +
 
 +
    CompareUI.openCompareDialog(input); // or CompareUI.openCompareEditor(input);
 +
}
 +
</source>
  
<pre>
+
[[Category:EMF_Compare]]
final CompareConfiguration configuration = new CompareConfiguration();
+
configuration.setProperty(EMFCompareConstants.COMPARE_RESULT, comparison);
+
configuration.setProperty(EMFCompareConstants.EDITING_DOMAIN, new EMFCompareEditingDomain(comparison, left, right, ancestor));
+
</pre>
+

Revision as of 03:53, 17 December 2012

This is only valid since release 2.1M4.

In this page you will learn how to open a dialog displaying the result of a comparison.

Preparing the input

The first thing to do is to choose an EMF Compare sub-implementation of the class of CompareEditorInput.

Two implementations are provided:

  • ComparisonEditorInput, that should be use when you want to display a pre-computed Comparison (the results of EMFCompare).
  • ComparisonScopeEditorInput, that should be use when you want to open the compare editor or dialog and to let it perform the comparison.

Both are available from the org.eclipse.emf.compare.ide.ui plug-in, in the package org.eclipse.emf.compare.ide.ui.internal.editor. This is still provisional API so we may break it any time.

Preparing the configuration

When instantiating an EMF Compare specific implementation of CompareEditorInput, you have to give it at least three paramaters:

  • a CompareConfiguration. This is a standard CompareConfiguration (no specific implementation needed) so you just instantiated it like this:
CompareConfiguration configuration = new CompareConfiguration();
  • an EMFCompareEditingDomain. It is not an implementation of EditingDomain from EMF. It shares similar concepts (it has a command stack, it can create some commands) but is much simpler. You can create it through the factory method:
// ancestor may be null
ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);

You can even give your own command(s) stack(s) if you need to know about executed merge commands.

  • An AdapterFactory used by the framework to adapt EObjects to be nicely displayed. Most of the time, a ComposedAdapterFactory with the global registry is sufficient as created in the example below:
AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);

Depending on the choosen sub-implementation of CompareEditorInput, you may need to provide additional parameters.

ComparisonEditorInput

You must provide a Comparison object, the result of the comparison computation of EMFCompare.

EMFCompare comparator = EMFCompare.builder().build();
Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor));

ComparisonScopeEditorInput

You must provide the comparator (instance of EMFCompare) and the scope of the comparison.

EMFCompare comparator = EMFCompare.builder().build();
IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor);

Opening the compare UI

Then, you can call the black magic method from Eclipse Compare framework. You have two choices. You may either open the compare UI wihtin a modal dialog or within an editor. Just call one of the two following methods:

End-to-end examples

With pre-computed comparison

public void compare(Notifier left, Notifier right, Notifier ancestor) {
    EMFCompare comparator = EMFCompare.builder().build();
    Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor));
 
    ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);
    AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);
    CompareEditorInput input = new ComparisonEditorInput(new CompareConfiguration(), comparison, editingDomain, adapterFactory);
 
    CompareUI.openCompareDialog(input); // or CompareUI.openCompareEditor(input);
}

With a comparison scope

public void compare(Notifier left, Notifier right, Notifier ancestor) {
    EMFCompare comparator = EMFCompare.builder().build();
    IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor));
 
    ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);
    AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);
    CompareEditorInput input = new ComparisonScopeEditorInput(new CompareConfiguration(), 
        editingDomain, adapterFactory, comparator, scope);
 
    CompareUI.openCompareDialog(input); // or CompareUI.openCompareEditor(input);
}