org.eclipse.compare
Class CompareEditorInput

java.lang.Object
  |
  +--org.eclipse.compare.CompareEditorInput

All Implemented Interfaces:

IAdaptable, IEditorInput, IPropertyChangeNotifier, IRunnableWithProgress

public abstract class CompareEditorInput

extends Object

implements IEditorInput, IPropertyChangeNotifier, IRunnableWithProgress

A compare operation which can present its results in a special editor. Running the compare operation and presentating the results in a compare editor are combined in one interface because it allows a client to keep the implementation all in one place while separating it from the innards of a specific UI implementation of compare/merge.

A CompareEditorInput defines methods for the following sequence steps:

• running a lengthy compare operation under progress monitor control,
• creating a UI for displaying the model and initializing the some widgets with the compare result,
• tracking the dirty state of the model in case of merge,
• saving the model.

The Compare plug-in's openCompareEditor method takes an ICompareEditorInput and starts sequencing through the above steps. If the compare result is not empty a new compare editor is opened and takes over the sequence until eventually closed.

The prepareInput method should contain the code of the compare operation. It is executed under control of a progress monitor and can be canceled. If the result of the compare is not empty, that is if there are differences that needs to be presented, the ICompareEditorInput should hold onto them and return them with the getCompareResult method. If the value returned from getCompareResult is not null a compare editor is opened on the ICompareEditorInput with title and title image initialized by the corresponding methods of the ICompareEditorInput.

Creation of the editor's SWT controls is delegated to the createContents method. Here the SWT controls must be created and initialized with the result of the compare operation.

If merging is allowed, the modification state of the compared constituents must be tracked and the dirty state returned from method isSaveNeeded. The value true triggers a subsequent call to save where the modified resources can be saved.

The most important part of this implementation is the setup of the compare/merge UI. The UI uses a simple browser metaphor to present compare results. The top half of the layout shows the structural compare results (e.g. added, deleted, and changed files), the bottom half the content compare results (e.g. textual differences between two files). A selection in the top pane is fed to the bottom pane. If a content viewer is registered for the type of the selected object, this viewer is installed in the pane. In addition if a structure viewer is registered for the selection type the top pane is split horizontally to make room for another pane and the structure viewer is installed in it. When comparing Java files this second structure viewer would show the structural differences within a Java file, e.g. added, deleted or changed methods and fields.

Subclasses provide custom setups, e.g. for a Catchup/Release operation by passing a subclass of CompareConfiguration and by implementing the prepareInput method. If a subclass cannot use the DiffTreeViewer which is installed by default in the top left pane, method createDiffViewer can be overridden.

See Also:

CompareUI, CompareEditorInput

Field Summary

static String

DIRTY_STATE The name of the "dirty" property (value "DIRTY_STATE").

Constructor Summary

CompareEditorInput(CompareConfiguration configuration)
Creates a CompareEditorInput which is initialized with the given compare configuration.

Method Summary

void	addPropertyChangeListener(IPropertyChangeListener listener) Adds a listener for property changes to this notifier.
void	contributeToToolBar(ToolBarManager toolBarManager) Adds standard actions to the given ToolBarManager.
Control	createContents(Composite parent) Create the SWT controls that are used to display the result of the compare operation.
Viewer	createDiffViewer(Composite parent) Factory method for creating a differences viewer for the top left pane.
boolean	exists() Returns false to indicate that this input should not appear in the "File Most Recently Used" menu.
Viewer	findContentViewer(Viewer oldViewer, ICompareInput input, Composite parent) Implements the dynamic viewer switching for content viewers.
Viewer	findStructureViewer(Viewer oldViewer, ICompareInput input, Composite parent) Implements the dynamic viewer switching for structure viewers.
Object	getAdapter(Class adapter) Returns an object which is an instance of the given class associated with this object.
CompareConfiguration	getCompareConfiguration() Returns the configuration object for the viewers within the compare editor.
Object	getCompareResult() Returns the compare result computed by the most recent call to the run method.
ImageDescriptor	getImageDescriptor() Returns the image descriptor for this input.
String	getMessage()
String	getName() Returns the name of this editor input for display purposes.
IPersistableElement	getPersistable() Returns null since this editor cannot be persisted.
String	getTitle() Returns the title which will be used in the compare editor's title bar.
Image	getTitleImage() Returns the title image which will be used in the compare editor's title bar.
String	getToolTipText() Returns the tool tip text for this editor input.
boolean	isSaveNeeded() Returns true if there are unsaved changes.
protected abstract Object	prepareInput(IProgressMonitor monitor) Runs the compare operation and returns the compare result.
void	removePropertyChangeListener(IPropertyChangeListener listener) Removes the given content change listener from this notifier.
void	run(IProgressMonitor monitor) Runs the compare operation and stores the compare result.
void	save(IProgressMonitor pm) Deprecated. Override method saveChanges instead.
void	saveChanges(IProgressMonitor pm) Save any unsaved changes.
void	setDirty(boolean dirty) Sets the dirty state of this input to the given value and sends out a PropertyChangeEvent if the new value differs from the old value.
void	setFocus() Asks this input to take focus within its container (editor).
protected void	setMessage(String message)
void	setTitle(String title) Sets the title which will be used when presenting the compare result.

