com.starbase.starteam.viewcomparemerge
Class Session

java.lang.Object
  |
  +--com.starbase.starteam.viewcomparemerge.Session

public final class Session

extends java.lang.Object

A view compare/merge (VCM) session.

Each VCM session has associated source view and target views. Comparing the two generates a set of differences. For each difference, you can detect conflicts, override default actions, and so on.

Conflicts may be resolved by merging item properties or file content. Alternatively, you can set property values or checkin new file revisions via the merge preview, which shows what the target view would look like were the session to be committed in its current state.

When ready, you can commit the changes, which updates the target view.

For general information on using the VCM APIs, see com.starbase.startem.viewcomparemerge.

Constructor Summary

Session(MergeType mergeType, View source, View target)
Constructs a new VCM session, for comparing and merging changes from a given source view to a given target view.

Session(MergeType mergeType, View source, View target, Options options)
Constructs a new VCM session, for comparing and merging changes from a given source view to a given target view.

Method Summary

void	cancel() Cancels a compare or commit operation that is currently in progress.
boolean	canCommit() Determines whether or not this session can be committed in its current state.
void	close() Close this session, freeing its internal resources.
void	commit() Commits changes to the target view.
void	compare() Compares the source and target views.
void	connect(Server server) Connects a restored session to a server instance.
void	generateDifferenceReport(java.io.File reportFile) Generates a difference report for this session.
void	generateDifferenceReport(java.io.File reportFile, boolean bListItemsInMovedFolders) Generates a difference report for this session.
void	generateSummary(java.io.File reportFile, boolean bIncludeHeading) Generates a summary session report for this session.
void	generateUpdateReport(java.io.File reportFile) Generates an update report for this session.
java.lang.Object	getApplicationObject() Gets an application-specific object associated with this session.
java.lang.String	getDefaultComment() Gets the default comment to use for checkin operations that occur when committing this session.
DifferenceIterator	getDifferences() Allows an application to iterate over the set of differences detected when comparing the source and target views.
ItemDifference	getDifferencesForMergedItem(Item item) Gets the ItemDifference that corresponds to a given merge item.
ItemDifference	getDifferencesForSourceItem(Item item) Gets the ItemDifference that corresponds to a given source item.
ItemDifference	getDifferencesForTargetItem(Item item) Gets the ItemDifference that corresponds to a given target item.
Type[]	getItemTypes() Gets the item types that are to be included in the view compare/merge operation.
int	getLockCount() Gets the number of source or target items that are currently locked on behalf of this session.
static Item	getMatchHint(Item source, View target) Determines whether or not a match hint is available that indicates which item in the given target view should be matched to the specified source item.
View	getMergePreview() Gets a preview of the merge results for this session.
MergeType	getMergeType() Gets the merge type of this session.
java.lang.String	getName() Gets the name of this session.
Options	getOptions() Gets the current set of options that influence the behavior of compare or merge operations.
java.lang.String	getPostCommitRevisionLabelName() Gets the name of the post-commit revision label.
java.lang.String	getPostCommitViewLabelName() Gets the name of the post-commit view label.
java.lang.String	getPreCommitRevisionLabelName() Gets the name of the pre-commit revision label.
java.lang.String	getPreCommitViewLabelName() Gets the name of the pre-commit view label.
Item	getProcessTask() Gets the process task created in the target view when this session was committed.
Progress	getProgress() Gets a snapshot of the state of the current compare or commit operation.
java.lang.String	getRootDirectory() Gets the path to the temporary folder on disk used by this session.
Scope	getScope() Gets the current scope of this view compare/merge session.
Server	getServer() Gets the server from which this session was constructed.
ServerInfo	getServerInfo() Gets the ServerInfo associated with this session.
SessionState	getSessionState() Gets the current state of this session.
Item[]	getSourceMatchesForTargetItems(Item[] targetItems) Finds the source items that are the best matches for the given target items.
Item	getSourceMatchForTargetItem(Item targetItem) Finds the source item that is the best match for the given target item.
View	getSourceView() Gets the source view associated with this session.
View	getSourceViewForCompare() Gets the version of the source view used for comparison.
View	getTargetView() Gets the target view associated with this session.
View	getTargetViewForCompare() Gets the version of the target view used for comparison.
boolean	hasDifferences() Determines whether or not there were any differences detected when comparing the source and target views.
boolean	hasLocks() Determines whether any source or target items are currently locked on behalf of this session.
boolean	isCommitTransacted() Determines whether or not the commit operation is atomic.
boolean	isDirty() Determines whether or not this session has been changed since it was last saved or restored.
boolean	isFullScope(Type type) Determines whether or not this session will perform a full-scope compare on the items of the given type.
boolean	isIncluded(Item item) Determines whether or not the given item is in scope for the current view compare/merge operation.
boolean	isIncluded(Type type) Determines whether or not the given item type is included in this view compare/merge session.
boolean	isPartiallyCommitted() Determines whether or not this session was partially committed.
boolean	isPostCommitRevisionLabelEnabled() Determines whether or not the post-commit revision label will be created.
boolean	isPostCommitViewLabelEnabled() Determines whether or not the post-commit view label will be created.
boolean	isPreCommitRevisionLabelEnabled() Determines whether or not the pre-commit revision label will be created.
boolean	isPreCommitViewLabelEnabled() Determines whether or not the pre-commit view label will be created.
boolean	isReadOnly() Determines whether this is a read-only session.
boolean	isVerbosePreview() Determines whether or not verbose preview mode is enabled.
void	remove() Removes this session and any associated temporary files on disk.
static void	remove(java.io.File theSession) Remove the temporary folder tree associated with the specified session file.
void	removeLocks() Unlocks any source or target items that were locked on behalf of this session.
static Session	restoreFrom(java.io.File file) Restores a saved session from a file.
static Session	restoreFrom(java.io.File file, boolean willPersist) Restores a saved session from a file.
void	saveTo(java.io.File file, boolean copyContent) Save this session to a file.
void	setApplicationObject(java.lang.Object applicationObject) Sets the application-specific object associated with this session.
void	setDefaultComment(java.lang.String comment) Sets the default comment to use for checkin operations that occur when committing this session.
void	setMatch(Item source, Item target) Tells the VCM engine to match a specific source item to a specific target item.
static void	setMatchHint(Item source, Item target) Saves a match hint, indicating that the given source item corresponds to the given target item, even though the two might otherwise be unrelated.
void	setOptions(Options options) Sets options that influence the behavior of compare or merge operations.
void	setPostCommitRevisionLabelEnabled(boolean isEnabled) Determines whether or not the post-commit revision label will be created.
void	setPostCommitRevisionLabelName(java.lang.String name) Sets the name of the post-commit revision label.
void	setPostCommitViewLabelEnabled(boolean isEnabled) Determines whether or not the post-commit view label will be created.
void	setPostCommitViewLabelName(java.lang.String name) Sets the name of the post-commit view label.
void	setPreCommitRevisionLabelEnabled(boolean isEnabled) Determines whether or not the pre-commit revision label will be created.
void	setPreCommitRevisionLabelName(java.lang.String name) Sets the name of the pre-commit revision label.
void	setPreCommitViewLabelEnabled(boolean isEnabled) Determines whether or not the pre-commit view label will be created.
void	setPreCommitViewLabelName(java.lang.String name) Sets the name of the pre-commit view label.
void	setScope(Scope s) Sets the scope of this view compare/merge session.
void	setVerbosePreview(boolean verbose) Enables or disables verbose preview mode.

