Package org.eclipse.team.core.mapping

Interface IMergeContext

All Superinterfaces:

ISynchronizationContext

All Known Implementing Classes:

MergeContext, SubscriberMergeContext

public interface IMergeContext
extends ISynchronizationContext

Provides the context for an IResourceMappingMerger or a model specific synchronization view that supports merging.

The diff tree associated with this context may be updated asynchronously in response to calls to any method of this context (e.g. merge and markAsMerged methods) that may result in changes in the synchronization state of resources. It may also get updated as a result of changes triggered from other sources. Hence, the callback from the diff tree to report changes may occur in the same thread as the method call or asynchronously in a separate thread, regardless of who triggered the refresh. Clients of this method (and any other asynchronous method on this context) may determine if all changes have been collected using IJobManager.find(Object) using this context as the family argument in order to determine if there are any jobs running that are populating the diff tree. Clients may also call IJobManager.join(Object, IProgressMonitor) if they wish to wait until all background handlers related to this context are finished.

Since:

3.2

See Also:

• IResourceMappingMerger
• MergeContext

Restriction:

This interface is not intended to be implemented by clients. Clients should instead subclass MergeContext.

Field Summary

Fields inherited from interface org.eclipse.team.core.mapping.ISynchronizationContext

THREE_WAY, TWO_WAY

Method Summary

Modifier and Type	Method	Description
ISchedulingRule	getMergeRule(IDiff diff)	Return the scheduling rule that is required to merge (or reject) the resource associated with the given diff.
ISchedulingRule	getMergeRule(IDiff[] diffs)	Return the scheduling rule that is required to merge (or reject) the resources associated with the given diffs.
int	getMergeType()	Return the type of merge that will be performed when using this context (either ISynchronizationContext.TWO_WAY or ISynchronizationContext.THREE_WAY).
void	markAsMerged(IDiff[] nodes, boolean inSyncHint, IProgressMonitor monitor)	Mark the files associated with the given diff nodes as being merged.
void	markAsMerged(IDiff node, boolean inSyncHint, IProgressMonitor monitor)	Method that allows the model merger to signal that the file associated with the given diff node has been completely merged.
IStatus	merge(IDiff[] diffs, boolean ignoreLocalChanges, IProgressMonitor monitor)	Attempt to merge any files associated with the given diffs.
IStatus	merge(IDiff diff, boolean ignoreLocalChanges, IProgressMonitor monitor)	Method that can be called by the model merger to attempt a file-system level merge.
void	reject(IDiff[] diffs, IProgressMonitor monitor)	Reject the changes associated with the given diffs.
void	reject(IDiff diff, IProgressMonitor monitor)	Reject the change associated with the given diff.
void	run(IWorkspaceRunnable runnable, ISchedulingRule rule, int flags, IProgressMonitor monitor)	Runs the given action as an atomic workspace operation.

Methods inherited from interface org.eclipse.team.core.mapping.ISynchronizationContext

dispose, getCache, getDiffTree, getScope, getType, refresh, refresh

Method Details

getMergeType

int getMergeType()

Return the type of merge that will be performed when using this context (either ISynchronizationContext.TWO_WAY or ISynchronizationContext.THREE_WAY). In most cases, this type which match that returned by ISynchronizationContext.getType(). However, for some THREE_WAY synchronizations, the merge type may be TWO_WAY which indicates that clients of the context should ignore local changes when performing merges. This capability is provided to support replace operations that support three-way preview but ignore local changes when replacing.

Returns:

the type of merge that will be performed when using this context.

markAsMerged

void markAsMerged(IDiff node,
 boolean inSyncHint,
 IProgressMonitor monitor)
           throws CoreException

Method that allows the model merger to signal that the file associated with the given diff node has been completely merged. Model mergers can call this method if they have transfered all changes from a remote file to a local file and wish to signal that the merge is done. This will allow repository providers to update the synchronization state of the file to reflect that the file is up-to-date with the repository.

For two-way merging, this method can be used to reject any change. For three-way merging, this method should only be used when remote content in being merged with local content (i.e. the file exists both locally and remotely) with the exception that it can also be used to keep local changes to a file that has been deleted. See the merge(IDiff[], boolean, IProgressMonitor) method for more details. For other cases in which either the local file or remote file does not exist, one of the merge methods should be used. This is done to accommodate repositories that have special handling for file additions, removals and moves. Invoking this method with a diff node associated with a folder will have no effect.

The inSyncHint allows a client to indicate to the context that the model persisted in the file is in-sync. If the hint is true, the context should compare the local and remote file at the content level and make the local file in-sync with the remote if the contents are the same.

Parameters:

node - the diff node whose file has been merged

inSyncHint - a hint to the context that the model persisted in the file is in-sync.

monitor - a progress monitor

Throws:

CoreException - if errors occur

markAsMerged

void markAsMerged(IDiff[] nodes,
 boolean inSyncHint,
 IProgressMonitor monitor)
           throws CoreException

