[572074] Constraint gmf.runtime range for Sirius integration

[EMFCompare2.git] / plugins / org.eclipse.emf.compare / src / org / eclipse / emf / compare / merge / FeatureMapChangeMerger.java

/*******************************************************************************
 * Copyright (c) 2014, 2017 Obeo and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *     Obeo - initial API and implementation
 *     Alexandra Buzila - Fixes for bug 446252
 *     Stefan Dirix - Fixes for Bugs 453218 and 453749
 *******************************************************************************/
package org.eclipse.emf.compare.merge;

import static org.eclipse.emf.compare.internal.utils.ComparisonUtil.isFeatureMapContainment;
import static org.eclipse.emf.compare.utils.ReferenceUtil.safeEGet;
import static org.eclipse.emf.compare.utils.ReferenceUtil.safeESet;

import com.google.common.collect.Iterables;

import java.util.List;

import org.eclipse.emf.compare.Comparison;
import org.eclipse.emf.compare.Diff;
import org.eclipse.emf.compare.DifferenceSource;
import org.eclipse.emf.compare.Equivalence;
import org.eclipse.emf.compare.FeatureMapChange;
import org.eclipse.emf.compare.Match;
import org.eclipse.emf.compare.ReferenceChange;
import org.eclipse.emf.compare.internal.utils.ComparisonUtil;
import org.eclipse.emf.compare.internal.utils.DiffUtil;
import org.eclipse.emf.compare.utils.IEqualityHelper;
import org.eclipse.emf.ecore.EObject;
import org.eclipse.emf.ecore.EReference;
import org.eclipse.emf.ecore.EStructuralFeature;
import org.eclipse.emf.ecore.resource.Resource;
import org.eclipse.emf.ecore.util.BasicFeatureMap;
import org.eclipse.emf.ecore.util.FeatureMap;
import org.eclipse.emf.ecore.util.FeatureMapUtil;
import org.eclipse.emf.ecore.xmi.XMIResource;

/**
 * This specific implementation of {@link AbstractMerger} will be used to merge attribute changes.
 * 
 * @author <a href="mailto:laurent.goubet@obeo.fr">Laurent Goubet</a>
 * @since 3.2
 */
public class FeatureMapChangeMerger extends AbstractMerger {
        /**
         * {@inheritDoc}
         * 
         * @see org.eclipse.emf.compare.merge.IMerger#isMergerFor(org.eclipse.emf.compare.Diff)
         */
        public boolean isMergerFor(Diff target) {
                return target instanceof FeatureMapChange;
        }

        /**
         * {@inheritDoc}
         * 
         * @see org.eclipse.emf.compare.merge.AbstractMerger#accept(org.eclipse.emf.compare.Diff, boolean)
         */
        @Override
        protected void accept(final Diff diff, boolean rightToLeft) {
                FeatureMapChange featureMapChange = (FeatureMapChange)diff;
                switch (diff.getKind()) {
                        case ADD:
                                // Create the same element in right
                                addInTarget(featureMapChange, rightToLeft);
                                break;
                        case DELETE:
                                // Delete that same element from right
                                removeFromTarget(featureMapChange, rightToLeft);
                                break;
                        case MOVE:
                                moveElement(featureMapChange, rightToLeft);
                                break;
                        case CHANGE:
                                changeValue(featureMapChange, rightToLeft);
                                break;
                        default:
                                break;
                }
        }

        /**
         * {@inheritDoc}
         * 
         * @see org.eclipse.emf.compare.merge.AbstractMerger#reject(org.eclipse.emf.compare.Diff, boolean)
         */
        @Override
        protected void reject(Diff diff, boolean rightToLeft) {
                FeatureMapChange featureMapChange = (FeatureMapChange)diff;
                switch (diff.getKind()) {
                        case ADD:
                                // We have a ADD on right. we need to revert this addition
                                removeFromTarget(featureMapChange, rightToLeft);
                                break;
                        case DELETE:
                                // DELETE in the right. We need to re-create this element
                                addInTarget(featureMapChange, rightToLeft);
                                break;
                        case MOVE:
                                moveElement(featureMapChange, rightToLeft);
                                break;
                        case CHANGE:
                                changeValue(featureMapChange, rightToLeft);
                                break;
                        default:
                                break;
                }
        }

