Package com.nomagic.magicdraw.merge

Class MergeUtil

java.lang.Object

com.nomagic.magicdraw.merge.MergeUtil

@OpenApiAll
public final class MergeUtil
extends java.lang.Object

Allows to use MagicDraw project merge to compare projects (find project differences) and merge projects. See Open API manual for the usage details.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MergeUtil.ConflictResolution	Conflict resolution for 3-way merge.
static class	MergeUtil.Optimization	Performance/memory usage optimization option.

Field Summary

Fields

Modifier and Type	Field	Description
private static com.nomagic.magicdraw.merge.CompositeIDSupport	compositeIDSupport

Constructor Summary

Constructors

Constructor	Description
MergeUtil()

Method Summary

Modifier and Type	Method	Description
static void	acceptChanges(java.util.Set<Change> preferredChanges, java.util.Set<Change> changes)	Accept given changes.
static boolean	applyChanges(ProjectDifference difference, ErrorHandler<java.lang.Exception> errorHandler)	Apply project difference changes.
static void	callInEsiIDSupport(java.lang.Runnable runnable)	Executes runnable where getID(BaseElement) uses twc server element id when comparing elements.
static ProjectDifference	compareProjects(Project project, ProjectDescriptor baseProjectDescriptor, ErrorHandler<java.lang.Exception> errorHandler, MergeUtil.Optimization optimization)	Compare projects.
static ProjectDescriptor	createRemoteAncestorDescriptorForMerge(Project targetProject, long mergeFrom, boolean lock)	Creates remote ancestor descriptor for merge.
static java.util.Collection<java.lang.String>	getAllIDS(Project ancestorProject)
static java.util.Set<Change>	getConflictingChanges(java.util.Set<Change> changes)	Filter only changes that has conflicts.
static ProjectDifference	getDifference(Project targetProject, ProjectDescriptor source, ProjectDescriptor ancestor, ErrorHandler<java.lang.Exception> errorHandler, MergeUtil.Optimization optimization)	Discover project difference.
static ProjectDifference	getDifference(Project targetProject, ProjectDescriptor source, ProjectDescriptor ancestor, ErrorHandler<java.lang.Exception> errorHandler, MergeUtil.Optimization optimization, java.util.Set<ModuleInfo> modules)	Discover project difference.
static BaseElement	getElementByID(Project project, java.lang.String id)	Return element from project with given simple or derived id.
static java.lang.String	getID(BaseElement be)
private static java.lang.String	getModelObjectID(ModelObject modelObject)
static boolean	merge(Project targetProject, ProjectDescriptor source, ProjectDescriptor ancestor, MergeUtil.ConflictResolution conflictResolution, ErrorHandler<java.lang.Exception> errorHandler, MergeUtil.Optimization optimization)	Merge projects.
static void	registerCreatedElement(java.lang.String compositeID, ModelObject element)	Register created element by composite id.
static void	resetCompositeIDSupport()	Reset known composite id support.
static void	resetCompositeIDSupportCreatedElements()	Reset known created elements.
static void	restore(ProjectDifference difference)	Dispose project difference.
static void	setChangeState(Change change, ChangeState state)	Set change state.
static void	showDifferenceGUI(ProjectDifference projectDifference)	Show project difference GUI.
static boolean	showMergeGUI(ProjectDifference projectDifference)	Show merge GUI.

Methods inherited from class java.lang.Object

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

Field Detail

compositeIDSupport

private static volatile com.nomagic.magicdraw.merge.CompositeIDSupport compositeIDSupport

Constructor Detail

MergeUtil

public MergeUtil()

Method Detail

compareProjects

@CheckForNull
public static ProjectDifference compareProjects(@Nonnull
                                                Project project,
                                                @Nonnull
                                                ProjectDescriptor baseProjectDescriptor,
                                                @Nonnull
                                                ErrorHandler<java.lang.Exception> errorHandler,
                                                @Nonnull
                                                MergeUtil.Optimization optimization)
                                         throws java.lang.IllegalStateException

Compare projects. On success project difference is returned and the base project is active project.

Parameters:

project - target project.

baseProjectDescriptor - source project descriptor.

errorHandler - invoked if error occurs. Allows to perform custom action.

optimization - optimization option.

Returns:

project difference.

Throws:

java.lang.IllegalStateException - if merge is not available

getDifference

@CheckForNull
public static ProjectDifference getDifference(@Nonnull
                                              Project targetProject,
                                              @Nonnull
                                              ProjectDescriptor source,
                                              @CheckForNull
                                              ProjectDescriptor ancestor,
                                              @Nonnull
                                              ErrorHandler<java.lang.Exception> errorHandler,
                                              @Nonnull
                                              MergeUtil.Optimization optimization)
                                       throws java.lang.IllegalStateException

Discover project difference. On success project difference is returned and ancestor project is active project.

Parameters:

targetProject - target project.

source - source project descriptor.

ancestor - ancestor project descriptor. Used only for 3-way merge, null for 2-way merge.

errorHandler - invoked if error occurs. Allows to perform custom action.

optimization - optimization option.

Returns:

project difference.

Throws:

java.lang.IllegalStateException - if merge is not available

getDifference

@CheckForNull
public static ProjectDifference getDifference(@Nonnull
                                              Project targetProject,
                                              @Nonnull
                                              ProjectDescriptor source,
                                              @CheckForNull
                                              ProjectDescriptor ancestor,
                                              @Nonnull
                                              ErrorHandler<java.lang.Exception> errorHandler,
                                              @Nonnull
                                              MergeUtil.Optimization optimization,
                                              @CheckForNull
                                              java.util.Set<ModuleInfo> modules)
                                       throws java.lang.IllegalStateException

