## Advanced compare techniques

This section provides additional information about advanced API in the compare plug-in.

### Writing compare operations

A compare operation must be implemented as a subclass of CompareEditorInput. A CompareEditorInput runs a (potentially lengthy) compare operation under progress monitor control, creates a UI for drilling-down into the compare results, tracks the dirty state of the result in case of merge, and saves any changes that occurred during a merge.

CompareUI defines the entry point to initiate a configurable compare operation on arbitrary resources. The result of the compare is opened into a compare editor where the details can be browsed and edited in dynamically selected structure and content viewers.

NavigationAction is used to navigate (step) through the individual differences of a CompareEditorInput.

CompareConfiguration configures various UI aspects of compare/merge viewers like title labels and images, or whether a side of a merge viewer is editable. It is passed to the CompareEditorInput on creation.

When implementing a hierarchical compare operation as a subclass of CompareEditorInput, clients must provide a tree of objects where each node implements the interface IStructureComparator. This interface is used by the hierarchical differencing engine (Differencer) to walk the tree.
In addition every leaf of the tree must implement the IStreamContentAccessor interface in order to give the differencing engine access to its stream content.

BufferedContent provides a default implementation for the IStreamContentAccessor and IContentChangeNotifier interfaces. Its subclass ResourceNode adds an implementation for the IStructureComparator and ITypedElement interfaces based on platform workbench resources (IResource). It can be used without modification as the input to the differencing engine.

### Compare functionality outside of compare editors

If you want to use compare functionality outside of the standard compare editor (for example, in a dialog or wizard) the compare plug-in provides additional helper classes.

CompareViewerPane is a convenience class which provides a label and local toolbar for a compare viewer (or any other subclass of a JFace viewer). Its abstract subclass CompareViewerSwitchingPane supports dynamic viewer switching, that is the viewer installed in the pane is dynamically determined by the pane's input object.

### Comparing a single file in an editor

The CompareEditorInput supports the comparison of an arbitrary file/folder structure which can be displayed in an editor, dialog or view. However, the specific case of comparing a single file in an editor warrants special handling because, in that case, the desired behavior should be close to that of editing the file. So, for this purpose a subclass of CompareEditorInput has been provided. The SaveableCompareEditorInput class provides this capability and has the following features:

- provides a static method `createFileElement` for creating a type element that represents a file.
- supports the use of shared documents (i.e. file buffers).
- supports the workbench Saveables API.
- auto-closes when changes are resolved.
- initializes asynchronously.

### Working with patches

The ApplyPatchOperation provides the ability to launch the Apply Patch wizard programmatically. The pages shown by the wizard are determined using the inputs to the operation. The class also contains the static method `parsePatch` which can be used by clients to deal with patches in a custom manner.