        /**
         * This will be called when we need to create an element in the target side.
         * <p>
         * All necessary sanity checks have been made to ensure that the current operation is one that should
         * create an object in its side or add an object to an attribute. In other words, either :
         * <ul>
         * <li>We are copying from right to left and
         * <ul>
         * <li>we are copying an addition to the right side (we need to create the same object in the left), or
         * </li>
         * <li>we are copying a deletion from the left side (we need to revert the deletion).</li>
         * </ul>
         * </li>
         * <li>We are copying from left to right and
         * <ul>
         * <li>we are copying a deletion from the right side (we need to revert the deletion), or</li>
         * <li>we are copying an addition to the left side (we need to create the same object in the right).</li>
         * </ul>
         * </li>
         * </ul>
         * </p>
         * 
         * @param diff
         *            The diff we are currently merging.
         * @param rightToLeft
         *            Tells us whether we are to add an object on the left or right side.
         */
        @SuppressWarnings("unchecked")
        protected void addInTarget(FeatureMapChange diff, boolean rightToLeft) {
                final Match match = diff.getMatch();
                final EObject expectedContainer;
                if (rightToLeft) {
                        expectedContainer = match.getLeft();
                } else {
                        expectedContainer = match.getRight();
                }
                if (expectedContainer == null) {
                        throw new IllegalStateException(
                                        "Couldn't add in target because its parent hasn't been merged yet: " + diff); //$NON-NLS-1$
                }
                final Comparison comparison = match.getComparison();
                final EStructuralFeature attribute = diff.getAttribute();
                final FeatureMap.Entry expectedValue = (FeatureMap.Entry)diff.getValue();
                // We have the container, attribute and value. We need to know the insertion index.
                final int insertionIndex = findInsertionIndex(comparison, diff, rightToLeft);

                final List<Object> targetList = (List<Object>)safeEGet(expectedContainer, attribute);
                addFeatureMapValueInTarget(comparison, rightToLeft, targetList, insertionIndex, expectedValue);
        }

        /**
         * Add the FeatueMapEntry value at the insertionIndex position in the list.
         * 
         * @param comparison
         *            The comparison object.
         * @param rightToLeft
         *            The way of merge.
         * @param list
         *            The list into which {@code value} should be added.
         * @param insertionIndex
         *            The index at which {@code value} should be inserted into {@code list}. {@code -1} if it
         *            should be appended at the end of the list.
         * @param entry
         *            The value we need to add to {@code list}.
         */
        private void addFeatureMapValueInTarget(final Comparison comparison, final boolean rightToLeft,
                        final List<Object> list, final int insertionIndex, final FeatureMap.Entry entry) {
                final Object value = entry.getValue();
                final EStructuralFeature key = entry.getEStructuralFeature();
                if (value instanceof EObject) {
                        final EObject copy;
                        // The value has its equivalent on the opposite side, or not
                        final Match match = comparison.getMatch((EObject)value);
                        final EObject left = match.getLeft();
                        final EObject right = match.getRight();
                        if (rightToLeft && left != null) {
                                copy = left;
                        } else if (!rightToLeft && right != null) {
                                copy = right;
                        } else {
                                copy = createCopy((EObject)value);
                        }

                        ((BasicFeatureMap)(Object)list).addUnique(insertionIndex, FeatureMapUtil.createEntry(key, copy));

                        if (DiffUtil.isContainmentReference(key)) {
                                if (rightToLeft) {
                                        match.setLeft(copy);
                                } else {
                                        match.setRight(copy);
                                }
                                // Copy XMI ID when applicable.
                                final Resource initialResource = ((EObject)value).eResource();
                                final Resource targetResource = copy.eResource();
                                if (initialResource instanceof XMIResource && targetResource instanceof XMIResource) {
                                        ((XMIResource)targetResource).setID(copy,
                                                        ((XMIResource)initialResource).getID((EObject)value));
                                }
                        }
                } else {
                        ((BasicFeatureMap)(Object)list).add(insertionIndex, FeatureMapUtil.createEntry(key, value));
                }
        }

