com.starteam.viewcomparemerge
Class ItemDifference

java.lang.Object
  com.starteam.viewcomparemerge.ItemDifference

public final class ItemDifference
extends java.lang.Object

Represents the difference between a given item from the source view and the corresponding item in the target view.

See Also:

Session.getDifferences()

Method Summary

MergeAction	getAction() Gets the action that will be performed at commit time to merge this difference from the source to the target.
ItemDifference[]	getAffectedDifferences(MergeAction newAction) Determines which differences would be affected if the merge action for this difference were changed to the given one.
MergeAction	getDefaultAction() Gets the default action recommended when merging this difference to the target view.
java.lang.String	getDescription() Gets a user-friendly description of this difference.
DifferenceType	getDifferenceType() Gets the difference type associated with this difference.
MergeAction[]	getLegalActions() Gets the list of merge actions that are legal for this difference.
java.io.File	getMergedFileContent() Gets the path to a file within this session's working vault where the merged file content for this difference resides.
File	getMergedFileContentItem() Gets the StarTeam file revision whose content was used as the merged file content for this difference, or null if the merged content was not set via setMergedFileContentItem.
Item	getMergedItem() Gets an item that closely approximates the state the target item after the merge, if the session were to be committed in its current state.
Session	getSession() Gets the VCM session to which this difference belongs.
Item	getSourceAncestor() Gets the item from the source item's history that was used to determine whether the source item has changed or moved since the last merge operation.
Item	getSourceItem() Gets the source item associated with this difference.
Item	getSourceItemForCompare() Gets the source item associated with this difference May be null for some difference types (for example, "New in Target").
Item	getTargetAncestor() Gets the item from the target item's history that was used to determine whether the target item has changed or moved since the last merge operation.
Item	getTargetItem() Gets the target item associated with this difference.
Item	getTargetItemForCompare() Gets the target item associated with this difference May be null for some difference types (for example, "New in source").
Item.Type	getType() Gets the item type of the source and target items in this difference.
boolean	isCommitted() Determines whether or not this difference has been commited.
boolean	isConflictDetected() Determines whether or not this difference represents a merge conflict.
boolean	isFileCheckin() Determines whether or not applying the current action at commit time would result in a file checkin.
boolean	isFileMerge() Determines whether or not this difference represents a file whose content has changed in both the source and target in such a way as to create a merge condition.
boolean	isLegalAction(MergeAction action) Determines whether or not the given action is a legal action for this item difference.
boolean	isNonTipReverseShare() Determines whether or not committing this difference resulted in a reverse share from a non-tip revision.
boolean	isPropertyMerge() Determines whether or not there is at least one property whose value has changed in both the source item and target item in such a way as to create a merge condition.
boolean	isPropertyMergeFor(Property property) Determines whether or not the given property has changed in both the source item and target item in such a way as to create a merge condition.
boolean	isUnresolved() Determines whether or not this difference has an unresolved merge condition.
boolean	isUnresolvedFileMerge() Determines whether or not this difference represents a file whose content has changed in both the source and target in such a way as to create a merge condition, and that merge condition has not yet been resolved.
boolean	isUnresolvedPropertyMerge() Determines whether or not there is at least one property whose value has changed in both the source item and target item in such a way as to create a merge condition, and that merge condition has not yet been resolved.
boolean	isUnresolvedPropertyMergeFor(Property property) Determines whether or not the given property has changed in both the source item and target item in such a way as to create a merge condition, and that merge condition has not yet been resolved.
void	setAction(MergeAction newAction) Sets the action that will be performed at commit time to merge this difference from the source to the target.
void	setMergedFileContent(java.io.File mergeResult) Sets the merged file content for this difference.
void	setMergedFileContentItem(File starTeamFile) Similar to setMergedFileContent, except that the merged file content is taken from the given StarTeam file revision.
java.lang.Object	setMergedPropertyValue(Property property, java.lang.Object value) Sets the value of the specified property on the merged item.
java.lang.String	toString() Gets a string representation of this difference.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getType

public Item.Type getType()

Gets the item type of the source and target items in this difference.

Returns:

The item type of the source and target items in this difference.

getMergedItem

