public interface IMergeContext extends ISynchronizationContext
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.
IResourceMappingMerger
,
MergeContext
MergeContext
.THREE_WAY, TWO_WAY
Modifier and Type | Method and 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.
|
dispose, getCache, getDiffTree, getScope, getType, refresh, refresh
int getMergeType()
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.void markAsMerged(IDiff node, boolean inSyncHint, IProgressMonitor monitor) throws CoreException
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.
node
- the diff node whose file has been mergedinSyncHint
- a hint to the context that the model persisted in the
file is in-sync.monitor
- a progress monitorCoreException
- if errors occurvoid markAsMerged(IDiff[] nodes, boolean inSyncHint, IProgressMonitor monitor) throws CoreException
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.
nodes
- the nodes to be marked as mergedinSyncHint
- a hint to the context that the model persisted in the
file is in-sync.monitor
- a progress monitorCoreException
- if errors occurIStatus merge(IDiff diff, boolean ignoreLocalChanges, IProgressMonitor monitor) throws CoreException
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.
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). 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). 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
).
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.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. 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. diff
- the difference to be mergedignoreLocalChanges
- ignore any local changes when performing the merge.monitor
- a progress monitorMergeStatus.CONFLICTS
indicates that the file
contain non-mergable conflicts and must be merged manually.CoreException
- if an error occursIDiffTree.addDiffChangeListener(IDiffChangeListener)
,
IWorkspace.addResourceChangeListener(IResourceChangeListener)
IStatus merge(IDiff[] diffs, boolean ignoreLocalChanges, IProgressMonitor monitor) throws CoreException
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.
diffs
- the differences to be mergedignoreLocalChanges
- ignore any local changes when performing the merge.monitor
- a progress monitorMergeStatus.CONFLICTS
indicates that the file
contain non-mergable conflicts and must be merged manually.CoreException
- if an error occursvoid reject(IDiff diff, IProgressMonitor monitor) throws CoreException
diff
- the diffmonitor
- a progress monitorCoreException
void reject(IDiff[] diffs, IProgressMonitor monitor) throws CoreException
reject(IDiff, IProgressMonitor)
for
each diff.diffs
- the diffsmonitor
- a progress monitorCoreException
void run(IWorkspaceRunnable runnable, ISchedulingRule rule, int flags, IProgressMonitor monitor) throws CoreException
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.runnable
- a workspace runnablerule
- a scheduling rule to be obtained while the runnable is runflags
- flags indicating when updates occur (either
IResource.NONE
or
IWorkspace.AVOID_UPDATE
.monitor
- a progress monitorCoreException
- if an error occursISchedulingRule getMergeRule(IDiff diff)
markAsMerged(IDiff, boolean, IProgressMonitor)
and reject(IDiff, IProgressMonitor)
.diff
- the diff to be mergedISchedulingRule getMergeRule(IDiff[] diffs)
markAsMerged(IDiff[], boolean, IProgressMonitor)
and reject(IDiff[], IProgressMonitor)
.diffs
- the diffs being merged
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.