com.starteam

Class Trace

java.lang.Object

com.starteam.TypedResource

com.starteam.LiveObject

com.starteam.TrackedObject

com.starteam.VersionedObject

com.starteam.ViewMember

com.starteam.Trace

All Implemented Interfaces:

ISecurable, Lockable, LockableObject, java.lang.Cloneable

Direct Known Subclasses:

LinkToTraceAdapter

public class Trace
extends ViewMember

A typed relationship between two artifacts.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Trace.Status The Status of a Trace
static class	Trace.TraceType Trace Type
static class	Trace.Type The type of the Trace
static class	Trace.WebCacheTrace Trace accessor for cached SDK Traces contained objects are obtained from the artifact cache

Nested classes/interfaces inherited from class com.starteam.ViewMember

ViewMember.LockType, ViewMember.MyLock, ViewMember.ShareState, ViewMember.WebCacheViewMember

Nested classes/interfaces inherited from class com.starteam.VersionedObject

VersionedObject.WebCacheVersionedObject

Nested classes/interfaces inherited from class com.starteam.TrackedObject

TrackedObject.WebCacheTrackedObject

Nested classes/interfaces inherited from class com.starteam.LiveObject

LiveObject.WebCacheLiveObject

Nested classes/interfaces inherited from class com.starteam.TypedResource

TypedResource.BranchState

Constructor Summary

Constructors

Constructor and Description
Trace(View view) Creates a new trace in the specified view.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getDescription() Gets the description of this trace.
double	getOrder() Returns the order in which the trace should be executed.
Trace.Type.PropertyCollection	getProperties() Gets all the properties of the Trace Type
LinkValue	getSource() Gets the source endpoint of this trace.
java.lang.String	getSourceVersions(Trace.Status statusValue) Returns the suspect transition versions of the source endpoint If a statusValue is not specified, the 'raw' value is returned.
Trace.Status	getStatus() Gets the Status of this Trace.
LinkValue	getTarget() Gets the target endpoint of this trace.
Trace.TraceType	getTraceType() Gets the TraceType of this Trace.
View	getView() Gets the view that contains this Trace
boolean	isReverseShareRecommended(View target) Determines whether share or reverse-share is the more appropriate operation when sharing this trace to the given target view.
boolean	isSuspect() Determines whether the trace is suspect
void	pinSource() Set the source end-point of this trace to pinned.
void	pinTarget() Set the target end-point of this trace to pinned.
void	remove() Removes this trace from the view.
Trace	reverseShareTo(View target) Transfers ownership of the root share of a trace to a new view, sharing a copy back to the original location.
void	setDescription(java.lang.String description) Sets the description of this trace.
void	setOrder(double traceOrder) Sets the order in which the trace should be executed.
void	setSource(LinkValue source) Sets the source endpoint of this trace.
void	setSource(LiveObject source) Sets the source endpoint of this trace.
void	setSourceVersions(Trace.Status statusValue, java.lang.String version) Set a source version override for specific status value
void	setStatus(Trace.Status status) Set the status of the trace
void	setSuspect(boolean isSuspect) Mark the trace as suspect
void	setTarget(LinkValue target) Sets the target endpoint of this trace.
void	setTarget(LiveObject target) Sets the target endpoint of this trace.
void	setTraceType(Trace.TraceType type) Set the trace type of the trace
Trace	shareTo(View target) Shares this trace to a new view.
Trace	smartShareTo(View target) Shares or reverse-shares this trace to the given target view, as appropriate.
java.lang.String	toString() Returns the description of this trace.
void	unpinSource() Set the source end-point of this trace to float.
void	unpinTarget() Set the target end-point of this trace to float.
void	update() Stores the underlying entity in the server.

Methods inherited from class com.starteam.ViewMember