        /**
         * This will be called when we need to remove an element from the target side.
         * <p>
         * All necessary sanity checks have been made to ensure that the current operation is one that should
         * delete an object. In other words, we are :
         * <ul>
         * <li>Copying from right to left and either
         * <ul>
         * <li>we are copying a deletion from the right side (we need to remove the same object in the left) or,
         * </li>
         * <li>we are copying an addition to the left side (we need to revert the addition).</li>
         * </ul>
         * </li>
         * <li>Copying from left to right and either
         * <ul>
         * <li>we are copying an addition to the right side (we need to revert the addition), or.</li>
         * <li>we are copying a deletion from the left side (we need to remove the same object in the right).</li>
         * </ul>
         * </li>
         * </ul>
         * </p>
         * 
         * @param diff
         *            The diff we are currently merging.
         * @param rightToLeft
         *            Tells us whether we are to add an object on the left or right side.
         */
        @SuppressWarnings("unchecked")
        protected void removeFromTarget(FeatureMapChange diff, boolean rightToLeft) {
                final EObject currentContainer;
                if (rightToLeft) {
                        currentContainer = diff.getMatch().getLeft();
                } else {
                        currentContainer = diff.getMatch().getRight();
                }

                if (currentContainer != null) {
                        FeatureMap.Entry expectedValue = (FeatureMap.Entry)diff.getValue();

                        if (!isDiffSourceIsMergeTarget(diff, rightToLeft)) {
                                final List<Object> targetList = (List<Object>)safeEGet(currentContainer, diff.getAttribute());
                                for (Object object : targetList) {
                                        if (diff.getMatch().getComparison().getEqualityHelper().matchingValues(expectedValue,
                                                        object)) {
                                                expectedValue = (FeatureMap.Entry)object;
                                                break;
                                        }
                                }
                        }

                        final EStructuralFeature attribute = diff.getAttribute();
                        // We have the container, attribute and value to remove.
                        /*
                         * TODO if the same value appears twice, should we try and find the one that has actually been
                         * deleted? Will it happen that often? For now, remove the first occurence we find.
                         */
                        final List<Object> targetList = (List<Object>)safeEGet(currentContainer, attribute);
                        final Comparison comparison = diff.getMatch().getComparison();
                        removeFeatureMapValueFromTarget(comparison, rightToLeft, targetList, expectedValue);
                }
        }

        /**
         * Remove the FeatueMapEntry value from the list.
         * 
         * @param comparison
         *            The comparison object.
         * @param rightToLeft
         *            The way of merge.
         * @param list
         *            The list from which {@code value} should be removed.
         * @param entry
         *            The value we need to remove from {@code list}.
         */
        private void removeFeatureMapValueFromTarget(final Comparison comparison, final boolean rightToLeft,
                        final List<Object> list, final FeatureMap.Entry entry) {
                final Object value = entry.getValue();
                final EStructuralFeature key = entry.getEStructuralFeature();

                if (((EReference)key).isContainment()) {
                        final Match expectedContainerMatch = comparison.getMatch((EObject)value);
                        if (rightToLeft) {
                                expectedContainerMatch.setLeft(null);
                        } else {
                                expectedContainerMatch.setRight(null);
                        }
                }
                ((BasicFeatureMap)(Object)list).remove(key, value);
        }

        /**
         * This will be called when trying to copy a "MOVE" diff.
         * 
         * @param diff
         *            The diff we are currently merging.
         * @param rightToLeft
         *            Whether we should move the value in the left or right side.
         */
        protected void moveElement(final FeatureMapChange diff, final boolean rightToLeft) {
                final Match match = diff.getMatch();
                final Comparison comparison = match.getComparison();
                final EObject expectedContainer = ComparisonUtil.moveElementGetExpectedContainer(comparison, diff,
                                rightToLeft);
                if (expectedContainer == null) {
                        throw new IllegalStateException(
                                        "Couldn't move element because its parent hasn't been merged yet: " + diff); //$NON-NLS-1$
                }
                final FeatureMap.Entry expectedEntry = moveElementGetExpectedEntry(comparison, diff,
                                expectedContainer, rightToLeft);
                // We now know the target container, target attribute and target entry.
                doMove(diff, comparison, expectedContainer, expectedEntry, rightToLeft);
        }

        /**
         * Get the expected FeatureMap.Entry to move.
         * 
         * @param comparison
         *            The comparison object.
         * @param diff
         *            The diff we are currently merging.
         * @param expectedContainer
         *            The expected container that will contain the expected entry to move.
         * @param rightToLeft
         *            Whether we should move the value in the left or right side.
         * @return The expected entry if found, <code>null</code> otherwise.
         */
        private FeatureMap.Entry moveElementGetExpectedEntry(final Comparison comparison,
                        final FeatureMapChange diff, final EObject expectedContainer, final boolean rightToLeft) {
                final FeatureMap.Entry expectedEntry;
                if (isDiffSourceIsMergeTarget(diff, rightToLeft)) {
                        expectedEntry = getExpectedEntryWhenDiffSourceIsMergeTarget(comparison, diff);

                } else {
                        expectedEntry = getExpectedEntryWhenDiffSourceIsNotMergeTarget(comparison, diff,
                                        expectedContainer, rightToLeft);
                }
                return expectedEntry;
        }