Methods inherited from class java.lang.Object

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

Field Detail

DIRTY_STATE

public static final String DIRTY_STATE

The name of the "dirty" property (value "DIRTY_STATE").

See Also:

Constant Field Values

Constructor Detail

CompareEditorInput

public CompareEditorInput(CompareConfiguration configuration)

Creates a CompareEditorInput which is initialized with the given compare configuration. The compare configuration is passed to subsequently created viewers.

Parameters:

configuration - the compare configuration

Method Detail

getAdapter

public Object getAdapter(Class adapter)

Description copied from interface: IAdaptable

Returns an object which is an instance of the given class associated with this object. Returns null if no such object can be found.

Specified by:

getAdapter in interface IAdaptable

Parameters:

adapter - the adapter class to look up

Returns:

a object castable to the given class, or null if this object does not have an adapter for the given class

getImageDescriptor

public ImageDescriptor getImageDescriptor()

Description copied from interface: IEditorInput

Returns the image descriptor for this input.

Specified by:

getImageDescriptor in interface IEditorInput

Returns:

the image descriptor for this input

getToolTipText

public String getToolTipText()

Description copied from interface: IEditorInput

Returns the tool tip text for this editor input. This text is used to differentiate between two input with the same name. For instance, MyClass.java in folder X and MyClass.java in folder Y.

The format of the path will vary with each input type. For instance, if the editor input is of type IFileEditorInput this method should return the fully qualified resource path. For editor input of other types it may be different.

Specified by:

getToolTipText in interface IEditorInput

Returns:

the tool tip text

getName

public String getName()

Description copied from interface: IEditorInput

Returns the name of this editor input for display purposes.

For instance, if the fully qualified input name is "a\b\MyFile.gif", the return value would be just "MyFile.gif".

Specified by:

getName in interface IEditorInput

Returns:

the name string

getPersistable

public IPersistableElement getPersistable()

Returns null since this editor cannot be persisted.

Specified by:

getPersistable in interface IEditorInput

Returns:

null because this editor cannot be persisted

exists

public boolean exists()

Returns false to indicate that this input should not appear in the "File Most Recently Used" menu.

Specified by:

exists in interface IEditorInput

Returns:

false

setMessage

protected void setMessage(String message)

getMessage

public String getMessage()

getTitle

public String getTitle()

Returns the title which will be used in the compare editor's title bar. It can be set with setTitle.

Returns:

the title

setTitle

public void setTitle(String title)

Sets the title which will be used when presenting the compare result. This method must be called before the editor is opened.

Parameters:

title - the title to use for the CompareEditor

getTitleImage

public Image getTitleImage()

Returns the title image which will be used in the compare editor's title bar. Returns the title image which will be used when presenting the compare result. This implementation returns a generic compare icon. Subclasses can override.

Returns:

the title image, or null if none

getCompareConfiguration

public CompareConfiguration getCompareConfiguration()

Returns the configuration object for the viewers within the compare editor. Returns the configuration which was passed to the constructor.

Returns:

the compare configuration

contributeToToolBar

public void contributeToToolBar(ToolBarManager toolBarManager)

Adds standard actions to the given ToolBarManager.

Subclasses may override to add their own actions.

Parameters:

toolBarManager - the ToolBarManager to which to contribute

run

public void run(IProgressMonitor monitor)
         throws InterruptedException,
                InvocationTargetException

Runs the compare operation and stores the compare result.

Specified by:

run in interface IRunnableWithProgress

Parameters:

monitor - the progress monitor to use to display progress and receive requests for cancelation

Throws:

InvocationTargetException - if the prepareInput method must propagate a checked exception, it should wrap it inside an InvocationTargetException; runtime exceptions are automatically wrapped in an InvocationTargetException by the calling context

InterruptedException - if the operation detects a request to cancel, using IProgressMonitor.isCanceled(), it should exit by throwing InterruptedException

See Also:

IRunnableContext.run(boolean, boolean, org.eclipse.jface.operation.IRunnableWithProgress)

prepareInput

protected abstract Object prepareInput(IProgressMonitor monitor)
                                throws InvocationTargetException,
                                       InterruptedException

