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 and Description
static class	MergeUtil.ConflictResolution Conflict resolution for 3-way merge.
static class	MergeUtil.Optimization Performance/memory usage optimization option.

Constructor Summary

Constructors

Constructor and Description
MergeUtil()

Method Summary

Modifier and Type	Method and 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 ProjectDifference	compareProjects(Project project, ProjectDescriptor baseProjectDescriptor, ErrorHandler<java.lang.Exception> errorHandler, MergeUtil.Optimization optimization) Compare projects.
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<com.nomagic.magicdraw.diff.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)
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 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

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<com.nomagic.magicdraw.diff.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)

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)

resetCompositeIDSupport

public static void resetCompositeIDSupport()

Reset known created elements.

See Also:

registerCreatedElement(String, ModelObject)

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.