com.starteam
Class Item

java.lang.Object
  com.starteam.TypedResource
      com.starteam.LiveObject
          com.starteam.TrackedObject
              com.starteam.VersionedObject
                  com.starteam.ViewMember
                      com.starteam.Item

All Implemented Interfaces:

ISecurable, Lockable, LockableObject, java.lang.Cloneable

Direct Known Subclasses:

Audit, ChangeRequest, Concept, File, Folder, Sprint, TreeItem, WhiteBoard

public class Item
extends ViewMember

Contextual reference to an object in a StarTeam repository. Items provide transparent access to the underlying entity (e.g., modifying the description of an item by calling Item.put("Description", "some text") actually modifies the Description property of the underlying entity the Item references. An Item consists of the underlying entity and its context within a view. Therefore, an Item has direct knowledge of the items to which it is related. Items also maintain state information to determine if the underlying object is new or modified relative to instances of the object stored in the repository. An Item also has a temporal aspect in that it represents a single development path (linear history) of the underlying object as of a moment in time.

Nested Class Summary

static class	Item.Type The Type of Items.
static class	Item.WebCacheItem Item accessor for cached SDK Items 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

Method Summary

ViewMember	copy() Creates a copy of the Item and all of its properties.
void	deleteMergePoint(MergePoint mergePoint) Deletes the specified merge point for this item.
Item	getCommonAncestor(Item other) Gets the most recent common ancestor between this item and the given item.
java.lang.String	getDebugString() Returns a String that is potentially useful while debugging.
PropertyCollection	getDisplayableProperties() return the set of properties that may be displayed in the context of an ALM editor If a layout is available, return the properties described in the layout xml, otherwise, return a default set of properties for the type The returned set may be empty, but is never null.
int	getItemID() Returns an identifier representing this item, that is, the underlying entity represented by this item in this specific context.
MergePoint[]	getMergeHistory() Returns the merge points for this item.
java.lang.String	getNewRevisionComment() Returns the empty string.
ISecurableContainer	getParentContainer() If there are no access rights explicitly assigned to this object, then the effective access rights come from a parent container.
Folder	getParentFolder() Returns the folder in which this item exists.
java.lang.String	getParentFolderHierarchy() Gets the fully-qualified name of this item's parent folder.
java.lang.String	getParentFolderName() Returns the name of the item's parent folder.
java.lang.String	getParentFolderPath() Returns the working directory path for the item's parent folder.
java.lang.String	getParentFolderQualifiedName() Gets the fully-qualified name of this item's parent folder.
ChangePackageCollection	getSharedChangePackages(View[] targets) Returns the set of change packages visible across the specified target views across the share tree of this item, as resolved to those target views The goal is to match old style server wide link visibility rules, constrained, however, by the fact that ChangePackages are view members.
TraceCollection	getSharedTraces(View[] targets) Returns the set of traces visible across the specified target views across the share tree of this item, as resolved to those target views The goal is to match old style server wide link visibility rules, constrained, however, by the fact that Traces are view members.
boolean	isEqualTo(Item item) Compares two Items.
boolean	isReverseShareRecommended(Folder target) Determines whether share or reverse-share is the more appropriate operation when sharing this item to the given target folder.
void	moveTo(Folder toFolder) Moves this item to the specified folder.
MergePoint	recordMergePoint(Item source) Records the merge point used to create this revision of the item with respect to the specified source item.
void	remove() Removes this item from its current folder.
Item	resolve() Gets a full-resolved version of this item.
MergePoint	resolveMergePoint(Item source) Returns the merge point used to create this revision of the item with respect to the specified source item.
MergePoint	resolveMergePointEx(Item source) Returns the real or simulated (change) merge point used to create this revision of the item with respect to the specified source item.
Item	reverseShareTo(Folder toFolder) Transfers ownership of the root share of an item to a new view or folder, sharing a copy back to the original location.
Item	reverseShareTo(Folder toFolder, View fromView) A variation of reverseShareTo() that is preferred in the case where many items may be shared from a rolled-back view configuration.
Item	shareTo(Folder toFolder) Shares this item to a new folder.
Item	smartShareTo(Folder target) Shares or reverse-shares this item to the given target folder, as appropriate.
java.lang.String	toString() Returns a string representation of this object.

Methods inherited from class com.starteam.ViewMember

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

Methods inherited from class com.starteam.VersionedObject

getBranchRevision, getRevisionNumber, getViewVersion, isFromHistory

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, 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

Method Detail

copy

public ViewMember copy()

Creates a copy of the Item and all of its properties. Does not copy the parent folder, type, etc. Useful to applications that want to save a snapshot of the Item in a given state, for example, before calling Item.refresh() or Folder.refreshItems().

Overrides:

copy in class ViewMember

Returns:

A copy of the Item and all of its properties.

See Also:

Item.isEqualTo(com.starteam.Item)

isEqualTo

public boolean isEqualTo(Item item)

Compares two Items. The items are considered equal if:

• They have the same Type. Types are compared by ClassID.
• They have the same ItemID, or are both new Items.
• They belong to the same view. Views are compared by ID.
• They both belong to the same folder. Folders are compared by ItemID. If both Items are themselves Folders, then they must have the same parent, or both be root folders without a parent. If both Items are disembodied, then the parent folder is not considered.
• For all Item properties, the property values must be equal for both Items.

Parameters:

item - The Item to be compared to this one.

Returns:

true if no differences were found.

See Also:

Item.copy()

getParentFolder

public Folder getParentFolder()

Returns the folder in which this item exists.

Returns:

the folder in which this item exists.

Throws:

DisembodiedException - if the Item is disembodied

See Also:

ViewMember.isDisembodied()

moveTo

public void moveTo(Folder toFolder)

Moves this item to the specified folder. This item will be removed from its current folder and added to the toFolder. However, if the new parent folder (toFolder) is floating, then the item will receive a new item id, which will be updated in place In this case too, if this item is a folder, then all it's contained items (prior to its move) will receive new item ids (after the move). Under these circumstances, the client application should refresh those contained types (in this folder) that it cares about

Parameters:

toFolder - the new folder to which this item is to be moved.

Throws:

DisembodiedException - if the Item is disembodied

See Also:

ViewMember.isDisembodied()

isReverseShareRecommended

public boolean isReverseShareRecommended(Folder target)

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

Parameters:

target - The target folder.

Returns:

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

See Also:

Item.smartShareTo(com.starteam.Folder)

smartShareTo

public Item smartShareTo(Folder target)

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

Parameters:

target - The target folder.

Returns:

The shared item.

See Also:

Item.isReverseShareRecommended(com.starteam.Folder)

shareTo

public Item shareTo(Folder toFolder)

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

If this is a deleted item, shareTo() will create a new item with the same properties, but in the state it was in prior to being deleted. This provides a way to recover content from the recycle bin.

Parameters:

toFolder - The new parent folder.

Returns:

The item object representing the newly shared item.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

ViewMember.isDisembodied(), Item.moveTo(com.starteam.Folder), Item.reverseShareTo(com.starteam.Folder), ViewMember.isDeleted(), RecycleBin

reverseShareTo

public Item reverseShareTo(Folder toFolder)

Transfers ownership of the root share of an item to a new view or folder, 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 item in the tip view configuration, and reverse sharing that one.

When reverse sharing from a rolled back view, it is possible that the desired item revision in the target is not the tip revision of the item being shared. The reverse share operation compensates for this by moving the item 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 item in the source view with a new share of the same underlying object. Since this is a new item with a new item ID, it initially has no attached labels. The reverse share operation will attempt to apply the same labels to the corresponding revisions of the new item. 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:

toFolder - The new parent folder.

Returns:

The item object representing the new item in the target folder.

Throws:

DisembodiedException - if either this item or the Folder is disembodied.

See Also:

ViewMember.isDisembodied(), Item.moveTo(com.starteam.Folder), Item.shareTo(com.starteam.Folder), Item.reverseShareTo(Folder,View)

reverseShareTo

public Item reverseShareTo(Folder toFolder,
                           View fromView)

A variation of reverseShareTo() that is preferred in the case where many items may be shared from a rolled-back view configuration.

Such shares can be expensive, due to the cost of opening the tip configuration of the view, and resolving the shared item in the tip. This cost can be minimized over multiple reverse share operations by opening the tip configuration once in the client application, and re-using it for each share.

Parameters:

toFolder - The new parent folder.

fromView - The tip configuration of the view in which this item resides.

Returns:

The item object representing the new item in the target folder.

Throws:

DisembodiedException - if either this item or the Folder is disembodied.

See Also:

ViewMember.isDisembodied(), Item.moveTo(com.starteam.Folder), Item.shareTo(com.starteam.Folder), Item.reverseShareTo(Folder)

remove

public void remove()

Removes this item from its current folder. This does not affect other shares of the item.

Overrides:

remove in class ViewMember

getItemID

public int getItemID()

Returns an identifier representing this item, that is, the underlying entity represented by this item in this specific context. This ID is different for each instance of one entity shared in two locations. For instance, a file "foo" is shared between the "source" folder and the "include" folder. Calling this method on the item "foo" contained in folder "source" yields a different ID than calling it on the item "foo" contained in folder "include". Therefore, this ID is not appropriately used as an identifier of the entity itself, rather it identifies an occurrence of the entity in a view.

Returns:

the unique item ID for this item.

See Also:

ViewMember.getVMID()

toString

public java.lang.String toString()

Returns a string representation of this object.

Overrides:

toString in class TypedResource

Returns:

a string representation of this object.

getDisplayableProperties

public PropertyCollection getDisplayableProperties()

return the set of properties that may be displayed in the context of an ALM editor If a layout is available, return the properties described in the layout xml, otherwise, return a default set of properties for the type The returned set may be empty, but is never null.

Returns:

the set of displayable properties

getDebugString

public java.lang.String getDebugString()

Returns a String that is potentially useful while debugging.

Returns:

a debug string for this item

resolveMergePoint

public MergePoint resolveMergePoint(Item source)

Returns the merge point used to create this revision of the item with respect to the specified source item. The source item cannot be null, must be of the same type as this item and reside in the same repository as this item.

Parameters:

source - the source Item that was the "merge" origin of the revision specified by this item.

Returns:

the merge point used to create this revision of the item with respect to the specified source item.

resolveMergePointEx

public MergePoint resolveMergePointEx(Item source)

Returns the real or simulated (change) merge point used to create this revision of the item with respect to the specified source item. The source item cannot be null, must be of the same type as this item and reside in the same repository as this item.

Parameters:

source - the source Item that was the "merge" origin of the revision specified by this item.

Returns:

the merge point used to create this revision of the item with respect to the specified source item.

recordMergePoint

public MergePoint recordMergePoint(Item source)

Records the merge point used to create this revision of the item with respect to the specified source item. The source item cannot be null, must be of the same type as this item and reside in the same repository as this item.

Parameters:

source - the source Item that is to be the "merge" origin of the revision specified by this item.

Returns:

the merge point used to create this revision

deleteMergePoint

public void deleteMergePoint(MergePoint mergePoint)

Deletes the specified merge point for this item.

Parameters:

mergePoint - the merge point to be deleted

getMergeHistory

public MergePoint[] getMergeHistory()

Returns the merge points for this item.

Returns:

the merge points for this item

getParentFolderName

public java.lang.String getParentFolderName()

Returns the name of the item's parent folder.

Returns:

the name of the item's parent folder.

See Also:

Item.getParentFolder(), Folder.getName()

getParentFolderPath

public java.lang.String getParentFolderPath()

Returns the working directory path for the item's parent folder.

Returns:

the working directory path for the item's parent folder.

See Also:

Item.getParentFolder(), Folder.getPath()

getParentFolderHierarchy

public java.lang.String getParentFolderHierarchy()

Gets the fully-qualified name of this item's parent folder. The names of all parent folders up to the root are included, separated by and terminated with the platform-specific path separator character.

Returns:

The fully-qualified name of this item's parent folder.

See Also:

Item.getParentFolder(), Folder.getFolderHierarchy(), ClientContext.getFilePathDelimiter()

getParentFolderQualifiedName

public java.lang.String getParentFolderQualifiedName()

Gets the fully-qualified name of this item's parent folder. The names of all parent folders up to the root are included, separated by the backslash character on all platforms. There is no terminating backslash. This is the same format used for the "Folder Path" property.

Returns:

The fully-qualified name of this item's parent folder.

See Also:

Item.getParentFolder(), Folder.getQualifiedName(), Item.getParentFolderHierarchy()

getNewRevisionComment

public java.lang.String getNewRevisionComment()

Returns the empty string. Added only because the property is used for the Win32 client and might show up in a query or filter definition.

Returns:

the empty string.

getCommonAncestor

public Item getCommonAncestor(Item other)

Gets the most recent common ancestor between this item and the given item. The common ancestor is taken from this item's history.

Parameters:

other - The item to be compared with this one.

Returns:

The most recent common ancestor between this item and the given item, or null if the two items have no common ancestor.

See Also:

ViewMember.isBranchable()

getSharedTraces

public TraceCollection getSharedTraces(View[] targets)

Returns the set of traces visible across the specified target views across the share tree of this item, as resolved to those target views The goal is to match old style server wide link visibility rules, constrained, however, by the fact that Traces are view members. In any given view, the first call to this api will typically be expensive and slow since the Traces for that view will need to be cached in client memory. All subsequent calls will be cheap, even across other items in the same view. Each call to this api requires at most one server call, to query the share tree. Note that this implementation does require a small run-time memory penalty to be paid. namely, the cache size grows with the number of traces in a view.

Parameters:

targets - the set of views from which traces are requested specify project.getAccessibleViews() for all views

Returns:

the set of visible traces returns an empty collection if targets is null or an empty array

See Also:

Project.getAccessibleViews(), View.getTraces()

getSharedChangePackages

public ChangePackageCollection getSharedChangePackages(View[] targets)

Returns the set of change packages visible across the specified target views across the share tree of this item, as resolved to those target views The goal is to match old style server wide link visibility rules, constrained, however, by the fact that ChangePackages are view members.

Parameters:

targets - the set of views from which ChangePackages are requested specify project.getAccessibleViews() for all views

Returns:

the set of visible ChangePackages returns an empty collection if targets is null or an empty array

See Also:

Project.getAccessibleViews(), View.getTraces()

getParentContainer

public ISecurableContainer getParentContainer()

If there are no access rights explicitly assigned to this object, then the effective access rights come from a parent container.

Specified by:

getParentContainer in interface ISecurable

Overrides:

getParentContainer in class ViewMember

Returns:

This object's parent container.

See Also:

ISecurableContainer

resolve

public Item resolve()

Gets a full-resolved version of this item. If the item is already fully resolved, the item itself is returned. This is a potentially expensive API, possibly involving the execution of several server commands

Returns:

a full-resolved version of this item