Methods inherited from class java.lang.Object

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

Constructor Detail

Session

public Session(MergeType mergeType,
               View source,
               View target)

Constructs a new VCM session, for comparing and merging changes from a given source view to a given target view.

Parameters:

mergeType - The type of compare/merge to be performed.

source - The source view.

target - The target view.

See Also:

Session.Session(MergeType,View,View,Options), Session.getMergeType(), Session.getSourceView(), Session.getTargetView()

Session

public Session(MergeType mergeType,
               View source,
               View target,
               Options options)

Constructs a new VCM session, for comparing and merging changes from a given source view to a given target view.

Parameters:

mergeType - The type of compare/merge to be performed.

source - The source view.

target - The target view.

options - Options that influence the behavior of the compare or merge operations.

See Also:

Session.Session(MergeType,com.starbase.starteam.View,com.starbase.starteam.View), Session.getMergeType(), Session.getSourceView(), Session.getTargetView(), Session.getOptions()

Method Detail

getServer

public Server getServer()

Gets the server from which this session was constructed.

Returns:

The Server instance from which this session was constructed.

getServerInfo

public ServerInfo getServerInfo()

Gets the ServerInfo associated with this session. For a disconnected session, the ServerInfo would have been read from a serialized stream.

Returns:

ServerInfo The ServerInfo associated with this session.