copy, equals, findLinks, getAllLabels, getAllShares, getAttachedLabels, getAttachments, getBehavior, getCache, getComment, getDeletedBy, getDeletedShares, getDeletedTime, getDisplayValue, getDotNotation, getExclusiveLocker, getExternalID, getExternalURL, getFromHistory, getFromHistory, getFromHistory, getFromHistory, getHistory, getID, getIntegerArrayValue, getLocker, getMyLockType, getParentContainer, getParentRevision, getPresentationID, getRights, getRootObjectID, getShare, getShare, getTraces, getValue, getViewMemberRevisions, getViewVersion, getVMID, hashCode, hasPermissions, isBookmarked, isBranchable, isDeleted, isDiscarded, isDisembodied, isEqualTo, isFloating, isPinned, isReadOnly, isRootShare, isUnread, lockExclusive, lockExclusive, lockNonExclusive, modifyBookmark, modifyReadStatus, putLock, remove, setAttachments, setBehavior, setBranchOnChange, setComment, setExternalID, setExternalURL, setFixedConfiguration, setFloatingConfiguration, setRights, setValue, toRESTUrl, unlock, update, updateRevisionComment

Methods inherited from class com.starteam.VersionedObject

getBranchRevision, getRevisionNumber, getShortComment, getViewVersion, isFromHistory, setShortComment

Methods inherited from class com.starteam.TrackedObject

getModifiedBy, getModifiedTime

Methods inherited from class com.starteam.LiveObject

getCreatedBy, getCreatedTime, toStarTeamURL

Methods inherited from class com.starteam.TypedResource

addToIntegerArray, getBooleanValue, getByteArrayValue, getCachedProperties, getContentValue, getDateTimeValue, getDateValue, getDisplayName, getDoubleValue, getEnumDisplayName, getEnumeratedValues, getIntegerValue, getLinkValue, getLongValue, getObjectID, getPossibleValues, getServer, getStringValue, getTimeSpanValue, getType, hasCachedProperties, hasValue, isDirty, isDirty, isNew, removeFromIntegerArray, setBooleanValue, setByteArrayValue, setContentValue, setDateTimeValue, setDateValue, setDoubleValue, setEnumeratedValue, setEnumeratedValues, setIntegerArrayValue, setIntegerValue, setLinkValue, setLongValue, setStringValue, setTimeSpanValue

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.starteam.ISecurable

getServer, getType

Constructor Detail

Trace

public Trace(View view)

Creates a new trace in the specified view.

Parameters:

view - The view to which this new trace will be added.

Method Detail

getProperties

public Trace.Type.PropertyCollection getProperties()

Gets all the properties of the Trace Type

Returns:

Collection of properties

getTraceType

public Trace.TraceType getTraceType()

Gets the TraceType of this Trace. return UNDEFINED if the TraceType is NULL

Returns:

Trace.TraceType

setTraceType

public void setTraceType(Trace.TraceType type)

Set the trace type of the trace

Parameters:

type - the trace type to set

getStatus

public Trace.Status getStatus()

Gets the Status of this Trace.

Returns:

Status

getOrder

public double getOrder()

Returns the order in which the trace should be executed.

Returns:

the order in which the trace should be executed.

See Also:

Trace.Type.PropertyCollection.ORDER

setOrder

public void setOrder(double traceOrder)

Sets the order in which the trace should be executed.

Parameters:

traceOrder - the order in which the trace should be executed.

setStatus

public void setStatus(Trace.Status status)

Set the status of the trace

Parameters:

status - the status to set

getSource

public LinkValue getSource()

Gets the source endpoint of this trace.

Returns:

The source endpoint of this trace.

setSource

public void setSource(LinkValue source)

Sets the source endpoint of this trace.

Parameters:

source - The source endpoint of this trace.

setSource

public void setSource(LiveObject source)

Sets the source endpoint of this trace.

Parameters:

source - The source liveobject of this trace. May be from this server or any other; the resulting source LinkValue will be an internal link or an external link as appropriate.

unpinSource

public void unpinSource()

Set the source end-point of this trace to float. i.e. the source will always match the tip ViewMember of the configuration

pinSource

public void pinSource()

Set the source end-point of this trace to pinned. i.e. the source will match the specified revision of the ViewMember

unpinTarget

public void unpinTarget()

Set the target end-point of this trace to float. i.e. the target will always match the tip ViewMember of the configuration

pinTarget

public void pinTarget()

Set the target end-point of this trace to pinned. i.e. the target will match the specified revision of the ViewMember

getTarget

