com.starteam.viewcomparemerge
Class Session

java.lang.Object
  com.starteam.ChangeSession
      com.starteam.viewcomparemerge.Session

public final class Session
extends ChangeSession

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.starteam.viewcomparemerge.

Nested Class Summary

static class

Session.State The state of the sesion.

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.

Session(View view)
Constructs a new VCM session for comparing and merging changes from the desktop (workspace) to the given view

Method Summary

void	addListener(CheckinListener listener) Add a checkin listener to this session when ready to commit a workspace view CheckinManager events fired during the commit will be delegated to this listener Client applications may use these events to perform per-file actions such as requiring different checkin comments
void	addListener(CheckoutListener listener) Add a checkout listener to this session when ready to commit a workspace view CheckoutManager events fired during the commit will be delegated to this listener Client applications may use these events to perform per-file actions such as launching DeltaII to resolve Merge conflicts
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.
static Session	forPromote(ChangePackage cp) Creates a new VCM session for replaying the given change package to its parent view.
static Session	forPromote(View source) Creates a new VCM session for promoting the given view to its parent.
static Session	forRebase(View target) Creates a new VCM session for rebasing the given view from its parent.
static Session	forReplay(ChangePackage cp, View target) Creates a new VCM session for replaying the given change package to a new target view.
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.
java.lang.String	getDefaultDescription() Gets the default description for this session.
java.lang.String	getDefaultName() Gets a default name for this session.
ItemDifference[]	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.
TypeCollection	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.
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.
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.
Session.State	getSessionState() Gets the current state of this session.
ChangePackage.SessionType	getSessionType() Gets the SessionType of this session.
ViewMemberCollection	getSourceMatchesForTargetItems(ViewMemberCollection 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	isActive() Returns true if this session is in an active state.
boolean	isCommitted() Returns true if this session is in a committed state.
boolean	isDirty() Determines whether or not this session has been changed since it was last saved or restored.
boolean	isFullScope(Item.Type type) Determines whether or not this session will perform a full-scope compare on the items of the given type.
boolean	isIncluded(Item.Type type) Determines whether or not the given item type is included in this view compare/merge session.
boolean	isIncluded(Item item) Determines whether or not the given item is in scope for the current view compare/merge operation.
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 ViewMemberCollection	resolve(View target, java.io.File file) Resolve a saved session file for a committed session (such as you'd find attached to a process task in the target view), to return a list of all the relevant target item revisions from the ItemDifferences that resulted in changes (i.e., everything except Ignore).
void	restart(Server server) Restart a restored 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 com.starteam.ChangeSession

close, getChangePackage, getDescription, getName, save, setDescription, setName

Methods inherited from class java.lang.Object

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

Constructor Detail

Session

public Session(View view)

Constructs a new VCM session for comparing and merging changes from the desktop (workspace) to the given view

Parameters:

view - the target view

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.starteam.View,com.starteam.View), Session.getMergeType(), Session.getSourceView(), Session.getTargetView(), Session.getOptions()

Method Detail

forPromote

public static Session forPromote(View source)

Creates a new VCM session for promoting the given view to its parent.

Parameters:

source - The view to be promoted.

Returns:

A newly constructed promote session.

See Also:

MergeType.PROMOTE

forRebase

public static Session forRebase(View target)

Creates a new VCM session for rebasing the given view from its parent.

Parameters:

target - The view to be rebased.

Returns:

A newly constructed rebase session.

See Also:

MergeType.REBASE

forReplay

public static Session forReplay(ChangePackage cp,
                                View target)

Creates a new VCM session for replaying the given change package to a new target view.

Parameters:

cp - The change package to be replayed.

target - The new target view.

Returns:

A newly constructed session with the appropriate merge type.

forPromote

public static Session forPromote(ChangePackage cp)

Creates a new VCM session for replaying the given change package to its parent view.

Parameters:

cp - The change package to be replayed.

Returns:

A newly constructed promote session.

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 Session.State getSessionState()

Gets the current state of this session.

Returns:

The current state of this session.

isActive

public boolean isActive()

Returns true if this session is in an active state.

Specified by:

isActive in class ChangeSession

Returns:

boolean

isCommitted

public boolean isCommitted()

Returns true if this session is in a committed state.

Specified by:

isCommitted in class ChangeSession

Returns:

boolean

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)