See Also:

Session.getSessionState(), Session.restoreFrom(java.io.File)

getSessionState

public SessionState getSessionState()

Gets the current state of this session.

Returns:

The current state of this session.

isDirty

public boolean isDirty()

Determines whether or not this session has been changed since it was last saved or restored.

Returns:

true if this session has been changed since it was last saved or restored, and false if it has not been changed.

See Also:

Session.saveTo(java.io.File, boolean), Session.restoreFrom(java.io.File)

getApplicationObject

public java.lang.Object getApplicationObject()

Gets an application-specific object associated with this session. The object, if provided, is saved and restored with the session data.

Returns:

An application-specific object associated with this session, or null.

setApplicationObject

public void setApplicationObject(java.lang.Object applicationObject)

Sets the application-specific object associated with this session. The object, if provided, is saved and restored with the session data.

Parameters:

applicationObject - The application-specific object to be associated with this session.

See Also:

Session.saveTo(java.io.File, boolean), Session.restoreFrom(java.io.File)

getName

public java.lang.String getName()

Gets the name of this session. The name is suitable, for example, as a file name.

Returns:

The name of this session.

getMergeType

public MergeType getMergeType()

Gets the merge type of this session.

Returns:

The merge type of this session.

getProcessTask

public Item getProcessTask()

Gets the process task created in the target view when this session was committed. The process task contains the process links to each file and folder revision that was created or modified as a result of the commit.

Returns:

The process task that was created in the target view when this session was committed.

Throws:

java.lang.IllegalStateException - if the session has not yet been committed.

getRootDirectory

public java.lang.String getRootDirectory()

Gets the path to the temporary folder on disk used by this session.

Returns:

The path to the temporary folder on disk used by this session.

See Also:

Session.remove()

getSourceView

public View getSourceView()

Gets the source view associated with this session.

Returns:

The source view associated with this session.

See Also:

Session.getTargetView(), Session.getSourceViewForCompare()

getSourceViewForCompare

public View getSourceViewForCompare()

Gets the version of the source view used for comparison. This is not always the same view that was used to create the session; it is typically a time-based snapshot, and may be populated with both active and deleted items.

Returns:

The version of the source view used for comparison.

See Also:

Session.getSourceView(), Session.getTargetViewForCompare()

getTargetViewForCompare

public View getTargetViewForCompare()

Gets the version of the target view used for comparison. This is not always the same view that was used to create the session; it is typically a time-based snapshot.

Returns:

The version of the target view used for comparison.

See Also:

Session.getTargetView(), Session.getSourceViewForCompare()

getTargetView

public View getTargetView()

Gets the target view associated with this session.

Returns:

The target view associated with this session.

See Also:

Session.getSourceView(), Session.getTargetViewForCompare()

remove

public void remove()

Removes this session and any associated temporary files on disk.

See Also:

Session.remove(java.io.File), Session.getRootDirectory()

remove

public static void remove(java.io.File theSession)

Remove the temporary folder tree associated with the specified session file.

Parameters:

theSession - A saved session file.

See Also:

Session.remove(), Session.getRootDirectory()

hasLocks

public boolean hasLocks()

Determines whether any source or target items are currently locked on behalf of this session.

Returns:

true if any source or target items are currently locked on behalf of this session.

See Also:

Session.getLockCount(), Session.removeLocks(), Options.getLockSourceForDifference(), Options.getLockTargetForDifference()

getLockCount

public int getLockCount()

Gets the number of source or target items that are currently locked on behalf of this session.

Returns:

The number of source or target items that are currently locked on behalf of this session.

See Also:

Session.hasLocks(), Session.removeLocks(), Options.getLockSourceForDifference(), Options.getLockTargetForDifference()

removeLocks

public void removeLocks()

Unlocks any source or target items that were locked on behalf of this session.

See Also:

Session.hasLocks(), Session.getLockCount(), Options.getLockSourceForDifference(), Options.getLockTargetForDifference()

compare

public void compare()

Compares the source and target views.

Note that this method returns when the compare is complete. An application that wants to monitor progress or cancel the operation must do so from a separate thread.

Throws:

java.lang.IllegalStateException - if the views have already been compared.

See Also:

Session.getProgress(), Session.cancel()

canCommit