public Item getMergedItem()

Gets an item that closely approximates the state the target item after the merge, if the session were to be committed in its current state.

The same merged item also appears in the merge preview.

Returns:

An item that closely approximates the state the target item after the merge, if the session were to be committed in its current state.

See Also:

Session.getMergePreview()

getSession

public Session getSession()

Gets the VCM session to which this difference belongs.

Returns:

The VCM session to which this difference belongs.

getDescription

public java.lang.String getDescription()

Gets a user-friendly description of this difference.

Returns:

A user-friendly description of this difference.

toString

public java.lang.String toString()

Gets a string representation of this difference.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this difference.

isLegalAction

public boolean isLegalAction(MergeAction action)

Determines whether or not the given action is a legal action for this item difference.

Parameters:

action - The MergeAction to be tested.

Returns:

True if the action is legal for this item difference; false otherwise.

See Also:

DifferenceType.isLegalAction(MergeAction), ItemDifference.getLegalActions()

getDefaultAction

public MergeAction getDefaultAction()

Gets the default action recommended when merging this difference to the target view.

The action associated with a given difference may be overridden, and therefore may differ from the default action.

Returns:

The default action recommended when merging this difference to the target view.

See Also:

ItemDifference.setAction(com.starteam.viewcomparemerge.MergeAction), ItemDifference.isLegalAction(MergeAction)

getLegalActions

public MergeAction[] getLegalActions()

Gets the list of merge actions that are legal for this difference.

Returns:

The list of merge actions that are legal for this difference.

See Also:

ItemDifference.setAction(com.starteam.viewcomparemerge.MergeAction), DifferenceType.getLegalActions(), ItemDifference.isLegalAction(MergeAction)

getAffectedDifferences

public ItemDifference[] getAffectedDifferences(MergeAction newAction)

Determines which differences would be affected if the merge action for this difference were changed to the given one.

For example, consider a folder that is "New in source". Changing the action from reverse share to ignore would also affect the differences for any "New in source" files in that folder. (If the folder isn't shared, its children won't be either.)

This method does not actually change the actions of any differences; the changes would not occur unless setAction were called.

Parameters:

newAction - the action to test against

Returns:

A list of the effected differences. The list is empty (zero length) if the action isn't changing, or isn't legal for this difference.

See Also:

ItemDifference.setAction(com.starteam.viewcomparemerge.MergeAction), ItemDifference.getLegalActions()

getAction

public MergeAction getAction()

Gets the action that will be performed at commit time to merge this difference from the source to the target.

Returns:

The action that will be performed at commit time.

See Also:

ItemDifference.setAction(com.starteam.viewcomparemerge.MergeAction), ItemDifference.getDefaultAction()

setAction

public void setAction(MergeAction newAction)

Sets the action that will be performed at commit time to merge this difference from the source to the target.

The new action overrides the default. It must be one of the actions that is legal for this difference.

Parameters:

newAction - The action that will be performed at commit time.

See Also:

ItemDifference.getAction(), ItemDifference.getLegalActions(), ItemDifference.getDefaultAction()

isConflictDetected

public boolean isConflictDetected()

Determines whether or not this difference represents a merge conflict. The conflict may or may not have already been resolved.

Returns:

true if this difference represents a merge conflict, and false otherwise.

See Also:

ItemDifference.isPropertyMerge(), ItemDifference.isFileMerge(), ItemDifference.isUnresolved()

isFileMerge

public boolean isFileMerge()

Determines whether or not this difference represents a file whose content has changed in both the source and target in such a way as to create a merge condition. Note that the merge condition may or may not have been resolved.

Returns:

true if this difference represents an file merge condition.

See Also:

ItemDifference.isUnresolvedFileMerge()

isFileCheckin

public boolean isFileCheckin()

Determines whether or not applying the current action at commit time would result in a file checkin.

Returns:

true if applying the current action would result in a file checkin.

isUnresolvedFileMerge

public boolean isUnresolvedFileMerge()

Determines whether or not this difference represents a file whose content has changed in both the source and target in such a way as to create a merge condition, and that merge condition has not yet been resolved.

Returns:

true if this difference represents an unresolved file merge condition.

See Also:

