Eclipse Plug-in Developer Guide (Galileo) - MergeContext (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.team.core.mapping.provider
Class MergeContext


java.lang.Object
  

org.eclipse.core.runtime.PlatformObject
      

org.eclipse.team.core.mapping.provider.SynchronizationContext
          
org.eclipse.team.core.mapping.provider.MergeContext

All Implemented Interfaces:: IAdaptable, IMergeContext, ISynchronizationContext

Direct Known Subclasses:: SubscriberMergeContext

public abstract class MergeContext
extends SynchronizationContext
implements IMergeContext
extends SynchronizationContext
implements IMergeContext

Provides the context for an IResourceMappingMerger. It provides access to the ancestor and remote resource mapping contexts so that resource mapping mergers can attempt head-less auto-merges. The ancestor context is only required for merges while the remote is required for both merge and replace.

Since:: 3.2
See Also:: IResourceMappingMerger

Field Summary

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

THREE_WAY, TWO_WAY

Constructor Summary

protected MergeContext ( ISynchronizationScopeManager manager, int type, IResourceDiffTree deltaTree)
          Create a merge context.

Method Summary

protected void ensureParentsExist ( IResource resource, IProgressMonitor monitor)
          Ensure that the parent folders of the given resource exist.

Object getAdapter ( Class adapter)
          Returns an object which is an instance of the given class associated with this object.

ISchedulingRule getMergeRule ( IDiff diff)
          Default implementation that returns the resource itself.

ISchedulingRule getMergeRule ( IDiff[] deltas)
          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).

protected abstract void makeInSync ( IDiff diff, IProgressMonitor monitor)
          Method that is invoked from performReplace(IDiff, IProgressMonitor) after the local has been changed to match the remote.

void markAsMerged ( IDiff[] nodes, boolean inSyncHint, IProgressMonitor monitor)
          Mark the files associated with the given diff nodes as being merged.

IStatus merge ( IDiff[] deltas, boolean force, 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.

protected void performReplace ( IDiff diff, IProgressMonitor monitor)
          Make the local state of the resource associated with the given diff match that of the remote.

protected IStatus performThreeWayMerge ( IThreeWayDiff diff, IProgressMonitor monitor)
          Perform a three-way merge on the given three-way diff that contains a content conflict.

void reject ( IDiff[] diffs, IProgressMonitor monitor)
          Reject the changes associated with the given diffs.

void run ( IWorkspaceRunnable runnable, ISchedulingRule rule, int flags, IProgressMonitor monitor)
          Default implementation of run that invokes the corresponding run on IWorkspace.

Methods inherited from class org.eclipse.team.core.mapping.provider. SynchronizationContext

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

Methods inherited from class java.lang. Object

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

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

markAsMerged, reject

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

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

Constructor Detail

MergeContext

protected MergeContext(
ISynchronizationScopeManager manager,
                       int type,
                       
IResourceDiffTree deltaTree)

Create a merge context.

Parameters:: type -

Method Detail

reject

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

Description copied from interface: IMergeContext

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

Specified by:: reject in interface IMergeContext

Parameters:: diffs - the diffs; monitor - a progress monitor
Throws:: CoreException

markAsMerged

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

Description copied from interface: IMergeContext

Mark the files associated with the given diff nodes as being merged. This method is equivalent to calling IMergeContext.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 IMergeContext.run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor) method. The rule for he method will be obtained using IMergeContext.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.

Specified by:: markAsMerged in interface IMergeContext

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

public 
IStatus merge(
IDiff[] deltas,
                     boolean force,
                     
IProgressMonitor monitor)
              throws 
CoreException

Description copied from interface: IMergeContext

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

Specified by:: merge in interface IMergeContext

Parameters:: deltas - the differences to be merged; force - 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

merge

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

Description copied from interface: IMergeContext

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 IMergeContext.getMergeType() methods, clients can either accept changes using the IMergeContext.merge(IDiff[], boolean, IProgressMonitor) method or reject them using IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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 IMergeContext.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

Specified by:: merge in interface IMergeContext

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)

performThreeWayMerge

protected 
IStatus performThreeWayMerge(
IThreeWayDiff diff,
                                       
IProgressMonitor monitor)
                                throws 
CoreException