public boolean canCommit()

Determines whether or not this session can be committed in its current state.

Note that a session cannot be committed if there are unresolved conflicts, or if there are no changes to be merged.

Also, a compare-only session or any other read-only session cannot be committed.

Returns:

boolean true if this session can be committed in its current state, and false otherwise.

See Also:

MergeType.COMPARE, ItemDifference.isUnresolved(), Session.isReadOnly(), Session.commit()

commit

public void commit()

Commits changes to the target view.

Note that this method returns when the commit is complete. An application that wants to monitor progress or cancel the operation must do so from a separate thread.

Throws:

java.lang.IllegalStateException - if the views cannot be committed in its current state.

See Also:

Session.canCommit(), Session.isCommitTransacted(), Session.getProgress(), Session.cancel()

isCommitTransacted

public boolean isCommitTransacted()

Determines whether or not the commit operation is atomic. Commits are atomic by default when running against StarTeam Server 9.0 or later.

Returns:

true if the commit operation is atomic; false otherwise.

See Also:

Session.commit(), Session.isPartiallyCommitted(), SupportedFeatures.hasMultiCommandTransactions()

isPartiallyCommitted

public boolean isPartiallyCommitted()

Determines whether or not this session was partially committed.

Partially committed sessions may occur when VCM commits are not transacted. If the commit fails in the middle (for example, due to insufficient access rights), then the session is left in a state where some of the differences have been merged to the target view and others have not.

A partially committed session may be saved, restored and re-committed. Previously committed differences will be skipped on subsequent commits.

Returns:

true if this session was partially committed, and false otherwise.

See Also:

Session.isCommitTransacted(), Session.getSessionState()

getPreCommitViewLabelName

public java.lang.String getPreCommitViewLabelName()

Gets the name of the pre-commit view label. This label shows the target view just before any changes are merged.

Creation of the pre-commit view label is optional, and is disabled by default. To enable creation of the label, use setPreCommitViewLabelEnabled.

Returns:

The name of the pre-commit view label.

setPreCommitViewLabelName

public void setPreCommitViewLabelName(java.lang.String name)

Sets the name of the pre-commit view label. This label shows the target view just before any changes are merged.

Creation of the pre-commit view label is optional, and is disabled by default. To enable creation of the label, use setPreCommitViewLabelEnabled.

Parameters:

name - The name of the pre-commit view label, or null to reset the label name to its default value.

See Also:

Session.setPreCommitViewLabelEnabled(boolean)

getPostCommitViewLabelName

public java.lang.String getPostCommitViewLabelName()

Gets the name of the post-commit view label. This label shows the target view after the changes have been merged. The label is created at the start of the commit, and is updated as each change is merged to the target view.

Creation of the post-commit view label is optional, and is enabled by default. To disable creation of the label, use setPostCommitViewLabelEnabled.

Returns:

The name of the post-commit view label.

setPostCommitViewLabelName

public void setPostCommitViewLabelName(java.lang.String name)

Sets the name of the post-commit view label. This label shows the target view after the changes have been merged. The label is created at the start of the commit, and is updated as each change is merged to the target view.

Creation of the post-commit view label is optional, and is enabled by default. To disable creation of the label, use setPostCommitViewLabelEnabled.

Parameters:

name - The name of the post-commit view label, or null to reset the label name to its default value.

See Also:

Session.setPostCommitViewLabelEnabled(boolean)

getPreCommitRevisionLabelName

public java.lang.String getPreCommitRevisionLabelName()

Gets the name of the pre-commit revision label. This label is attached only to items that are changed or removed during the commit. It is attached to the item revision that is current prior to making the change.

Creation of the pre-commit revision label is optional, and is disabled by default. To enable creation of the label, use setPreCommitRevisionLabelEnabled.

Returns:

The name of the pre-commit revision label.

setPreCommitRevisionLabelName

public void setPreCommitRevisionLabelName(java.lang.String name)

Sets the name of the pre-commit revision label. This label is attached only to items that are changed or removed during the commit. It is attached to the item revision prior to making the change.

Creation of the pre-commit revision label is optional, and is disabled by default. To enable creation of the label, use setPreCommitRevisionLabelEnabled.

Parameters:

name - The name of the pre-commit revision label, or null to reset the label name to its default value.

See Also:

Session.setPreCommitRevisionLabelEnabled(boolean)

getPostCommitRevisionLabelName