        /**
         * Get the expected FeatureMap.Entry to move.
         * 
         * @param comparison
         *            The comparison object.
         * @param diff
         *            The diff we are currently merging.
         * @param expectedContainer
         *            The expected container that will contain the expected entry to move.
         * @param rightToLeft
         *            Whether we should move the value in the left or right side.
         * @return The expected entry if found, <code>null</code> otherwise.
         */
        @SuppressWarnings("unchecked")
        private FeatureMap.Entry getExpectedEntryWhenDiffSourceIsNotMergeTarget(final Comparison comparison,
                        final FeatureMapChange diff, final EObject expectedContainer, final boolean rightToLeft) {
                FeatureMap.Entry expectedEntry = null;
                final IEqualityHelper equalityHelper = comparison.getEqualityHelper();
                final FeatureMap.Entry diffEntry = (FeatureMap.Entry)diff.getValue();
                // It is a Move on containment entry and the diff has an equivalence.
                Equivalence equ = diff.getEquivalence();
                if (isFeatureMapContainment(diff) && equ != null) {
                        // There is a ReferenceChange associated with the FeatureMapChange. This ReferenceChange
                        // contains the expected value to move.
                        for (ReferenceChange equivalence : Iterables.filter(equ.getDifferences(),
                                        ReferenceChange.class)) {
                                final Match equivalenceMatchValue = comparison.getMatch(equivalence.getValue());
                                final Object expectedEntryValue;
                                if (rightToLeft) {
                                        expectedEntryValue = equivalenceMatchValue.getLeft();
                                } else {
                                        expectedEntryValue = equivalenceMatchValue.getRight();
                                }
                                expectedEntry = FeatureMapUtil.createEntry(diffEntry.getEStructuralFeature(),
                                                expectedEntryValue);
                                break;
                        }
                } else {
                        final List<Object> targetList = (List<Object>)safeEGet(expectedContainer, diff.getAttribute());
                        for (Object object : targetList) {
                                if (equalityHelper.matchingValues(diffEntry, object)) {
                                        expectedEntry = (FeatureMap.Entry)object;
                                        break;
                                }
                        }
                }
                return expectedEntry;
        }

        /**
         * Get the expected FeatureMap.Entry to move.
         * 
         * @param comparison
         *            The comparison object.
         * @param diff
         *            The diff we are currently merging.
         * @return The expected entry if found, <code>null</code> otherwise.
         */
        @SuppressWarnings("unchecked")
        private FeatureMap.Entry getExpectedEntryWhenDiffSourceIsMergeTarget(final Comparison comparison,
                        final FeatureMapChange diff) {
                final FeatureMap.Entry expectedEntry;
                final IEqualityHelper equalityHelper = comparison.getEqualityHelper();
                final FeatureMap.Entry diffEntry = (FeatureMap.Entry)diff.getValue();
                final Match matchValue = comparison.getMatch((EObject)diffEntry.getValue());
                final EObject value;
                if (diff.getSource() == DifferenceSource.RIGHT) {
                        value = matchValue.getRight();
                } else {
                        value = matchValue.getLeft();
                }
                if (comparison.isThreeWay() && isFeatureMapContainment(diff)) {
                        // search the origin key associated to the value
                        EStructuralFeature originKey = null;
                        final List<Object> originList = (List<Object>)safeEGet(matchValue.getOrigin().eContainer(),
                                        diff.getAttribute());
                        for (Object object : originList) {
                                if (object instanceof FeatureMap.Entry
                                                && equalityHelper.matchingValues(value, ((FeatureMap.Entry)object).getValue())) {
                                        // same value, get the key
                                        originKey = ((FeatureMap.Entry)object).getEStructuralFeature();
                                        break;
                                }
                        }
                        expectedEntry = FeatureMapUtil.createEntry(originKey, value);
                } else if (((EReference)diffEntry.getEStructuralFeature()).isContainment()) {
                        EStructuralFeature targetReference = getTargetReference(comparison, diff);
                        expectedEntry = FeatureMapUtil.createEntry(targetReference, value);
                } else {
                        expectedEntry = FeatureMapUtil.createEntry(diffEntry.getEStructuralFeature(), value);
                }
                return expectedEntry;
        }