ItemDifference.isFileMerge()

isNonTipReverseShare

public boolean isNonTipReverseShare()

Determines whether or not committing this difference resulted in a reverse share from a non-tip revision.

When the source item being reverse shared is not the tip revision of the item, StarTeam compensates by:

1. reverse sharing the tip revision;

2. creating a new revision in the target view that has the effect of rolling back the item properties and/or file content to the desired non-tip revision;

3. forcing the item to branch in the source view, so that a subsequent rebase will cause a merge condition.

This isNonTipReverseShare flag is set at commit time, and is always false prior to the commit.

Returns:

true if committing this difference resulted in a reverse share from a non-tip revision.

See Also:

MergeAction.REVERSE_SHARE, Item.reverseShareTo(Folder)

getMergedFileContent

public java.io.File getMergedFileContent()

Gets the path to a file within this session's working vault where the merged file content for this difference resides.

The difference must be a file difference with a file merge condition that has already been resolved.

Returns:

The path to the file where the merged file content for this difference resides.

See Also:

ItemDifference.isFileMerge(), ItemDifference.isUnresolvedFileMerge(), ItemDifference.setMergedFileContent(java.io.File)

setMergedFileContent

public void setMergedFileContent(java.io.File mergeResult)

Sets the merged file content for this difference. This is the content that will be checked into the target view at commit time.

The difference must be one with a file merge condition. The provided file content is copied into the session's working vault, and the file merge condition is marked resolved.

An alternate way to specify the merged file content for a difference is to check in the new content through the merge preview. For example:

 // The merged item is accessible through the ItemDifference
 // and through the merge preview; they are physically the same.
 Item item = diff.getMergedItem();
 
 // Checking in a new file revision also resolves the conflict.
 View preview = session.getMergePreview();
 CheckinManager mgr = preview.createCheckinManager();
 mgr.checkin((File) item, path);
 

Parameters:

mergeResult - The merged file content for this difference.

See Also:

ItemDifference.isFileMerge(), ItemDifference.getMergedFileContent(), Session.getMergePreview(), ItemDifference.setMergedFileContentItem(com.starteam.File)

setMergedFileContentItem

public void setMergedFileContentItem(File starTeamFile)

Similar to setMergedFileContent, except that the merged file content is taken from the given StarTeam file revision.

Parameters:

starTeamFile - StarTeam file revision whose content is used as the merged file content for this difference.

See Also:

ItemDifference.setMergedFileContent(java.io.File), ItemDifference.isFileMerge(), ItemDifference.getMergedFileContentItem()

getMergedFileContentItem

public File getMergedFileContentItem()

Gets the StarTeam file revision whose content was used as the merged file content for this difference, or null if the merged content was not set via setMergedFileContentItem.

Returns:

The StarTeam file revision whose content was used as the merged file content for this difference.

See Also:

ItemDifference.setMergedFileContentItem(com.starteam.File)

setMergedPropertyValue

public java.lang.Object setMergedPropertyValue(Property property,
                                               java.lang.Object value)

Sets the value of the specified property on the merged item. This is the property value that will be saved to the target item at commit time.

Setting the property value resolves any outstanding merge conflict associated with this property.

Alternatively, an application can change the property value using the normal setValue and update methods available on the merged item.

Parameters:

property - The property whose value is to be changed.

value - The new property value.

Returns:

The previous value of the property.

See Also:

ItemDifference.isPropertyMerge(), ItemDifference.isPropertyMergeFor(Property), ItemDifference.getMergedItem(), TypedResource.setValue(Property,Object), ViewMember.update()

getSourceItem

public Item getSourceItem()

Gets the source item associated with this difference. May be null for some difference types (for example, "New in target").

Returns:

The source item associated with this difference, or null.

See Also:

ItemDifference.getTargetItem(), ItemDifference.getMergedItem()

getSourceItemForCompare

public Item getSourceItemForCompare()

Gets the source item associated with this difference May be null for some difference types (for example, "New in Target"). Prior to the commit, this item is the same as the source item After the commit, this item represents the source item prior to the commit

Returns:

The source item associated with this difference, or null

See Also:

ItemDifference.getSourceItem()

getSourceAncestor