Mark the files associated with the given diff nodes as being merged. This method is equivalent to calling markAsMerged(IDiff, boolean, IProgressMonitor) for each diff but gives the context the opportunity to optimize the operation for multiple files.

This method will batch change notification by using the run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor) method. The rule for he method will be obtained using getMergeRule(IDiff) and the flags will be IResource.NONE meaning that intermittent change events may occur. Clients may wrap the call in an outer run that either uses a broader scheduling rule or the IWorkspace.AVOID_UPDATES flag.

Parameters:

nodes - the nodes to be marked as merged

inSyncHint - a hint to the context that the model persisted in the file is in-sync.

monitor - a progress monitor

Throws:

CoreException - if errors occur

merge

IStatus merge(IDiff diff,
 boolean ignoreLocalChanges,
 IProgressMonitor monitor)
       throws CoreException

Method that can be called by the model merger to attempt a file-system level merge. This is useful for cases where the model merger does not need to do any special processing to perform the merge. By default, this method attempts to use an appropriate IStorageMerger to merge the files covered by the provided traversals. If a storage merger cannot be found, the text merger is used. If this behavior is not desired, sub-classes of MergeContext may override this method.

This method does a best-effort attempt to merge of the file associated with the given diff. A file that could not be merged will be indicated in the returned status. If the status returned has the code MergeStatus.CONFLICTS, the list of failed files can be obtained by calling the MergeStatus#getConflictingFiles() method.

It is not expected that clients of this API will associate special meaning with the existence of a folder other than the fact that it contains files. The sync delta tree should still include folder changes so that clients that have a one-to-one correspondence between their model objects and folders can decorate these elements appropriately. However, clients of this API will only be expected to perform operations on file deltas and will expect folders to be created as needed to contain the files (i.e. implementations of this method should ignore any folder deltas in the provided deltas). Clients will also expect local folders that have incoming folder deletions to be removed once all the folder's children have been removed using merge.

There are two special cases where merge is meaningful for folders. First, a merge on a local added empty folder with force set should delete the folder. However, the folder should not be deleted if it has any local children unless merge is called for those resources first and they end up being deleted as a result. Second, a merge on an incoming folder addition should create the empty folder locally.

It is not expected that clients of this API will be capable of dealing with namespace conflicts. Implementors should ensure that any namespace conflicts are dealt with before the merger is invoked.

The deltas provided to this method should be those obtained from the tree (ISynchronizationContext.getDiffTree()) of this context. Any resource changes triggered by this merge will be reported through the resource delta mechanism and the change notification mechanisms of the delta tree associated with this context.

For two-way merging, as indicated by either the ISynchronizationContext.getType() or getMergeType() methods, clients can either accept changes using the merge(IDiff[], boolean, IProgressMonitor) method or reject them using markAsMerged(IDiff, boolean, IProgressMonitor). Three-way changes are a bit more complicated. The following list summarizes how particular remote file changes can be handled. The delta kind and flags mentioned in the descriptions are obtained the remote change (see IThreeWayDiff.getRemoteChange()), whereas conflicts are indicated by the three-way delta itself.

• When the delta kind is IDiff.ADD and the delta is also a move (i.e. the ITwoWayDiff.MOVE_FROM is set). The merge can either use the merge(IDiff[], boolean, IProgressMonitor) method to accept the rename or perform an IFile.move(IPath, boolean, boolean, IProgressMonitor) where the source file is obtained using ITwoWayDiff.getFromPath() and the destination is the path of the delta (IDiff.getPath()). This later approach is helpful in the case where the local file and remote file both contain content changes (i.e. the file can be moved by the model and then the contents can be merged by the model).
• When the delta kind is IDiff.REMOVE and the delta is also a move (i.e. the ITwoWayDiff.MOVE_TO is set). The merge can either use the merge(IDiff[], boolean, IProgressMonitor) method to accept the rename or perform an IFile.move(IPath, boolean, boolean, IProgressMonitor) where the source file is obtained using IDiff.getPath() and the destination is obtained from ITwoWayDiff.getToPath(). This later approach is helpful in the case where the local file and remote file both contain content changes (i.e. the file can be moved by the model and then the contents can be merged by the model).
• When the delta kind is IDiff.ADD and it is not part of a move, the merger must use the merge(IDiff[], boolean, IProgressMonitor) method to accept this change. If there is a conflicting addition, the force flag can be set to override the local change. If the model wishes to keep the local changes, they can overwrite the file after merging it. Models should consult the flags to see if the remote change is a rename (ITwoWayDiff.MOVE_FROM).
• When the delta kind is IDiff.REMOVE and it is not part of a move, the merger can use the merge(IDiff[], boolean, IProgressMonitor) method but could also perform the delete manually using any of the IFile delete methods. In the case where there are local changes to the file being deleted, the model may either choose to merge using the force flag (thus removing the file and the local changes) or call markAsMerged(IDiff, boolean, IProgressMonitor) on the file which will convert the incoming deletion to an outgoing addition.
• When the delta kind is IDiff.CHANGE and there is no conflict, the model is advised to use the merge(IDiff[], boolean, IProgressMonitor) method to merge these changes as this is the most efficient means to do so. However, the model can choose to perform the merge themselves and then invoke markAsMerged(IDiff, boolean, IProgressMonitor) with the inSyncHint set to true but this will be less efficient.
• When the delta kind is IDiff.CHANGE and there is a conflict, the model can use the merge(IDiff[], boolean, IProgressMonitor) method to merge these changes. If the force flag is not set, an auto-merge is attempted using an appropriate IStorageMerger. If the force flag is set, the local changes are discarded. The model can choose to attempt the merge themselves and, if it is successful, invoke markAsMerged(IDiff, boolean, IProgressMonitor) with the inSyncHint set to false which will make the file an outgoing change.