Perform a three-way merge on the given three-way diff that contains a content conflict. By default, this method makes use of IStorageMerger instances registered with the storageMergers extension point. Note that the ancestor of the given diff may be missing. Some IStorageMerger instances can still merge without an ancestor so we need to consult the appropriate merger to find out.

Parameters:: diff - the diff; monitor - a progress monitor
Returns:: a status indicating the results of the merge
Throws:: CoreException

performReplace

protected void performReplace(
IDiff diff,
                              
IProgressMonitor monitor)
                       throws 
CoreException

Make the local state of the resource associated with the given diff match that of the remote. This method is invoked by the merge(IDiff, boolean, IProgressMonitor) method. By default, it either overwrites the local contexts with the remote contents if both exist, deletes the local if the rmeote does not exists or addes the local if the local doesn't exist but the remote does. It then calls makeInSync(IDiff, IProgressMonitor) to give subclasses a change to make the file associated with the diff in-sync.

Parameters:: diff - the diff whose local is to be replaced; monitor - a progrss monitor
Throws:: CoreException

makeInSync

protected abstract void makeInSync(
IDiff diff,
                                   
IProgressMonitor monitor)
                            throws 
CoreException

Method that is invoked from performReplace(IDiff, IProgressMonitor) after the local has been changed to match the remote. Subclasses may override performReplace(IDiff, IProgressMonitor) or this method in order to properly reconcile the synchronization state. This method is also invoked from merge(IDiff, boolean, IProgressMonitor) if deletion conflicts are encountered. It can also be invoked from that same method if a folder is created due to an incoming folder addition.

Parameters:: diff - the diff whose local is now in-sync; monitor - a progress monitor
Throws:: CoreException

ensureParentsExist

protected void ensureParentsExist(
IResource resource,
                                  
IProgressMonitor monitor)
                           throws 
CoreException

Ensure that the parent folders of the given resource exist. This method is invoked from performReplace(IDiff, IProgressMonitor) for files that are being merged that do not exist locally. By default, this method creates the parents using IFolder.create(boolean, boolean, IProgressMonitor). Subclasses may override.

Parameters:: resource - a resource; monitor - a progress monitor
Throws:: CoreException - if an error occurs

run

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

Default implementation of run that invokes the corresponding run on IWorkspace.

Specified by:: run in interface IMergeContext

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
See Also:: IMergeContext.run(org.eclipse.core.resources.IWorkspaceRunnable, org.eclipse.core.runtime.jobs.ISchedulingRule, int, org.eclipse.core.runtime.IProgressMonitor)

getMergeRule

public 
ISchedulingRule getMergeRule(
IDiff diff)

Default implementation that returns the resource itself. Subclass should override to provide the appropriate rule.

Specified by:: getMergeRule in interface IMergeContext

Parameters:: diff - the diff to be merged
Returns:: the scheduling rule that is required to merge the resource of the given diff
See Also:: IMergeContext.getMergeRule(IDiff)

getMergeRule

public 
ISchedulingRule getMergeRule(
IDiff[] deltas)

Description copied from interface: IMergeContext

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 IMergeContext.markAsMerged(IDiff[], boolean, IProgressMonitor) and IMergeContext.reject(IDiff[], IProgressMonitor).

Specified by:: getMergeRule in interface IMergeContext

Parameters:: deltas - the diffs being merged
Returns:: the scheduling rule that is required to merge the resources of the given diffs

getMergeType

public int getMergeType()

Description copied from interface: IMergeContext

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.

Specified by:: getMergeType in interface IMergeContext

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

getAdapter

public 
Object getAdapter(
Class adapter)

Description copied from class: PlatformObject

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

This implementation of the method declared by IAdaptable passes the request along to the platform's adapter manager; roughly Platform.getAdapterManager().getAdapter(this, adapter). Subclasses may override this method (however, if they do so, they should invoke the method on their superclass to ensure that the Platform's adapter manager is consulted).

Specified by:: getAdapter in interface IAdaptable
Overrides:: getAdapter in class PlatformObject

Parameters:: adapter - the class to adapt to
Returns:: the adapted object or null
See Also:: IAdaptable.getAdapter(Class)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.team.core.mapping.provider Class MergeContext

MergeContext

reject

markAsMerged

merge

merge

performThreeWayMerge

performReplace

makeInSync

ensureParentsExist

run

getMergeRule

getMergeRule

getMergeType

getAdapter

org.eclipse.team.core.mapping.provider
Class MergeContext