public java.lang.String getPostCommitRevisionLabelName()

Gets the name of the post-commit revision label. This label is attached only to items that are added or changed during the commit. It is attached to the item revision that is current after making the change.

Creation of the post-commit revision label is optional, and is disabled by default. To enable creation of the label, use setPostCommitRevisionLabelEnabled.

Returns:

The name of the post-commit revision label.

setPostCommitRevisionLabelName

public void setPostCommitRevisionLabelName(java.lang.String name)

Sets the name of the post-commit revision label. This label is attached only to items that are added or changed during the commit. It is attached to the item revision that is current after making the change.

Creation of the post-commit revision label is optional, and is disabled by default. To enable creation of the label, use setPostCommitRevisionLabelEnabled.

Parameters:

name - The name of the post-commit revision label, or null to reset the label name to its default value.

See Also:

Session.setPostCommitRevisionLabelEnabled(boolean)

isPreCommitViewLabelEnabled

public boolean isPreCommitViewLabelEnabled()

Determines whether or not the pre-commit view label will be created. The pre-commit view label is disabled by default.

Returns:

true if the pre-commit view label will be created, and false otherwise.

setPreCommitViewLabelEnabled

public void setPreCommitViewLabelEnabled(boolean isEnabled)

Determines whether or not the pre-commit view label will be created. The pre-commit view label is disabled by default.

Parameters:

isEnabled - true if the pre-commit view label will be created, and false otherwise.

See Also:

Session.setPreCommitViewLabelName(java.lang.String), Session.setPostCommitViewLabelEnabled(boolean), Session.setPreCommitRevisionLabelEnabled(boolean), Session.setPostCommitRevisionLabelEnabled(boolean)

isPostCommitViewLabelEnabled

public boolean isPostCommitViewLabelEnabled()

Determines whether or not the post-commit view label will be created. The post-commit view label is enabled by default.

Returns:

true if the post-commit view label will be created, and false otherwise.

setPostCommitViewLabelEnabled

public void setPostCommitViewLabelEnabled(boolean isEnabled)

Determines whether or not the post-commit view label will be created. The post-commit view label is enabled by default.

Parameters:

isEnabled - true if the post-commit view label will be created, and false otherwise.

See Also:

Session.setPostCommitViewLabelName(java.lang.String), Session.setPreCommitViewLabelEnabled(boolean), Session.setPreCommitRevisionLabelEnabled(boolean), Session.setPostCommitRevisionLabelEnabled(boolean)

isPreCommitRevisionLabelEnabled

public boolean isPreCommitRevisionLabelEnabled()

Determines whether or not the pre-commit revision label will be created. The pre-commit revision label is disabled by default.

Returns:

true if the pre-commit revision label will be created, and false otherwise.

setPreCommitRevisionLabelEnabled

public void setPreCommitRevisionLabelEnabled(boolean isEnabled)

Determines whether or not the pre-commit revision label will be created. The pre-commit revision label is disabled by default.

Parameters:

isEnabled - true if the pre-commit revision label will be created, and false otherwise.

See Also:

Session.setPreCommitRevisionLabelName(java.lang.String), Session.setPreCommitViewLabelEnabled(boolean), Session.setPostCommitViewLabelEnabled(boolean), Session.setPostCommitRevisionLabelEnabled(boolean)

isPostCommitRevisionLabelEnabled

public boolean isPostCommitRevisionLabelEnabled()

Determines whether or not the post-commit revision label will be created. The post-commit revision label is disabled by default.

Returns:

true if the post-commit revision label will be created, and false otherwise.

setPostCommitRevisionLabelEnabled

public void setPostCommitRevisionLabelEnabled(boolean isEnabled)

Determines whether or not the post-commit revision label will be created. The post-commit revision label is disabled by default.

Parameters:

isEnabled - true if the post-commit revision label will be created, and false otherwise.

See Also:

Session.setPostCommitRevisionLabelName(java.lang.String), Session.setPreCommitViewLabelEnabled(boolean), Session.setPostCommitViewLabelEnabled(boolean), Session.setPreCommitRevisionLabelEnabled(boolean)

setDefaultComment

public void setDefaultComment(java.lang.String comment)

Sets the default comment to use for checkin operations that occur when committing this session.

Parameters:

comment - The default checkin comment.

getDefaultComment

public java.lang.String getDefaultComment()

Gets the default comment to use for checkin operations that occur when committing this session.

