com.microsoft.tfs.core.clients.versioncontrol.engines
Class MergeEngine

java.lang.Object
  extended by com.microsoft.tfs.core.clients.versioncontrol.engines.MergeEngine

public final class MergeEngine
extends java.lang.Object

Handles high-level merge tasks for external tool and custom merge processes. A MergeEngine is designed to be used by Workspace, and is not intended to be used by other clients.

Thread-safety:
thread-safe

Constructor Summary
MergeEngine(Workspace workspace, VersionControlClient client)
          No merge toolset will be available in this MergeEngine, so external merge operations will fail.
MergeEngine(Workspace workspace, VersionControlClient client, ExternalToolset mergeToolset)
          Creates a MergeEngine with the given workspace, client, and merge toolset (which will be used to select a tool when external merges require them).
 
Method Summary
 java.lang.String beginCustomMerge(Conflict conflict, ThreeWayMerge threeWayMerge)
          Sets up a merge for the given conflict so that callers may perform a custom merge process, returning the merge output file that should be written to to complete the merge.
 com.microsoft.tfs.util.process.ProcessRunner beginExternalMerge(Conflict conflict, ThreeWayMerge threeWayMerge, com.microsoft.tfs.util.process.ProcessFinishedHandler finishedHandler, java.io.OutputStream capturedStandardOutput, java.io.OutputStream capturedStandardError)
          Begins an external content merge for the given conflict.
 void countContentConflicts(Conflict conflict)
          Counts the potential content merge conflicts for the given conflict and stores them in the conflict's merge summary.
 void endCustomMerge(java.lang.String mergeFilename, Conflict conflict, ThreeWayMerge threeWayMerge, boolean success)
          Ends an custom content merge for the given conflict that was begun with beginCustomMerge(Conflict, ThreeWayMerge).
 boolean endExternalMerge(com.microsoft.tfs.util.process.ProcessRunner runner, Conflict conflict, ThreeWayMerge threeWayMerge)
          Ends an external content merge for the given conflict that was begun with beginExternalMerge(Conflict, ThreeWayMerge, ProcessFinishedHandler, OutputStream, OutputStream) .
 java.lang.String getTempFilePath(java.lang.String fileName)
          Creates a new temp directory and returns the full path to the given file inside it (does not create the file).
 boolean mergeContent(Conflict conflict, boolean onlyCountConflicts, com.microsoft.tfs.util.process.ProcessFinishedHandler finishedHandler, java.io.OutputStream capturedStandardOutput, java.io.OutputStream capturedStandardError)
          Merges content for the given conflict.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MergeEngine

public MergeEngine(Workspace workspace,
                   VersionControlClient client)
No merge toolset will be available in this MergeEngine, so external merge operations will fail.

Equivalent To:
MergeEngine(workspace, client, null)

MergeEngine

public MergeEngine(Workspace workspace,
                   VersionControlClient client,
                   ExternalToolset mergeToolset)
Creates a MergeEngine with the given workspace, client, and merge toolset (which will be used to select a tool when external merges require them).

Parameters:
workspace - the workspace where items are being merged (must not be null)
client - the version control client (must not be null)
mergeToolset - a set of tools to use for external merges (may be null but external merges will fail)
Method Detail

beginExternalMerge

public com.microsoft.tfs.util.process.ProcessRunner beginExternalMerge(Conflict conflict,
                                                                       ThreeWayMerge threeWayMerge,
                                                                       com.microsoft.tfs.util.process.ProcessFinishedHandler finishedHandler,
                                                                       java.io.OutputStream capturedStandardOutput,
                                                                       java.io.OutputStream capturedStandardError)
                                                                throws MergeToolNotConfiguredException,
                                                                       PreMergeFailedException,
                                                                       java.io.IOException,
                                                                       ExternalToolException
Begins an external content merge for the given conflict. The appropriate external merge tool will be invoked and a ProcessRunner that wraps it returned. This runner can be polled for the process state, or you can pass in a ProcessFinishedHandler and be notified as soon as the state changes.

This method is a core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
conflict - the conflict whose content should be merged (must not be null)
threeWayMerge - a newly constructed ThreeWayMerge to be used by this merge operation. (must not be null)
finishedHandler - an event handler whose methods are invoked when the process runner reaches one of its terminal states. The caller would normally implement the handler to call endExternalMerge(ProcessRunner, Conflict, ThreeWayMerge) when the runner reaches any terminal state. May be null if no state information is desired via the handler.
capturedStandardOutput - a stream to capture the text written by the child process to its standard output stream. Pass null if you don't want this output.

See the warning in ProcessRunner's Javadoc about deadlock.

capturedStandardError - a stream to capture the text written by the child process to its standard error stream. Pass null if you don't want this output.

See the warning in ProcessRunner's Javadoc about deadlock.

