org.eclipse.compare.structuremergeviewer.Differencer

public class Differencer extends Object

A generic two-way or three-way differencing engine.

The engine is used by calling one of the findDifferences methods and passing in the objects to compare. The engine calls the following methods on the input objects to perform the compare:

getChildren: for enumerating the children of an object (if any),
contentsEqual: for comparing the content of leaf objects, that is, objects without children,
visit: for every pair of compared object the compare result is passed in.

Clients may use as is, or subclass to provide a custom implementation for the three hooks. However the default implementation already deals with the typical case:

getChildren: tries to apply the IStructureComparator interface to enumerate the children,
contentsEqual: tries to apply the IStreamContentAccessor interface to perform a byte-wise content comparison,
visit: creates a DiffNode for any detected difference between the compared objects and links it under a parent node effectively creating a tree of differences.

The different kind of changes detected by the engine are decoded as follows: In the two-way case only NO_CHANGE, ADDITION, DELETION, and CHANGE are used. In the three-way case these constants are bitwise ORed with one of directional constants LEFT, RIGHT, and CONFLICTING.

Field Summary

Fields

Modifier and Type

Field

Description

static final int

ADDITION

Difference constant (value 1) indicating one side was added.

static final int

CHANGE

Difference constant (value 3) indicating side changed.

static final int

CHANGE_TYPE_MASK

Bit mask (value 3) for extracting the kind of difference.

static final int

CONFLICTING

Three-way change constant (value 12) indicating a change on left and right sides.

static final int

DELETION

Difference constant (value 2) indicating one side was removed.

static final int

DIRECTION_MASK

Bit mask (value 12) for extracting the direction of a three-way change.

static final int

LEFT

Three-way change constant (value 4) indicating a change on left side.

static final int

NO_CHANGE

Difference constant (value 0) indicating no difference.

static final int

PSEUDO_CONFLICT

Constant (value 16) indicating a change on left and right side (with respect to ancestor) but left and right are identical.

static final int

RIGHT

Three-way change constant (value 8) indicating a change on right side.
Constructor Summary

Constructors

Constructor

Description

Differencer()

Creates a new differencing engine.
Method Summary

Modifier and Type

Method

Description

protected boolean

contentsEqual(Object input1, char contributor1, Object input2, char contributor2)

Performs a content compare on the two given inputs.

protected boolean

contentsEqual(Object input1, Object input2)

Performs a content compare on the two given inputs.

Object

findDifferences(boolean threeWay, IProgressMonitor pm, Object data, Object ancestor, Object left, Object right)

Starts the differencing engine on the three input objects.

protected Object[]

getChildren(Object input)

Returns the children of the given input or null if there are no children.

protected void

updateProgress(IProgressMonitor progressMonitor, Object node)

Called for every leaf or node compare to update progress information.

protected Object

visit(Object data, int result, Object ancestor, Object left, Object right)

Called for every node or leaf comparison.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- NO_CHANGE
  
  public static final int NO_CHANGE
  
  Difference constant (value 0) indicating no difference.
  See Also:
  
  Constant Field Values
- ADDITION
  
  public static final int ADDITION
  
  Difference constant (value 1) indicating one side was added.
  See Also:
  
  Constant Field Values
- DELETION
  
  public static final int DELETION
  
  Difference constant (value 2) indicating one side was removed.
  See Also:
  
  Constant Field Values
- CHANGE
  
  public static final int CHANGE
  
  Difference constant (value 3) indicating side changed.
  See Also:
  
  Constant Field Values
- CHANGE_TYPE_MASK
  
  public static final int CHANGE_TYPE_MASK
  
  Bit mask (value 3) for extracting the kind of difference.
  See Also:
  
  Constant Field Values
- LEFT
  
  public static final int LEFT
  
  Three-way change constant (value 4) indicating a change on left side.
  See Also:
  
  Constant Field Values
- RIGHT
  
  public static final int RIGHT
  
  Three-way change constant (value 8) indicating a change on right side.
  See Also:
  
  Constant Field Values
- CONFLICTING
  
  public static final int CONFLICTING
  
  Three-way change constant (value 12) indicating a change on left and right sides.
  See Also:
  
  Constant Field Values
