Package org.eclipse.emf.compare.diff

# Class DefaultDiffEngine

java.lang.Object
org.eclipse.emf.compare.diff.DefaultDiffEngine

All Implemented Interfaces:
  `IDiffEngine`

public class DefaultDiffEngine extends Object implements IDiffEngine
The diff engine is in charge of actually computing the differences between the objects mapped by a `Match` object.

This default implementation aims at being generic enough to be used for any model, whatever the metamodel. However, specific differences, refinements of differences or even higher level differences might be necessary.

TODO document available extension possibilities.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected static final Object`
`UNMATCHED_VALUE`
We'll use this "placeholder" to differentiate the unmatched elements from the "null" values that attributes can legitimately use.

## Constructor Summary

Constructors
Constructor
Description
`DefaultDiffEngine()`
Create the diff engine.
`DefaultDiffEngine(IDiffProcessor processor)`
Create the diff engine.

## Method Summary

Modifier and Type
Method
Description
`protected void`
`checkForDifferences(Match match, Monitor monitor)`
Checks the given `Match`'s sides for potential differences.
`protected void`
`checkResourceAttachment(Match match, Monitor monitor)`
Checks whether the given `Match`'s sides have changed resources.
`protected void`
`computeContainmentDifferences(Match match, EReference reference, boolean checkOrdering)`
Delegates the computation of Differences for a given containment reference according to the type of comparison (two- or three-way), and whether we need to take ordering changes into account.
`protected void`
`computeContainmentDifferencesThreeWay(Match match, EReference reference, boolean checkOrdering)`
Computes the difference between the sides of the given `match` for the given containment `reference`.
`protected void`
`computeContainmentDifferencesTwoWay(Match match, EReference reference, boolean checkOrdering)`
Computes the difference between the sides of the given `match` for the given containment `reference`.
`protected void`
`computeDifferences(Match match, EAttribute attribute, boolean checkOrdering)`
Computes the difference between the sides of the given `match` for the given `attribute`.
`protected void`
`computeDifferences(Match match, EReference reference, boolean checkOrdering)`
Computes the difference between the sides of the given `match` for the given `reference`.
`protected void`
`computeMultiValuedFeatureDifferences(Match match, EStructuralFeature feature, boolean checkOrdering)`
Delegates the computation of Differences for a given muti-valued feature according to the type of comparison (two- or three-way), and whether we need to take ordering changes into account.
`protected void`
`computeMultiValuedFeatureDifferencesThreeWay(Match match, EStructuralFeature feature, boolean checkOrdering)`
Computes the difference between the sides of the given `match` for the given multi-valued `feature`.
`protected void`
`computeMultiValuedFeatureDifferencesTwoWay(Match match, EStructuralFeature feature, boolean checkOrdering)`
Computes the difference between the sides of the given `match` for the given multi-valued `feature`.
`protected void`
`computeSingleValuedAttributeDifferences(Match match, EAttribute attribute)`
Computes the difference between the sides of the given `match` for the given single-valued `attribute`.
`protected void`
`computeSingleValuedReferenceDifferencesThreeWay(Match match, EReference reference)`
Computes the difference between the sides of the given `match` for the given single-valued `reference`.
`protected void`
`computeSingleValuedReferenceDifferencesTwoWay(Match match, EReference reference)`
Computes the difference between the sides of the given `match` for the given single-valued `reference`.
`protected void`
`createContainmentDifferences(Match match, EReference reference, boolean checkOrdering, List<Object> values, List<Object> lcsWithOrigin, DifferenceSource side)`
Called from `computeContainmentDifferencesThreeWay(Match, EReference, boolean)` once our LCS have been computed and we know what really changed.
`protected void`
`createContainmentDifferencesNoOrdering(Match match, EReference reference, List<Object> sideValues, DifferenceSource side)`
This will iterate over the given list of values from a containment reference and create the differences that can be detected from it.
`protected FeatureFilter`
`createFeatureFilter()`
This will be used in order to create the `FeatureFilter` that should be used by this engine to determine the structural features on which it is to try and detect differences.
`protected void`
`createMultiValuedFeatureDifferencesNoOrdering(Match match, EStructuralFeature feature, List<Object> sideValues, List<Object> originValues, DifferenceSource side)`
This will iterate over the given list of values from a multi-valued feature and create the differences that can be detected from it.
`void`
`diff(Comparison comparison, Monitor monitor)`
This is the entry point of the differencing process.
`protected void`
`featureChange(Match match, EStructuralFeature feature, Object value, DifferenceKind kind, DifferenceSource source)`
Delegates to the diff processor to create the specified feature change.
`protected final IDiffProcessor`
`getDiffProcessor()`
This will return the diff processor that has been created through `#createDiffProcessor()` for this differencing process.
`protected static com.google.common.base.Optional<Object>`
`getIfPresent(List<Object> list, int index)`
This will be used in order to read the LCS synchronously with the iteration on its target lists' values.
`protected static com.google.common.base.Optional<Match>`
`getMatchIfPresent(Comparison comparison, List<Object> list, int index)`
This will be used in order to read the LCS synchronously with the iteration on its target lists' values.
`protected <E> int`
`indexOf(Comparison comparison, List<E> list, E element)`
Checks whether the given `list` contains the given `element` according to the semantics of `IEqualityHelper#matchingValues(Comparison, Object, Object)` and returns the index at which it is positioned if applicable.
`protected static boolean`
`isRoot(EObject eObj)`
Checks whether the given EObject is a root of its resource or not.
`protected boolean`
`matchingContainment(IEqualityHelper equalityHelper, EObject o1, EObject o2)`
Checks whether the two given EObjects are contained within the same object, under the same reference.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### UNMATCHED_VALUE