getDefaultName

public java.lang.String getDefaultName()

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

Specified by:

getDefaultName in class ChangeSession

Returns:

A default name for this session.

getMergeType

public MergeType getMergeType()

Gets the merge type of this session.

Returns:

The merge type of this session.

getSessionType

public ChangePackage.SessionType getSessionType()

Gets the SessionType of this session. Returns null for a compare-only session.

Returns:

the SessionType of this session, or null for a compare-only session.

See Also:

ChangePackage.SessionType

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.

Specified by:

getSourceView in class ChangeSession

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.

Specified by:

getTargetView in class ChangeSession

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. If the session has been restored but is still in a disconnected state, hasLocks will inspect the XML representation of the session to determine whether or not items are currently locked

Specified by:

hasLocks in class ChangeSession

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. If the session has been restored but is still in a disconnected state, getLockCount will inspect the XML representation of the session to determine the number of items currently locked

Specified by:

getLockCount in class ChangeSession

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. If the session is in a disconnected state removeLocks will inspect the XML representation of the session to identify and unlock the locked items

Specified by:

removeLocks in class ChangeSession

See Also:

Session.hasLocks(), Session.getLockCount(), Session.getSourceView(), Session.getTargetView(), 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 or if the session was closed/disconnected

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()

addListener

public void addListener(CheckinListener listener)

Add a checkin listener to this session when ready to commit a workspace view CheckinManager events fired during the commit will be delegated to this listener Client applications may use these events to perform per-file actions such as requiring different checkin comments

Parameters:

listener - a checkin listener or NULL

addListener

public void addListener(CheckoutListener listener)

Add a checkout listener to this session when ready to commit a workspace view CheckoutManager events fired during the commit will be delegated to this listener Client applications may use these events to perform per-file actions such as launching DeltaII to resolve Merge conflicts

Parameters:

listener - a checkin listener or NULL

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.getProgress(), Session.cancel()

getDefaultDescription

public java.lang.String getDefaultDescription()

Gets the default description for this session.

Returns:

the default description for this session.

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 ItemDifference[] 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.

Throws:

java.lang.IllegalStateException - if the source and target have not yet been compared.

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.starteam.Server), Session.restart(com.starteam.Server), Session.State.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.starteam.Server), Session.close(), Session.State.DISCONNECTED

resolve

public static ViewMemberCollection resolve(View target,
                                           java.io.File file)
                                    throws java.io.IOException

Resolve a saved session file for a committed session (such as you'd find attached to a process task in the target view), to return a list of all the relevant target item revisions from the ItemDifferences that resulted in changes (i.e., everything except Ignore).

Parameters:

target - View the target view to resolve to

file - File the java.io.File containing the saved session

Returns:

Collection of ViewMembers resolved to the specified target View

Throws:

java.io.IOException

restart

public void restart(Server server)

Restart a restored session. The session must be in a disconnected state The session is opened for writing, and is ready to re-run a compare in the current context of the source and target views i.e. the scope of the session is refreshed, and relevant changes to newer revisions (of items that are in scope) are automatically picked up. Session.connect(Server) and Session.restart(Server) are mututally exclusive

Specified by:

restart in class ChangeSession

Parameters:

server - the server instance on which this session will run

See Also:

Session.connect(Server), Session.restoreFrom(java.io.File)

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

Specified by:

connect in class ChangeSession

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()

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 committed. 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(), ViewMember.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 committed. 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.

Overrides:

close in class ChangeSession

See Also:

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

getItemTypes

public TypeCollection 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(Item.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.starteam.Item.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:

Session.setScope(com.starteam.viewcomparemerge.Scope)

isReadOnly

public boolean isReadOnly()

Determines whether this is a read-only session.

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

Overrides:

isReadOnly in class ChangeSession

Returns:

true if this is a read-only session.

See Also:

Session.State.COMMITTED, Session.State.DISCONNECTED, MergeType.COMPARE

isFullScope

public boolean isFullScope(Item.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 ViewMemberCollection getSourceMatchesForTargetItems(ViewMemberCollection 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.

Parameters:

targetItems - Item collection

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.

Returns:

The matching item in the target view, or null if no match hint has been saved for this source item.