TODO: need to talk about ITwoWayDelta CONTENT and REPLACED

Parameters:

diff - the difference to be merged

ignoreLocalChanges - ignore any local changes when performing the merge.

monitor - a progress monitor

Returns:

a status indicating success or failure. A code of MergeStatus.CONFLICTS indicates that the file contain non-mergable conflicts and must be merged manually.

Throws:

CoreException - if an error occurs

See Also:

• IDiffTree.addDiffChangeListener(IDiffChangeListener)
• IWorkspace.addResourceChangeListener(IResourceChangeListener)

merge

IStatus merge(IDiff[] diffs,
 boolean ignoreLocalChanges,
 IProgressMonitor monitor)
       throws CoreException

Attempt to merge any files associated with the given diffs. This method is equivalent to calling merge(IDiff, boolean, IProgressMonitor) for each diff individually but gives the context a chance to perform a more optimal merge involving multiple resources.

This method will batch change notification by using the run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor) method. The rule for he method will be obtained using getMergeRule(IDiff) and the flags will be IResource.NONE meaning that intermittent change events may occur. Clients may wrap the call in an outer run that either uses a broader scheduling rule or the IWorkspace.AVOID_UPDATES flag.

Parameters:

diffs - the differences to be merged

ignoreLocalChanges - ignore any local changes when performing the merge.

monitor - a progress monitor

Returns:

a status indicating success or failure. A code of MergeStatus.CONFLICTS indicates that the file contain non-mergable conflicts and must be merged manually.

Throws:

CoreException - if an error occurs

reject

void reject(IDiff diff,
 IProgressMonitor monitor)
     throws CoreException

Reject the change associated with the given diff. For a two-way merge, this should just remove the change from the set of changes in the diff tree. For a three-way merge, this should throw away the remote change and keep any local changes. So, for instance, if the diff is an incoming change or a conflict, the result of rejecting the change should be an outgoing change that will make the remote state match the local state.

Parameters:

diff - the diff

monitor - a progress monitor

Throws:

CoreException - if an error occurs

reject

void reject(IDiff[] diffs,
 IProgressMonitor monitor)
     throws CoreException

Reject the changes associated with the given diffs. This method is equivalent to calling reject(IDiff, IProgressMonitor) for each diff.

Parameters:

diffs - the diffs

monitor - a progress monitor

Throws:

CoreException - if an error occurs

run

void run(IWorkspaceRunnable runnable,
 ISchedulingRule rule,
 int flags,
 IProgressMonitor monitor)
  throws CoreException

Runs the given action as an atomic workspace operation. It has the same semantics as IWorkspace.run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor) with the added behavior that any synchronization state updates are batched or deferred until the end of the operation (depending on the IWorkspace.AVOID_UPDATE flag.

Parameters:

runnable - a workspace runnable

rule - a scheduling rule to be obtained while the runnable is run

flags - flags indicating when updates occur (either IResource.NONE or IWorkspace.AVOID_UPDATE.

monitor - a progress monitor

Throws:

CoreException - if an error occurs

getMergeRule

ISchedulingRule getMergeRule(IDiff diff)

Return the scheduling rule that is required to merge (or reject) the resource associated with the given diff. If a resource being merged is a folder or project, the returned rule will be sufficient to merge any files contained in the folder or project. The returned rule also applies to markAsMerged(IDiff, boolean, IProgressMonitor) and reject(IDiff, IProgressMonitor).

Parameters:

diff - the diff to be merged

Returns:

the scheduling rule that is required to merge the resource of the given diff

getMergeRule

ISchedulingRule getMergeRule(IDiff[] diffs)

Return the scheduling rule that is required to merge (or reject) the resources associated with the given diffs. If a resource being merged is a folder or project, the returned rule will be sufficient to merge any files contained in the folder or project. The returned rule also applies to markAsMerged(IDiff[], boolean, IProgressMonitor) and reject(IDiff[], IProgressMonitor).

Parameters:

diffs - the diffs being merged

Returns:

the scheduling rule that is required to merge the resources of the given diffs