protected static final Object UNMATCHED_VALUE
We'll use this "placeholder" to differentiate the unmatched elements from the "null" values that attributes can legitimately use.

## Constructor Details

### DefaultDiffEngine

public DefaultDiffEngine()
Create the diff engine.

### DefaultDiffEngine

public DefaultDiffEngine(IDiffProcessor processor)
Create the diff engine.

Parameters:
  `processor` - this instance will be called for each detected difference.

## Method Details

### indexOf

protected <E> int indexOf(Comparison comparison, List<E> list, E element)
Checks whether the given `list` contains the given `element` according to the semantics of `IEqualityHelper#matchingValues(Comparison, Object, Object)` and returns the index at which it is positioned if applicable.

Type Parameters:
  `E` - Type of the input iterable's content.
Parameters:
  `comparison` - This will be used in order to retrieve the Match for EObjects when comparing them.
  `list` - List which content we are to check.
  `element` - The element we expect to be contained in `list`.
Returns:
  The index at which the given `list` contains `element`, `-1` otherwise.

### diff

public void diff(Comparison comparison, Monitor monitor)
This is the entry point of the differencing process.

It will complete the input `comparison` by iterating over the `matches` it contain, filling in the differences it can detect for each distinct Match.

Specified by:
  `diff` in interface `IDiffEngine`
Parameters:
  `comparison` - The comparison this engine is expected to complete.
  `monitor` - The monitor to report progress or to check for cancellation.
See Also:
  - `IDiffEngine.diff(org.eclipse.emf.compare.Comparison, org.eclipse.emf.common.util.Monitor)`

### checkForDifferences

protected void checkForDifferences(Match match, Monitor monitor)
Checks the given `Match`'s sides for potential differences. Will recursively check for differences on submatches.

Parameters:
  `match` - The match that is to be checked.
  `monitor` - The monitor to report progress or to check for cancellation.

### checkResourceAttachment

protected void checkResourceAttachment(Match match, Monitor monitor)
Checks whether the given `Match`'s sides have changed resources. This will only be called for `Match` elements referencing the root(s) of an EMF Resource.

Parameters:
  `match` - The match that is to be checked.
  `monitor` - The monitor to report progress or to check for cancellation.

### isRoot

protected static boolean isRoot(EObject eObj)
Checks whether the given EObject is a root of its resource or not.

Parameters:
  `eObj` - The EObject to check.
Returns:
  `true` if this object is a root of its containing resource, `false` otherwise.

### computeContainmentDifferences

