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

From Eclipsepedia

Jump to: navigation, search
(Preparing the input)
(7 intermediate revisions by one 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 can be reused 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  ==
package org.eclipse.emf.compare.ide.ui.internal.util;
+
  
import static com.google.common.base.Preconditions.checkNotNull;
+
When instantiating an EMF Compare specific implementation of CompareEditorInput, you have to give it at least three paramaters:
  
import java.lang.reflect.InvocationTargetException;
+
*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:
  
import org.eclipse.compare.CompareConfiguration;
+
<source lang="java">
import org.eclipse.compare.CompareEditorInput;
+
CompareConfiguration configuration = new CompareConfiguration();
import org.eclipse.compare.structuremergeviewer.IDiffElement;
+
</source>
import org.eclipse.core.runtime.IProgressMonitor;
+
import org.eclipse.emf.common.notify.AdapterFactory;
+
import org.eclipse.emf.compare.Comparison;
+
import org.eclipse.emf.compare.ide.ui.internal.EMFCompareConstants;
+
import org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer;
+
import org.eclipse.jface.viewers.Viewer;
+
import org.eclipse.swt.widgets.Composite;
+
  
/**
+
*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:
* A custom implementation of the editor input.
+
*/
+
class EMFCompareEditorInput extends CompareEditorInput {
+
  
private final Comparison comparison;
+
<source lang="java">
 +
// ancestor may be null
 +
ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor);  
 +
</source>
  
private final AdapterFactory adapterFactory;
+
You can even give your own command(s) stack(s) if you need to know about executed merge commands.
  
/**
+
* 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:
* Constructor.
+
*
+
* @param configuration
+
*            the compare configuration
+
* @param adapterFactory
+
*            an adapter factory (can be new as simple as ComposedAdapterFactory(
+
ComposedAdapterFactory.Descriptor.Registry.INSTANCE)).
+
*/
+
public EMFCompareEditorInput(CompareConfiguration configuration, AdapterFactory adapterFactory) {
+
super(checkNotNull(configuration));
+
this.comparison = (Comparison)configuration.getProperty(EMFCompareConstants.COMPARE_RESULT);
+
this.adapterFactory = checkNotNull(adapterFactory);
+
}
+
  
/**
+
<source lang="java">
* {@inheritDoc}
+
AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);
*
+
</source>
* @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);
+
}
+
  
/**
+
Depending on the choosen sub-implementation of CompareEditorInput, you may need to provide additional parameters.
* {@inheritDoc}
+
*
+
* @see org.eclipse.compare.CompareEditorInput#createDiffViewer(org.eclipse.swt.widgets.Composite)
+
*/
+
@Override
+
public Viewer createDiffViewer(Composite parent) {
+
return new EMFCompareStructureMergeViewer(parent, getCompareConfiguration());
+
}
+
}
+
</pre>
+
  
== Preparing the configuration ==
+
=== ComparisonEditorInput ===
  
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:
+
You must provide a Comparison object, the result of the comparison computation of EMFCompare.
*EMFCompareConstants.COMPARE_RESULT, the comparison itself.
+
*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 simpler.
+
  
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).
+
<source lang="java">
 +
EMFCompare comparator = EMFCompare.builder().build();
 +
Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor));
 +
</source>
  
<pre>
+
=== ComparisonScopeEditorInput ===
final CompareConfiguration configuration = new CompareConfiguration();
+
configuration.setProperty(EMFCompareConstants.COMPARE_RESULT, comparison);
+
configuration.setProperty(EMFCompareConstants.EDITING_DOMAIN, new EMFCompareEditingDomain(comparison, left, right, ancestor));
+
</pre>
+
  
== Wiring it all together ==
+
You must provide the comparator (instance of EMFCompare) and the scope of the comparison.
  
Then, you can call the black magic method from Eclipse Compare framework: [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)].
+
<source lang="java">
 +
EMFCompare comparator = EMFCompare.builder().build();
 +
IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor);
 +
</source>
  
<pre>
+
== Opening the compare UI  ==
final Notifier left = ..., right = ..., ancestor = ...;
+
final Comparison comparison = ...;
+
  
final CompareConfiguration configuration = new CompareConfiguration();
+
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:
configuration.setProperty(EMFCompareConstants.COMPARE_RESULT, comparison);
+
configuration.setProperty(EMFCompareConstants.EDITING_DOMAIN, new EMFCompareEditingDomain(comparison, left, right, ancestor));
+
  
final CompareEditorInput input = new EMFCompareEditorInput(configuration);
+
* [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.
input.setTitle("My own compare dialog");
+
*[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);
 +
}
 +
</source>
 +
 
 +
=== With a comparison scope ===
 +
 
 +
<source lang="java">
 +
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);
 +
}
 +
</source>
  
configuration.setContainer(input);
+
[[Category:EMF_Compare]]
CompareUI.openCompareDialog(input);
+
</pre>
+

Revision as of 04: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.

Contents

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);
}