        /**
         * Get the target EStructuralFeature when moving a FeatureMap.Entry.
         * 
         * @param comparison
         *            The comparison object.
         * @param diff
         *            The diff we are currently merging.
         * @return The target reference, i.e. the reference into which the value will be moved.
         */
        private EStructuralFeature getTargetReference(final Comparison comparison, final FeatureMapChange diff) {
                final FeatureMap.Entry diffEntry = (FeatureMap.Entry)diff.getValue();
                final Match equivalenceMatchValue = comparison.getMatch((EObject)diffEntry.getValue());
                final EObject targetValue;
                if (diff.getSource() == DifferenceSource.LEFT) {
                        targetValue = equivalenceMatchValue.getRight();
                } else {
                        targetValue = equivalenceMatchValue.getLeft();
                }
                return targetValue.eContainingFeature();
        }

        /**
         * Checks if the source of the given diff is the same as the target of the merge.
         * 
         * @param diff
         *            The diff we are currently merging.
         * @param rightToLeft
         *            Whether we should merge the diff in the left or right side.
         * @return true if the source of the given diff is the same as the target of the merge, false otherwise.
         */
        private boolean isDiffSourceIsMergeTarget(final Diff diff, final boolean rightToLeft) {
                DifferenceSource source = diff.getSource();
                return source == DifferenceSource.LEFT && rightToLeft
                                || source == DifferenceSource.RIGHT && !rightToLeft;
        }

        /**
         * This will do the actual work of moving the element into its attribute. All sanity checks were made in
         * {@link #moveElement(boolean)} and no more verification will be made here.
         * 
         * @param diff
         *            The diff we are currently merging.
         * @param comparison
         *            Comparison holding this Diff.
         * @param expectedContainer
         *            The container in which we are reorganizing an attribute.
         * @param expectedValue
         *            The value that is to be moved within its attribute.
         * @param rightToLeft
         *            Whether we should move the value in the left or right side.
         */
        @SuppressWarnings("unchecked")
        protected void doMove(FeatureMapChange diff, Comparison comparison, EObject expectedContainer,
                        FeatureMap.Entry expectedValue, boolean rightToLeft) {
                final EStructuralFeature attribute = diff.getAttribute();
                if (attribute.isMany()) {
                        // Element to move cannot be part of the LCS... or there would not be a MOVE diff
                        int insertionIndex = findInsertionIndex(comparison, diff, rightToLeft);
                        /*
                         * However, it could still have been located "before" its new index, in which case we need to take
                         * it into account.
                         */
                        final List<Object> targetList = (List<Object>)safeEGet(expectedContainer, attribute);
                        final int currentIndex = targetList.indexOf(expectedValue);
                        if (insertionIndex > currentIndex && currentIndex >= 0) {
                                insertionIndex--;
                        }

                        if (currentIndex == -1) {
                                if (insertionIndex < 0 || insertionIndex >= targetList.size()) {
                                        ((BasicFeatureMap)(Object)targetList).addUnique(expectedValue);
                                } else {
                                        ((BasicFeatureMap)(Object)targetList).addUnique(insertionIndex, expectedValue);
                                }
                        } else {
                                if (insertionIndex < 0 || insertionIndex >= targetList.size()) {
                                        ((BasicFeatureMap)(Object)targetList).move(targetList.size() - 1, expectedValue);
                                } else {
                                        ((BasicFeatureMap)(Object)targetList).move(insertionIndex, expectedValue);
                                }
                        }
                } else {
                        // This will never happen with the default diff engine, but may still be done from extenders
                        safeESet(expectedContainer, attribute, expectedValue);
                }
        }