protected void computeContainmentDifferences(Match match, EReference reference, boolean checkOrdering)
Delegates the computation of Differences for a given containment reference according to the type of comparison (two- or three-way), and whether we need to take ordering changes into account.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The reference whose values are currently being checked for differences.
  `checkOrdering` - Whether we need to detect ordering changes or ignore them.

### computeMultiValuedFeatureDifferences

protected void computeMultiValuedFeatureDifferences(Match match, EStructuralFeature feature, boolean checkOrdering)
Delegates the computation of Differences for a given muti-valued feature according to the type of comparison (two- or three-way), and whether we need to take ordering changes into account.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `feature` - The feature whose values are currently being checked for differences.
  `checkOrdering` - Whether we need to detect ordering changes or ignore them.

### computeContainmentDifferencesThreeWay

protected void computeContainmentDifferencesThreeWay(Match match, EReference reference, boolean checkOrdering)
Computes the difference between the sides of the given `match` for the given containment `reference`.

This is only meant for three-way comparisons.

Note that this is no longer used for references which ordering is not considered, so `checkOrdering` will always be `true` .

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The containment reference which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this reference, `false` otherwise.

### createContainmentDifferencesNoOrdering

protected void createContainmentDifferencesNoOrdering(Match match, EReference reference, List<Object> sideValues, DifferenceSource side)
This will iterate over the given list of values from a containment reference and create the differences that can be detected from it.

Ordering changes will not be considered at all from this method. Values that exist in both the given list of elements and the origin (either ancestor or right side for two-way comparisons), will only have a Diff if their container or containing reference has changed. If they are still in the same container and reference, then even if they are not in the same position, we will not try and detect an ordering change.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The containment reference which values are to be checked.
  `sideValues` - Value of that `reference` on the given `side`.
  `side` - The side currently being compared.

### createContainmentDifferences

protected void createContainmentDifferences(Match match, EReference reference, boolean checkOrdering, List<Object> values, List<Object> lcsWithOrigin, DifferenceSource side)
Called from `computeContainmentDifferencesThreeWay(Match, EReference, boolean)` once our LCS have been computed and we know what really changed. It will be used for both the left and right side.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The containment reference which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this reference, `false` otherwise.
  `values` - Value of that `reference` on the given `side`.
  `lcsWithOrigin` - LCS between the reference values on the given `side` and the values in origin.
  `side` - The side currently being compared.

### matchingContainment

protected boolean matchingContainment(IEqualityHelper equalityHelper, EObject o1, EObject o2)
Checks whether the two given EObjects are contained within the same object, under the same reference.

Parameters:
  `equalityHelper` - Our current equality helper.
  `o1` - First of the two EObjects to compare.
  `o2` - Second of the two EObjects to compare.
Returns:
  `true` if these two objects are contained within the same container, false otherwise.

### getMatchIfPresent

protected static com.google.common.base.Optional<Match> getMatchIfPresent(Comparison comparison, List<Object> list, int index)
This will be used in order to read the LCS synchronously with the iteration on its target lists' values. This should be used cautiously since it will work on empty lists, null values and out-of-scope objects.

Parameters:
  `comparison` - The current comparison.
  `list` - A list of EObjects. May be empty or contain out-of-scope values.
  `index` - Index of the object we seek within this list.
Returns:
  An optional containing the match of the object at the given index... or `Optional.absent()`.

### getIfPresent

protected static com.google.common.base.Optional<Object> getIfPresent(List<Object> list, int index)
This will be used in order to read the LCS synchronously with the iteration on its target lists' values. This should be used cautiously since it will work on empty lists, and null values contained in the list are treated the same as an empty list and considered to be Optional.absent().

Parameters:
  `list` - A list of EObjects. May be empty or contain null or out-of-scope values.
  `index` - Index of the object we seek within this list.
Returns:
  An optional containing the object at the given index... or `Optional.absent()`.

### computeContainmentDifferencesTwoWay

protected void computeContainmentDifferencesTwoWay(Match match, EReference reference, boolean checkOrdering)
Computes the difference between the sides of the given `match` for the given containment `reference`.

This is only meant for two-way comparisons.

Note that this is no longer used for references which ordering is not considered, so `checkOrdering` will always be `true` .

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The containment reference which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this reference, `false` otherwise.

### computeDifferences