Runs the compare operation and returns the compare result. If null is returned no differences were found and no compare editor needs to be opened. Progress should be reported to the given progress monitor. A request to cancel the operation should be honored and acknowledged by throwing InterruptedException.

Note: this method is typically called in a modal context thread which doesn't have a Display assigned. Implementors of this method shouldn't therefore allocated any SWT resources in this method.

Parameters:

monitor - the progress monitor to use to display progress and receive requests for cancelation

Returns:

the result of the compare operation, or null if there are no differences

Throws:

InvocationTargetException - if the prepareInput method must propagate a checked exception, it should wrap it inside an InvocationTargetException; runtime exceptions are automatically wrapped in an InvocationTargetException by the calling context

InterruptedException - if the operation detects a request to cancel, using IProgressMonitor.isCanceled(), it should exit by throwing InterruptedException

getCompareResult

public Object getCompareResult()

Returns the compare result computed by the most recent call to the run method. Returns null if no differences were found.

Returns:

the compare result prepared in method prepareInput or null if there were no differences

createContents

public Control createContents(Composite parent)

Create the SWT controls that are used to display the result of the compare operation. Creates the SWT Controls and sets up the wiring between the individual panes. This implementation creates all four panes but makes only the necessary ones visible. Finally it feeds the compare result into the top left structure viewer and the content viewer.

Subclasses may override if they need to change the layout or wiring between panes.

Parameters:

parent - the parent control under which the control must be created

Returns:

the SWT control hierarchy for the compare editor

setFocus

public void setFocus()

Asks this input to take focus within its container (editor).

Clients should not call this method but they may override if they implement a different layout with different visual components. Clients are free to call the inherited method.

createDiffViewer

public Viewer createDiffViewer(Composite parent)

Factory method for creating a differences viewer for the top left pane. It is called from createContents and returns a DiffTreeViewer.

Subclasses may override if they need a different viewer.

Parameters:

parent - the SWT parent control under which to create the viewer's SWT controls

Returns:

a compare viewer for the top left pane

findStructureViewer

public Viewer findStructureViewer(Viewer oldViewer,
                                  ICompareInput input,
                                  Composite parent)

Implements the dynamic viewer switching for structure viewers. The method must return a compare viewer based on the old (or current) viewer and a new input object. If the old viewer is suitable for showing the new input the old viewer can be returned. Otherwise a new viewer must be created under the given parent composite or null can be returned to indicate that no viewer could be found.

This implementation forwards the request to CompareUI.findStructureViewer.

Subclasses may override to implement a different strategy.

Returns:

a compare viewer which is suitable for the given input object or null

findContentViewer

public Viewer findContentViewer(Viewer oldViewer,
                                ICompareInput input,
                                Composite parent)

Implements the dynamic viewer switching for content viewers. The method must return a compare viewer based on the old (or current) viewer and a new input object. If the old viewer is suitable for showing the new input the old viewer can be returned. Otherwise a new viewer must be created under the given parent composite or null can be returned to indicate that no viewer could be found.

This implementation forwards the request to CompareUI.findContentViewer.

Subclasses may override to implement a different strategy.

Returns:

a compare viewer which is suitable for the given input object or null

isSaveNeeded

public boolean isSaveNeeded()

Returns true if there are unsaved changes. The value returned is the value of the DIRTY_STATE property of this input object. Returns true if this input has unsaved changes, that is if setDirty(true) has been called. Subclasses don't have to override if the functionality provided by setDirty is sufficient.

Returns:

true if there are changes that need to be saved

setDirty

public void setDirty(boolean dirty)

Sets the dirty state of this input to the given value and sends out a PropertyChangeEvent if the new value differs from the old value.

Parameters:

dirty - the dirty state for this compare input

addPropertyChangeListener

public void addPropertyChangeListener(IPropertyChangeListener listener)

Description copied from interface: IPropertyChangeNotifier

Adds a listener for property changes to this notifier. Has no effect if an identical listener is already registered.

Specified by:

addPropertyChangeListener in interface IPropertyChangeNotifier

Parameters:

listener - a property change listener

removePropertyChangeListener

public void removePropertyChangeListener(IPropertyChangeListener listener)

Description copied from interface: IPropertyChangeNotifier

Removes the given content change listener from this notifier. Has no effect if the identical listener is not registered.

Specified by:

removePropertyChangeListener in interface IPropertyChangeNotifier

Parameters:

listener - a property change listener

save

public void save(IProgressMonitor pm)

Deprecated. Override method saveChanges instead.

Save any unsaved changes. Empty implementation. Subclasses must override to save any changes.

saveChanges

public void saveChanges(IProgressMonitor pm)
                 throws CoreException

Save any unsaved changes. Subclasses must override to save any changes. This implementation tries to flush changes in all viewers by calling ISavable.save on them.

CoreException

Since:

2.0