- DIRECTION_MASK
  
  public static final int DIRECTION_MASK
  
  Bit mask (value 12) for extracting the direction of a three-way change.
  See Also:
  
  Constant Field Values
- PSEUDO_CONFLICT
  
  public static final int PSEUDO_CONFLICT
  
  Constant (value 16) indicating a change on left and right side (with respect to ancestor) but left and right are identical.
  See Also:
  
  Constant Field Values
Constructor Details
- Differencer
  
  public Differencer()
  
  Creates a new differencing engine.
Method Details
- findDifferences
  
  public Object findDifferences(boolean threeWay, IProgressMonitor pm, Object data, Object ancestor, Object left, Object right)
  
  Starts the differencing engine on the three input objects. If threeWay is true a three-way comparison is performed, otherwise a two-way compare (in the latter case the ancestor argument is ignored). The progress monitor is passed to the method updateProgress which is called for every node or leaf compare. The method returns the object that was returned from the top-most call to method visit. At most two of the ancestor, left, and right parameters are allowed to be null.
  
  Parameters:
  
  threeWay - if true a three-way comparison is performed, otherwise a two-way compare
  
  pm - a progress monitor which is passed to method updateProgress
  
  data - a client data that is passed to the top-level call to visit
  
  ancestor - the ancestor object of the compare (may be null)
  
  left - the left object of the compare
  
  right - the right object of the compare
  
  Returns:
  
  the object returned from the top most call to method visit, possibly null
- visit
  
  protected Object visit(Object data, int result, Object ancestor, Object left, Object right)
  
  Called for every node or leaf comparison. The differencing engine passes in the input objects of the compare and the result of the compare. The data object is the value returned from a call to the visit method on the parent input. It can be considered the "parent" reference and is useful when building a tree.
  The Differencer implementation returns a new DiffNode which is initialized with the corresponding values. Subclasses may override.
  
  Parameters:
  
  data - object returned from parent call to visit, possibly null
  
  result - the result of the compare operation performed on the three inputs
  
  ancestor - the compare ancestor of the left and right inputs
  
  left - the left input to the compare
  
  right - the right input to the compare
  
  Returns:
  
  the result, possibly null
- contentsEqual
  
  protected boolean contentsEqual(Object input1, char contributor1, Object input2, char contributor2)
  
  Performs a content compare on the two given inputs.
  The Differencer implementation returns contentsEqual(Object input1, Object input2). Subclasses may override to implement a different content compare on the given inputs.
  
  Parameters:
  
  input1 - first input to contents compare
  
  contributor1 - the contributor of input1
  
  input2 - second input to contents compare
  
  contributor2 - the contributor of input2
  
  Returns:
  
  true if content is equal
  
  Since:
  
  3.6
  
  Restriction:
  
  This method is not intended to be referenced by clients.
- contentsEqual
  
  protected boolean contentsEqual(Object input1, Object input2)
  
  Performs a content compare on the two given inputs.
  The Differencer implementation returns true if both inputs implement IStreamContentAccessor and their byte contents is identical. Subclasses may override to implement a different content compare on the given inputs.
  
  Parameters:
  
  input1 - first input to contents compare
  
  input2 - second input to contents compare
  
  Returns:
  
  true if content is equal
- getChildren
  
  protected Object[] getChildren(Object input)
  
  Returns the children of the given input or null if there are no children.
  The Differencer implementation checks whether the input implements the IStructureComparator interface. If yes it is used to return an array containing all children. Otherwise null is returned. Subclasses may override to implement a different strategy to enumerate children.
  
  Parameters:
  
  input - the object for which to return children
  
  Returns:
  
  the children of the given input or null if there are no children.
- updateProgress
  
  protected void updateProgress(IProgressMonitor progressMonitor, Object node)
  
  Called for every leaf or node compare to update progress information.
  The Differencer implementation shows the name of the input object as a subtask. Subclasses may override.
  
  Parameters:
  
  progressMonitor - the progress monitor for reporting progress
  
  node - the currently processed non-null node

Class Differencer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

NO_CHANGE

ADDITION

DELETION

CHANGE

CHANGE_TYPE_MASK

LEFT

RIGHT

CONFLICTING

DIRECTION_MASK

PSEUDO_CONFLICT

Constructor Details

Differencer

Method Details

findDifferences

visit

contentsEqual

contentsEqual

getChildren

updateProgress