Returns:

The default checkin comment.

hasDifferences

public boolean hasDifferences()

Determines whether or not there were any differences detected when comparing the source and target views.

Returns:

True if there were differences detected, and false otherwise.

See Also:

Session.getDifferences(), ItemDifference

getDifferences

public DifferenceIterator getDifferences()

Allows an application to iterate over the set of differences detected when comparing the source and target views.

Returns:

An iterator over the set of differences.

See Also:

Session.compare(), Session.hasDifferences(), ItemDifference

getProgress

public Progress getProgress()

Gets a snapshot of the state of the current compare or commit operation. Used for progress monitoring.

Returns:

A snapshot of the state of the current compare or commit operation.

See Also:

Session.compare(), Session.commit(), Session.cancel()

saveTo

public void saveTo(java.io.File file,
                   boolean copyContent)
            throws java.io.IOException

Save this session to a file.

If copyContent is false, then merged file content is stored in a session-specific temporary file on disk. This results in smaller session files, but means that they are generally useful only from the computer where they were generated.

If copyContent is true, then merged file content is copied into the session file. This may result in very large session files, but allows them to be used from any computer, attached to email messages, and so on.

Parameters:

file - The output file.

copyContent - True to copy merged file content into the session file; false to reference files stored on the local disk.

Throws:

java.io.IOException

See Also:

Session.restoreFrom(java.io.File), Session.getRootDirectory()

restoreFrom

public static Session restoreFrom(java.io.File file)
                           throws java.io.IOException

Restores a saved session from a file.

When a session is first restored, it is in a disconnected state. It is not fully functional until it is connected to a server instance that references the correct repository. To determine which server is required, use getServerInfo.

For example:

     Session session = Session.restoreFrom("MySession.vcmx");
     Server server = new Server(session.getServerInfo());
     server.logOn(user, password);
     session.connect(server);
     . . .
 

Parameters:

file - The session file. The file must have been previously saved using saveTo.

Returns:

A new session in the disconnected state.

Throws:

java.io.IOException

See Also:

Session.restoreFrom(java.io.File,boolean), Session.saveTo(java.io.File, boolean), Session.getSessionState(), Session.connect(com.starbase.starteam.Server), SessionState.DISCONNECTED

restoreFrom

public static Session restoreFrom(java.io.File file,
                                  boolean willPersist)
                           throws java.io.IOException

Restores a saved session from a file.

When a session is first restored, it is in a disconnected state. It is not fully functional until it is connected to a server instance that references the correct repository. To determine which server is required, use getServerInfo.

For example:

     Session session = Session.restoreFrom("MySession.vcmx");
     Server server = new Server(session.getServerInfo());
     server.logOn(user, password);
     session.connect(server);
     . . .
 

Parameters:

file - The session file. The file must have been previously saved using saveTo.

willPersist - True if the session will remain persisted on disk; false if it is a temporary session that will be removed. When a temporary session is closed, its working files on disk are automatically removed.

Returns:

A new session in the disconnected state.

Throws:

java.io.IOException

See Also:

Session.restoreFrom(java.io.File), Session.saveTo(java.io.File, boolean), Session.getSessionState(), Session.connect(com.starbase.starteam.Server), Session.close(), SessionState.DISCONNECTED

connect

public void connect(Server server)

Connects a restored session to a server instance.

When a session is first restored, it is in a disconnected state. It is not fully functional until it is connected to a server instance that references the correct repository. To determine which server is required, use getServerInfo.

For example:

     Session session = Session.restoreFrom("MySession.vcmx");
     Server server = new Server(session.getServerInfo());
     server.logOn(user, password);
     session.connect(server);
     . . .
 

Parameters:

server - The server instance to be connected. The server must refer to the same StarTeam repository with which the session was created.

See Also:

Session.restoreFrom(java.io.File)

setOptions

public void setOptions(Options options)

Sets options that influence the behavior of compare or merge operations.

An application may also call getOptions, and change individual settings in the Options instance that is returned.

Parameters:

options - Options that influence the behavior of compare or merge operations.

getOptions

public Options getOptions()

Gets the current set of options that influence the behavior of compare or merge operations.

An application may change individual settings in the Options object, and they will affect this session.

Returns:

Options that influence the behavior of compare or merge operations.

cancel

public void cancel()

Cancels a compare or commit operation that is currently in progress.

