Class 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 Detail

      • 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 Detail

      • 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 Detail

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