public Item getSourceAncestor()

Gets the item from the source item's history that was used to determine whether the source item has changed or moved since the last merge operation.

Returns:

The item from the source item's history that was used to determine whether the source item has changed or moved since the last merge operation.

See Also:

Options.getIgnoreMergePoints()

getTargetItem

public Item getTargetItem()

Gets the target item associated with this difference. May be null for some difference types (for example, "New in source").

Returns:

The target item associated with this difference, or null.

See Also:

ItemDifference.getSourceItem(), ItemDifference.getMergedItem()

getTargetItemForCompare

public Item getTargetItemForCompare()

Gets the target item associated with this difference May be null for some difference types (for example, "New in source"). Prior to the commit, this item is the same as the target item After the commit, this item represents the target item prior to the commit

Returns:

The target item associated with this difference, or null

See Also:

ItemDifference.getTargetItem()

getTargetAncestor

public Item getTargetAncestor()

Gets the item from the target item's history that was used to determine whether the target item has changed or moved since the last merge operation.

Returns:

The item from the target item's history that was used to determine whether the target item has changed or moved since the last merge operation.

See Also:

Options.getIgnoreMergePoints()

isUnresolved

public boolean isUnresolved()

Determines whether or not this difference has an unresolved merge condition.

Returns:

true if this difference has an unresolved merge condition, and false otherwise.

See Also:

ItemDifference.isConflictDetected(), ItemDifference.isUnresolvedFileMerge(), ItemDifference.isUnresolvedPropertyMerge(), ItemDifference.isUnresolvedPropertyMergeFor(Property)

isPropertyMerge

public boolean isPropertyMerge()

Determines whether or not there is at least one property whose value has changed in both the source item and target item in such a way as to create a merge condition. Note that the merge condition may or may not have been resolved.

Returns:

true if there is at least one item property requiring a merge, whether or not the merge condition has already been resolved.

See Also:

ItemDifference.isUnresolvedPropertyMerge(), ItemDifference.isPropertyMergeFor(Property), ItemDifference.setMergedPropertyValue(com.starteam.Property, java.lang.Object)

isUnresolvedPropertyMerge

public boolean isUnresolvedPropertyMerge()

Determines whether or not there is at least one property whose value has changed in both the source item and target item in such a way as to create a merge condition, and that merge condition has not yet been resolved.

Returns:

true if there is at least one item property with a merge condition that has not yet been resolved.

See Also:

ItemDifference.isPropertyMerge(), ItemDifference.isUnresolvedPropertyMergeFor(Property), ItemDifference.setMergedPropertyValue(com.starteam.Property, java.lang.Object)

isPropertyMergeFor

public boolean isPropertyMergeFor(Property property)

Determines whether or not the given property has changed in both the source item and target item in such a way as to create a merge condition. Note that the merge condition may or may not have been resolved.

Parameters:

property - An item property.

Returns:

true if the given item property requires a merge, whether or not the merge condition has already been resolved.

See Also:

ItemDifference.isPropertyMerge(), ItemDifference.isUnresolvedPropertyMergeFor(Property), ItemDifference.setMergedPropertyValue(com.starteam.Property, java.lang.Object)

isUnresolvedPropertyMergeFor

public boolean isUnresolvedPropertyMergeFor(Property property)

Determines whether or not the given property has changed in both the source item and target item in such a way as to create a merge condition, and that merge condition has not yet been resolved.

Parameters:

property - An item property.

Returns:

true if the given item property has a merge condition that has not yet been resolved.

See Also:

ItemDifference.isUnresolvedPropertyMerge(), ItemDifference.isPropertyMergeFor(Property), ItemDifference.setMergedPropertyValue(com.starteam.Property, java.lang.Object)

isCommitted

public boolean isCommitted()

Determines whether or not this difference has been commited.

Note that if the session was committed as an atomic transaction, then all differences are committed together. However, on a server that does not support atomic transactions, the session may be partially committed. In this case, some differences may report that they have been committed, while others may not.

Returns:

true if this difference has been committed.

getDifferenceType

public DifferenceType getDifferenceType()

Gets the difference type associated with this difference.

Returns:

The difference type associated with this difference.