The compare and commit methods return when complete. An application that wants to monitor progress or cancel the operation must do so from a separate thread.

If a commit that is being executed as an atomic transaction is canceled before it is completed, then the transaction is rolled back. The source and target views are left in the state they were in prior to the start of the commit.

See Also:

Session.compare(), Session.commit(), Session.getProgress(), Session.isCommitTransacted()

setVerbosePreview

public void setVerbosePreview(boolean verbose)

Enables or disables verbose preview mode.

In verbose preview mode, every ItemDifference has a corresponding item in the MergePreview. In cases where the item will not actually appear in the target view after the merge, the preview item is marked deleted.

For example, in the case of an ItemDifference where the default action is "Delete", the item will be removed from the target view when the merge is commited. Thus, the merged item for this ItemDifference would normally be null. However, in verbose mode, the merged item for this ItemDifference would be a deleted item, and the deleted item would appear in the merge preview.

Parameters:

verbose - true to enable verbose preview mode; false to disable it.

See Also:

Session.isVerbosePreview(), Session.getMergePreview(), ItemDifference.getMergedItem(), Item.isDeleted()

isVerbosePreview

public boolean isVerbosePreview()

Determines whether or not verbose preview mode is enabled.

In verbose preview mode, every ItemDifference has a corresponding item in the MergePreview. In cases where the item will not actually appear in the target view after the merge, the preview item is marked deleted.

For example, in the case of an ItemDifference where the default action is "Delete", the item will be removed from the target view when the merge is commited. Thus, the merged item for this ItemDifference would normally be null. However, in verbose mode, the merged item for this ItemDifference would be a deleted item, and the deleted item would appear in the merge preview.

Returns:

true if verbose preview mode is enabled; false if it is disabled.

See Also:

Session.setVerbosePreview(boolean)

getMergePreview

public View getMergePreview()

Gets a preview of the merge results for this session.

The preview is a close approximation of what the target view would look like if the session were to be committed in its current state.

Since the preview is itself a view, it provides applications with a familiar way to browse and manipulate the difference information. For example, in order to manually resolve a file merge conflict, an application may use the ItemDifference directly:

     // Manually resolve a file merge conflict
     // through the ItemDifference.
     diff.setMergedFileContent(path);
 

Alternatively, the application may choose to checkin the new content through the merge preview:

     // 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);
 

Returns:

A preview of the merge results for this session.

getDifferencesForMergedItem

public ItemDifference getDifferencesForMergedItem(Item item)

Gets the ItemDifference that corresponds to a given merge item.

The merged item may have been obtained through getMergeItem, or it may have been obtained via the merge preview.

Parameters:

item - A merged item.

Returns:

The associated ItemDifference, or null if the given item is not a recognized merged item.

See Also:

ItemDifference.getMergedItem(), Session.getMergePreview()

getDifferencesForSourceItem

public ItemDifference getDifferencesForSourceItem(Item item)

Gets the ItemDifference that corresponds to a given source item.

Parameters:

item - A source item.

Returns:

The associated ItemDifference, or null if the given item is not a source item with an associated difference.

See Also:

ItemDifference.getSourceItem()

getDifferencesForTargetItem

public ItemDifference getDifferencesForTargetItem(Item item)

Gets the ItemDifference that corresponds to a given target item.

Parameters:

item - A target item.

Returns:

The associated ItemDifference, or null if the given item is not a target item with an associated difference.

See Also:

ItemDifference.getTargetItem()

close

public void close()

Close this session, freeing its internal resources.

Closing a session that has not been persisted also deletes the associated temporary files on disk.

See Also:

Session.remove(), Session.saveTo(java.io.File, boolean)

getItemTypes

public Type[] getItemTypes()

Gets the item types that are to be included in the view compare/merge operation. If no item types have been specified, files and folders are included by default. Note that folders are always included.

Returns:

The list of types included in the view compare/merge operation.

isIncluded

public boolean isIncluded(Type type)

Determines whether or not the given item type is included in this view compare/merge session.

Parameters:

type - The type to be tested.

Returns:

true if this type is included, false otherwise.

setScope

public void setScope(Scope s)

Sets the scope of this view compare/merge session.

By default, all files and folders in the source view are compared against the corresponding target items. An application can change the scope so that specific items or types are included.

Parameters:

s - A scope specifier, indicating which source items are compared against the target in this view compare/merge session, or null for a full-scope compare of files and folders.