Discover project difference. On success project difference is returned and ancestor project is active project.

Parameters:

targetProject - target project.

source - source project descriptor.

ancestor - ancestor project descriptor. Used only for 3-way merge, null for 2-way merge.

errorHandler - invoked if error occurs. Allows to perform custom action.

optimization - optimization option.

modules - request modules for read-write merge mode. Restriction/constraints apply for read-write module merge mode. Invoke ProjectDifference.getRejectedModules() to find out which modules did not qualify for read-write merge mode.

Returns:

project difference.

Throws:

java.lang.IllegalStateException - if merge is not available

acceptChanges

public static void acceptChanges(@Nonnull
                                 java.util.Set<Change> preferredChanges,
                                 @Nonnull
                                 java.util.Set<Change> changes)
                          throws java.lang.IllegalStateException

Accept given changes. If change from changes conflicts with change from preferredChanges, it is rejected. The result is - all preferredChanges are accepted, and only not conflicting changes are accepted.

Parameters:

preferredChanges - accept all these changes.

changes - accept only not conflicting changes.

Throws:

java.lang.IllegalStateException - if merge is not available

restore

public static void restore(@Nonnull
                           ProjectDifference difference)

Dispose project difference.

Parameters:

difference - project difference.

showMergeGUI

public static boolean showMergeGUI(ProjectDifference projectDifference)
                            throws java.lang.IllegalStateException

Show merge GUI.

Parameters:

projectDifference - project difference.

Returns:

true proceed merging, false - cancel merging.

Throws:

java.lang.IllegalStateException - if merge is not available

applyChanges

public static boolean applyChanges(@Nonnull
                                   ProjectDifference difference,
                                   @Nonnull
                                   ErrorHandler<java.lang.Exception> errorHandler)
                            throws java.lang.IllegalStateException

Apply project difference changes.

Parameters:

difference - project difference.

errorHandler - invoked if error occurs.

Returns:

true if changes applied, otherwise - false.

Throws:

java.lang.IllegalStateException - if merge is not available, if changes applied on not latest teamwork project version, or trying to merge local project with teamwork project.

getConflictingChanges

public static java.util.Set<Change> getConflictingChanges(@Nonnull
                                                          java.util.Set<Change> changes)

Filter only changes that has conflicts.

Parameters:

changes - changes to filter.

Returns:

conflicting changes.

setChangeState

public static void setChangeState(@Nonnull
                                  Change change,
                                  @Nonnull
                                  ChangeState state)

Set change state. Dependent, required and conflicting changes states are also modified (if modification is required).

Parameters:

change - change to modify state.

state - new change state.

merge

public static boolean merge(@Nonnull
                            Project targetProject,
                            @Nonnull
                            ProjectDescriptor source,
                            @CheckForNull
                            ProjectDescriptor ancestor,
                            @CheckForNull
                            MergeUtil.ConflictResolution conflictResolution,
                            @Nonnull
                            ErrorHandler<java.lang.Exception> errorHandler,
                            @Nonnull
                            MergeUtil.Optimization optimization)
                     throws java.lang.IllegalStateException

Merge projects.

Parameters:

targetProject - target project.

source - source project descriptor.

ancestor - ancestor project descriptor. Pass value only for 3-way merge (null for 2-way merge).

conflictResolution - define conflict resolution. Used only in 3-way merge. null is treated as MergeUtil.ConflictResolution.TARGET_PREFERRED.

errorHandler - invoked if error occurs. Allows to perform custom action.

optimization - optimization option.

Returns:

true if project merged, otherwise false.

Throws:

java.lang.IllegalStateException - if merge is not available, if changes applied on not latest teamwork project version, or trying to merge local project with teamwork project.

showDifferenceGUI

public static void showDifferenceGUI(ProjectDifference projectDifference)
                              throws java.lang.IllegalStateException

Show project difference GUI.

Parameters:

projectDifference - project difference.

Throws:

java.lang.IllegalStateException - if diff is not available

getID

public static java.lang.String getID(BaseElement be)

getModelObjectID

private static java.lang.String getModelObjectID(@Nonnull
                                                 ModelObject modelObject)

getElementByID

@CheckForNull
public static BaseElement getElementByID(Project project,
                                         java.lang.String id)

Return element from project with given simple or derived id. For esi project checks project for found element - if there are more than one project with same local id.

Parameters:

project - project

id - simple or derived id

Returns:

element or null

getAllIDS

@Nonnull
public static java.util.Collection<java.lang.String> getAllIDS(Project ancestorProject)

resetCompositeIDSupportCreatedElements

public static void resetCompositeIDSupportCreatedElements()

Reset known created elements.

See Also:

registerCreatedElement(String, ModelObject)

resetCompositeIDSupport

public static void resetCompositeIDSupport()

Reset known composite id support.

callInEsiIDSupport

public static void callInEsiIDSupport(java.lang.Runnable runnable)

Executes runnable where getID(BaseElement) uses twc server element id when comparing elements.

Parameters:

runnable - runnable to execute

registerCreatedElement

public static void registerCreatedElement(java.lang.String compositeID,
                                          ModelObject element)

Register created element by composite id. Composite id may contain information that element is in module, but in ancestor such module is still not used. When element is registered it can be found by provided composite id.

Parameters:

compositeID - composite id.

element - created element.

createRemoteAncestorDescriptorForMerge

@CheckForNull
public static ProjectDescriptor createRemoteAncestorDescriptorForMerge(Project targetProject,
                                                                       long mergeFrom,
                                                                       boolean lock)

Creates remote ancestor descriptor for merge.

Parameters:

targetProject - target project.

mergeFrom - source version.

lock - should decomposition lock be taken.

Returns:

created descriptor or null.