Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.compare.structuremergeviewer
Class Differencer

    java.lang.Object
      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
`static int` | `ADDITION` Difference constant (value 1) indicating one side was added.
`static int` | `CHANGE` Difference constant (value 3) indicating side changed.
`static int` | `CHANGE_TYPE_MASK` Bit mask (value 3) for extracting the kind of difference.
`static int` | `CONFLICTING` Three-way change constant (value 12) indicating a change on left and right sides.
`static int` | `DELETION` Difference constant (value 2) indicating one side was removed.
`static int` | `DIRECTION_MASK` Bit mask (value 12) for extracting the direction of a three-way change.
`static int` | `LEFT` Three-way change constant (value 4) indicating a change on left side.
`static int` | `NO_CHANGE` Difference constant (value 0) indicating no difference.
`static 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 int` | `RIGHT` Three-way change constant (value 8) indicating a change on right side.

Constructor Summary
`Differencer()` Creates a new differencing engine.

Method Summary
`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 Detail

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

### Differencer

    public Differencer()

  Creates a new differencing engine.

Method Detail

### 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,
                                    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

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.