See Also:

ItemTypeScope, FolderScope, ItemListScope, RevisionLabelScope, ProcessItemScope, AnyScope, EveryScope, Options.setVerboseDifferences(com.starbase.starteam.Type, boolean)

getScope

public Scope getScope()

Gets the current scope of this view compare/merge session.

Returns:

A scope specifier, indicating which source items are compared against the target in this view compare/merge session, or null for a full-scope compare of files and folders.

isIncluded

public boolean isIncluded(Item item)

Determines whether or not the given item is in scope for the current view compare/merge operation.

Parameters:

item - The item to be tested.

Returns:

true if the item is in scope; false otherwise.

See Also:

#addScope, #resetScope

isReadOnly

public boolean isReadOnly()

Determines whether this is a read-only session.

Compare-only sessions are read-only, as are sessions that have already been committed.

Returns:

true if this is a read-only session.

See Also:

SessionState.COMMITTED, MergeType.COMPARE

isFullScope

public boolean isFullScope(Type type)

Determines whether or not this session will perform a full-scope compare on the items of the given type.

Parameters:

type - An item type.

Returns:

true if this session will perform a full-scope compare on the items of the given type; false if the item type is out of scope, or if only some items of the given type are in scope.

getSourceMatchForTargetItem

public Item getSourceMatchForTargetItem(Item targetItem)

Finds the source item that is the best match for the given target item.

The scope of the view compare/merge operation is always defined in terms of the source. getSourceMatchForTargetItem() may be used by an application that wants to define the scope starting with a target item.

To find source matches for multiple target items, use getSourceMatchesForTargetItems(), which will result in better performance.

Parameters:

targetItem - Item

Returns:

The matching source item, or null.

getSourceMatchesForTargetItems

public Item[] getSourceMatchesForTargetItems(Item[] targetItems)

Finds the source items that are the best matches for the given target items.

The scope of the view compare/merge operation is always defined in terms of the source. getSourceMatchesForTargetItems() may be used by an application that wants to define the scope starting with a set of target items.

To find source matches for multiple target items, use getSourceMatchesForTargetItems(), which will result in better performance.

Returns:

The matching source item, or null.

generateDifferenceReport

public void generateDifferenceReport(java.io.File reportFile)
                              throws java.io.IOException

Generates a difference report for this session. This report lists differences that were detected when the source and target views were compared. The report is in HTML format.

Parameters:

reportFile - The report output file.

Throws:

java.io.IOException

generateDifferenceReport

public void generateDifferenceReport(java.io.File reportFile,
                                     boolean bListItemsInMovedFolders)
                              throws java.io.IOException

Generates a difference report for this session. This report lists differences that were detected when the source and target views were compared. The report is in HTML format.

Parameters:

reportFile - The report output file.

bListItemsInMovedFolders - true to list items whose parent folder has moved in either the source or target, even if the items themselves have no true differences.

Throws:

java.io.IOException

generateSummary

public void generateSummary(java.io.File reportFile,
                            boolean bIncludeHeading)
                     throws java.io.IOException

Generates a summary session report for this session. The report is in HTML format.

Parameters:

reportFile - The report output file.

bIncludeHeading - false to suppress the generation of the heading.

Throws:

java.io.IOException

generateUpdateReport

public void generateUpdateReport(java.io.File reportFile)
                          throws java.io.IOException

Generates an update report for this session. This report lists items that were added, changed or removed when the session was committed. The report is in HTML format.

Parameters:

reportFile - The report output file.

Throws:

java.io.IOException

setMatch

public void setMatch(Item source,
                     Item target)

Tells the VCM engine to match a specific source item to a specific target item. This overrides the normal comparison logic.

A client application can call setMatch() before calling compare() to avoid an AmbiguousMatchException.

Parameters:

source - An item from the source view.

target - The corresponding item from the target view.

See Also:

Session.compare(), AmbiguousMatchException

setMatchHint

public static void setMatchHint(Item source,
                                Item target)

Saves a match hint, indicating that the given source item corresponds to the given target item, even though the two might otherwise be unrelated.

Internally, the match hint is represented by a StarTeam link.

Parameters:

source - A source item.

target - The matching target item.

getMatchHint

public static Item getMatchHint(Item source,
                                View target)

Determines whether or not a match hint is available that indicates which item in the given target view should be matched to the specified source item.

Parameters:

source - A source item.

target - The desired target view.