public LinkValue getTarget()

Gets the target endpoint of this trace.

Returns:

The target endpoint of this trace.

setTarget

public void setTarget(LinkValue target)

Sets the target endpoint of this trace.

Parameters:

target - The target endpoint of this trace.

setTarget

public void setTarget(LiveObject target)

Sets the target endpoint of this trace.

Parameters:

target - The target liveobject of this trace. May be from this server or any other; the resulting source LinkValue will be an internal link or an external link as appropriate.

getDescription

public java.lang.String getDescription()

Gets the description of this trace.

Returns:

The description of this trace.

isSuspect

public boolean isSuspect()

Determines whether the trace is suspect

Returns:

true if the trace is suspect

setSuspect

public void setSuspect(boolean isSuspect)

Mark the trace as suspect

Parameters:

isSuspect - the suspect flag

getSourceVersions

public java.lang.String getSourceVersions(Trace.Status statusValue)

Returns the suspect transition versions of the source endpoint If a statusValue is not specified, the 'raw' value is returned. If a Status Value is specified, then the DotNotation of the matching status, if available, is returned

Parameters:

statusValue - a specific Trace Status to look for

Returns:

the suspect transition version(s) of the source endpoint

setSourceVersions

public void setSourceVersions(Trace.Status statusValue,
                              java.lang.String version)

Set a source version override for specific status value

Parameters:

statusValue - the status value to override

version - the new dot notation

setDescription

public void setDescription(java.lang.String description)

Sets the description of this trace.

Parameters:

description - The description of this trace.

getView

public View getView()

Gets the view that contains this Trace

Overrides:

getView in class ViewMember

Returns:

View

See Also:

ViewMember.isDisembodied()

isReverseShareRecommended

public boolean isReverseShareRecommended(View target)

Determines whether share or reverse-share is the more appropriate operation when sharing this trace to the given target view.

Parameters:

target - The target view.

Returns:

true if a reverse-share is appropriate; false otherwise.

See Also:

Trace.smartShareTo(com.starteam.View)

smartShareTo

public Trace smartShareTo(View target)

Shares or reverse-shares this trace to the given target view, as appropriate. The new share uses a time-based configuration, and is set to branch on change.

Parameters:

target - The target view.

Returns:

The shared trace.

See Also:

Trace.isReverseShareRecommended(com.starteam.View)

shareTo

public Trace shareTo(View target)

Shares this trace to a new view. The shared trace will still exist in its original view as well as in the new one.

Parameters:

target - The new view.

Returns:

The newly shared trace.

See Also:

Trace.reverseShareTo(com.starteam.View)

reverseShareTo

public Trace reverseShareTo(View target)

Transfers ownership of the root share of a trace to a new view, sharing a copy back to the original location.

In its basic form, this is simply a move followed by a share. However, reverse share is permitted from a rolled-back view. This is supported by finding the corresponding trace in the tip view configuration, and reverse sharing that one.

When reverse sharing from a rolled back view, it is possible that the desired trace revision in the target is not the tip revision of the trace being shared. The reverse share operation compensates for this by moving the trace to the target, sharing it back to the source, and then rolling back the target by creating a new revision whose user-modifiable properties (and content, if applicable) match the desired revision.

Sharing replaces the original trace in the source view with a new share of the same underlying object. Since this is a new trace with a new VMID, it initially has no attached labels. The reverse share operation will attempt to apply the same labels to the corresponding revisions of the new trace. However, the label operations may be unsuccessful (for example, because of access rights, or because a label may be frozen). Any server exceptions that occur while re-applying labels to the new share are silently ignored, and will not cause the reverse share operation to fail.

Parameters:

target - The new view.

Returns:

The new trace in the target view.

See Also:

Trace.shareTo(com.starteam.View)

update

public void update()

Stores the underlying entity in the server. If the item is new it will be created otherwise an existing item will be modified.

Overrides:

update in class ViewMember

remove

public void remove()

Removes this trace from the view. This does not affect other shares of the trace.

Overrides:

remove in class ViewMember

toString

public java.lang.String toString()

Returns the description of this trace.

Overrides:

toString in class TypedResource

Returns:

the description of this trace.