        /**
         * This will be called by the merge operations in order to change a key.
         * 
         * @param diff
         *            The diff we are currently merging.
         * @param rightToLeft
         *            Direction of the merge.
         */
        @SuppressWarnings("unchecked")
        protected void changeValue(FeatureMapChange diff, boolean rightToLeft) {
                final Match match = diff.getMatch();
                final IEqualityHelper equalityHelper = match.getComparison().getEqualityHelper();
                final EStructuralFeature attribute = diff.getAttribute();
                final FeatureMap.Entry entry = (FeatureMap.Entry)diff.getValue();
                // the value we're looking for in expected and origin container.
                final Object entryValue = entry.getValue();

                // Get the XMI ID
                final String originValueId;
                if (entryValue instanceof EObject) {
                        final Resource initialResource = ((EObject)entryValue).eResource();
                        if (initialResource instanceof XMIResource) {
                                originValueId = ((XMIResource)initialResource).getID((EObject)entryValue);
                        } else {
                                originValueId = null;
                        }
                } else {
                        originValueId = null;
                }

                final EObject expectedContainer;
                if (rightToLeft) {
                        expectedContainer = match.getLeft();
                } else {
                        expectedContainer = match.getRight();
                }

                final EObject originContainer;
                final boolean resetToOrigin = diff.getSource() == DifferenceSource.LEFT && rightToLeft
                                || diff.getSource() == DifferenceSource.RIGHT && !rightToLeft;
                if (resetToOrigin && match.getComparison().isThreeWay()) {
                        originContainer = match.getOrigin();
                } else if (rightToLeft) {
                        originContainer = match.getRight();
                } else {
                        originContainer = match.getLeft();
                }

                // search the origin key associated to the value
                EStructuralFeature originKey = null;
                final List<Object> originList = (List<Object>)safeEGet(originContainer, attribute);
                for (Object object : originList) {
                        if (object instanceof FeatureMap.Entry) {
                                // same value, get the key
                                if (equalityHelper.matchingValues(entryValue, ((FeatureMap.Entry)object).getValue())) {
                                        originKey = ((FeatureMap.Entry)object).getEStructuralFeature();
                                        break;
                                }
                        }
                }

                if (originKey == null) {
                        throw new RuntimeException("FeatureMapChangeMerger: Cannot find the key to change."); //$NON-NLS-1$
                }

                // search the value in expected container to change his key.
                final List<Object> targetList = (List<Object>)safeEGet(expectedContainer, attribute);
                int index = 0;
                for (Object object : targetList) {
                        if (object instanceof FeatureMap.Entry) {
                                // same value, now change the key
                                Object targetValue = ((FeatureMap.Entry)object).getValue();
                                if (equalityHelper.matchingValues(entryValue, targetValue)) {
                                        // forced to use setUnique(int, Entry) because if the originKey is not present in the
                                        // target map, the setUnique(EStructuralFeature, int, Object) will not validate the key
                                        ((BasicFeatureMap)(Object)targetList).setUnique(index,
                                                        FeatureMapUtil.createEntry(originKey, targetValue));

                                        // setUnique(int, Entry) doesn't keep ID, so copy XMI ID when applicable.
                                        final Resource targetResource;
                                        if (DiffUtil.isContainmentReference(originKey) && targetValue instanceof EObject
                                                        && originValueId != null) {
                                                targetResource = ((EObject)targetValue).eResource();
                                        } else {
                                                targetResource = null;
                                        }
                                        if (targetResource instanceof XMIResource) {
                                                ((XMIResource)targetResource).setID((EObject)targetValue, originValueId);
                                        }
                                        break;
                                }
                        }
                        index++;
                }
        }

        /**
         * This will be used by the distinct merge actions in order to find the index at which a value should be
         * inserted in its target list. See {@link DiffUtil#findInsertionIndex(Comparison, Diff, boolean)} for
         * more on this.
         * <p>
         * Sub-classes can override this if the insertion order is irrelevant. A return value of {@code -1} will
         * be considered as "no index" and the value will be inserted at the end of its target list.
         * </p>
         * 
         * @param comparison
         *            This will be used in order to retrieve the Match for EObjects when comparing them.
         * @param diff
         *            The diff which merging will trigger the need for an insertion index in its target list.
         * @param rightToLeft
         *            {@code true} if the merging will be done into the left list, so that we should consider the
         *            right model as the source and the left as the target.
         * @return The index at which this {@code diff}'s value should be inserted into the 'target' list, as
         *         inferred from {@code rightToLeft}. {@code -1} if the value should be inserted at the end of its
         *         target list.
         * @see DiffUtil#findInsertionIndex(Comparison, Diff, boolean)
         */
        protected int findInsertionIndex(Comparison comparison, Diff diff, boolean rightToLeft) {
                return DiffUtil.findInsertionIndex(comparison, diff, rightToLeft);
        }
}