Returns:
the process runner that can be queried for information about the external merge tool process.
Throws:
MergeToolNotConfiguredException - if no configured merge tool exists for the given conflict. No external process was launched.
java.io.IOException - if an error occurred creating the merge output file before the merge tool was invoked. No external process was launched.
PreMergeFailedException - if the pre merge step failed for this conflict. No external process was launched.
ExternalToolException - if no merge tools are available, or if the configured merge command or arguments string caused a problem creating the merge tool.

endExternalMerge

public boolean endExternalMerge(com.microsoft.tfs.util.process.ProcessRunner runner,
                                Conflict conflict,
                                ThreeWayMerge threeWayMerge)
Ends an external content merge for the given conflict that was begun with beginExternalMerge(Conflict, ThreeWayMerge, ProcessFinishedHandler, OutputStream, OutputStream) .

This method is a core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
runner - the process runner created by beginExternalMerge(Conflict, ThreeWayMerge, ProcessFinishedHandler, OutputStream, OutputStream) . If this runner is not already finished, this method will wait until it finishes. (must not be null)
conflict - the Conflict that was passed to beginExternalMerge(Conflict, ThreeWayMerge, ProcessFinishedHandler, OutputStream, OutputStream) to start this merge. (must not be null)
threeWayMerge - the ThreeWayMerge that was passed to beginExternalMerge(Conflict, ThreeWayMerge, ProcessFinishedHandler, OutputStream, OutputStream) to start this merge. (must not be null)
Returns:
true if the external merge succeeded, false otherwise

beginCustomMerge

public java.lang.String beginCustomMerge(Conflict conflict,
                                         ThreeWayMerge threeWayMerge)
                                  throws PreMergeFailedException,
                                         java.io.IOException
Sets up a merge for the given conflict so that callers may perform a custom merge process, returning the merge output file that should be written to to complete the merge. Users should call endCustomMerge(String, Conflict, ThreeWayMerge, boolean) to complete the merge.

This method is a core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
conflict - the conflict whose content should be merged (must not be null)
threeWayMerge - a newly constructed ThreeWayMerge to be used by this merge operation. (must not be null)
Returns:
the filename that merged output should be written to
Throws:
java.io.IOException - if an error occurred creating the merge input or output files.
PreMergeFailedException - if the pre merge step failed for this conflict.

endCustomMerge

public void endCustomMerge(java.lang.String mergeFilename,
                           Conflict conflict,
                           ThreeWayMerge threeWayMerge,
                           boolean success)
Ends an custom content merge for the given conflict that was begun with beginCustomMerge(Conflict, ThreeWayMerge).

This method is a core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
mergeFilename - the merge output filename created by beginCustomMerge(Conflict, ThreeWayMerge) (must not be null).
conflict - the Conflict that was passed to beginCustomMerge(Conflict, ThreeWayMerge) to start this merge. (must not be null)
threeWayMerge - the ThreeWayMerge that was passed to beginCustomMerge(Conflict, ThreeWayMerge) to start this merge. (must not be null)
success - true if the custom merge was accepted, false if the merge failed

countContentConflicts

public void countContentConflicts(Conflict conflict)
Counts the potential content merge conflicts for the given conflict and stores them in the conflict's merge summary.

Parameters:
conflict - the conflict to count content conflicts for (must not be null)

mergeContent

public boolean mergeContent(Conflict conflict,
                            boolean onlyCountConflicts,
                            com.microsoft.tfs.util.process.ProcessFinishedHandler finishedHandler,
                            java.io.OutputStream capturedStandardOutput,
                            java.io.OutputStream capturedStandardError)
Merges content for the given conflict. Detects whether to use internal or external method. Both strategies may block a significant amount of time while the merge happens.

This method is a core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
conflict - the conflict whose content should be merged (must not be null)
onlyCountConflicts - if true, the pre merge completes but only the conflicts are counted, no merged file result will be present (check the conflict object's MergeSummary for the conflict count). If false, the merge is completed, and the output file is created. This parameter is ignored when the external merge tool is used.
finishedHandler - an event handler whose methods are invoked when the process runner used to run external merge tools reaches one of its terminal states. May be null if no state information is desired via the handler.
capturedStandardOutput - a stream to capture the text written by the child process to its standard output stream. Pass null if you don't want this output.

See the warning in ProcessRunner's Javadoc about deadlock.

capturedStandardError - a stream to capture the text written by the child process to its standard error stream. Pass null if you don't want this output.

See the warning in ProcessRunner's Javadoc about deadlock.

Returns:
true if the merge was successful (the merge process was run), false if it was not (the merge process could not be started or there was a non-content-conflict error).

getTempFilePath

public java.lang.String getTempFilePath(java.lang.String fileName)
Creates a new temp directory and returns the full path to the given file inside it (does not create the file).

Parameters:
fileName - the file name (not absolute path) to append to the newly created temp directory (must not be null or empty)
Returns:
the full path to the temp file (which is not created, but parent directories are)


© 2015 Microsoft. All rights reserved.