protected void computeDifferences(Match match, EAttribute attribute, boolean checkOrdering)
Computes the difference between the sides of the given `match` for the given `attribute`.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `attribute` - The attribute which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this attribute, `false` otherwise.

### computeDifferences

protected void computeDifferences(Match match, EReference reference, boolean checkOrdering)
Computes the difference between the sides of the given `match` for the given `reference`.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The reference which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this reference, `false` otherwise.

### computeMultiValuedFeatureDifferencesThreeWay

protected void computeMultiValuedFeatureDifferencesThreeWay(Match match, EStructuralFeature feature, boolean checkOrdering)
Computes the difference between the sides of the given `match` for the given multi-valued `feature`.

The given `feature` cannot be a containment reference.

This is only meant for three-way comparisons.

Note that this is no longer used for features which ordering is not considered, so `checkOrdering` will always be `true` .

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `feature` - The feature which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this feature, `false` otherwise.

### createMultiValuedFeatureDifferencesNoOrdering

protected void createMultiValuedFeatureDifferencesNoOrdering(Match match, EStructuralFeature feature, List<Object> sideValues, List<Object> originValues, DifferenceSource side)
This will iterate over the given list of values from a multi-valued feature and create the differences that can be detected from it.

Ordering changes will not be considered at all from this method. Values that exist in both the given list of elements and the origin (either ancestor or right side for two-way comparisons), will never have a Diff even if they are not at the same index in the list of their respective side.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `feature` - The feature which values are to be checked. Cannot be a containment reference.
  `sideValues` - Value of that `reference` on the given `side`.
  `originValues` - Value of that `reference` on the origin side. Could be the common ancestor or the right side in case of two-way comparisons.
  `side` - The side currently being compared.

### computeMultiValuedFeatureDifferencesTwoWay

protected void computeMultiValuedFeatureDifferencesTwoWay(Match match, EStructuralFeature feature, boolean checkOrdering)
Computes the difference between the sides of the given `match` for the given multi-valued `feature`.

The given `feature` cannot be a containment reference.

This is only meant for two-way comparisons.

Note that this is no longer used for features which ordering is not considered, so `checkOrdering` will always be `true` .

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `feature` - The feature which values are to be checked.
  `checkOrdering` - `true` if we should consider ordering changes on this feature, `false` otherwise.

### computeSingleValuedAttributeDifferences

protected void computeSingleValuedAttributeDifferences(Match match, EAttribute attribute)
Computes the difference between the sides of the given `match` for the given single-valued `attribute`.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `attribute` - The attribute which values are to be checked.

### computeSingleValuedReferenceDifferencesThreeWay

protected void computeSingleValuedReferenceDifferencesThreeWay(Match match, EReference reference)
Computes the difference between the sides of the given `match` for the given single-valued `reference`.

The given `reference` cannot be a containment reference.

This is only meant for three-way comparisons.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The reference which values are to be checked.

### computeSingleValuedReferenceDifferencesTwoWay

protected void computeSingleValuedReferenceDifferencesTwoWay(Match match, EReference reference)
Computes the difference between the sides of the given `match` for the given single-valued `reference`.

The given `reference` cannot be a containment reference.

This is only meant for two-way comparisons.

Parameters:
  `match` - The match which sides we need to check for potential differences.
  `reference` - The reference which values are to be checked.

### createFeatureFilter

protected FeatureFilter createFeatureFilter()
This will be used in order to create the `FeatureFilter` that should be used by this engine to determine the structural features on which it is to try and detect differences.

Returns:
  The newly created feature filter.

### featureChange

protected void featureChange(Match match, EStructuralFeature feature, Object value, DifferenceKind kind, DifferenceSource source)
Delegates to the diff processor to create the specified feature change.

Parameters:
  `match` - The match on which values we detected a diff.
  `feature` - The exact feature on which a diff was detected.
  `value` - The value for which we detected a changed.
  `kind` - The kind of difference to create.
  `source` - The source from which originates that diff.

### getDiffProcessor

protected final IDiffProcessor getDiffProcessor()
This will return the diff processor that has been created through `#createDiffProcessor()` for this differencing process.

Returns:
  The diff processor to notify of difference detections.