com.starteam
Class Item

java.lang.Object
  com.starteam.CacheRef
      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, File, Folder, Sprint, TreeItem

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.
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.
boolean	isRootShare() Determines whether or not this item is the root share of its share tree.
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, getDeletedBy, getDeletedTime, getDisplayValue, getExclusiveLocker, getFromHistory, getFromHistory, getFromHistory, getFromHistory, getHistory, getID, getIntegerArrayValue, getLocker, getMyLockType, getParentRevision, getRights, getRootObjectID, getShare, getShare, getTraces, getValue, getView, getViewMemberRevisions, getViewVersion, getVMID, hashCode, hasPermissions, isBookmarked, isBranchable, isDeleted, isDisembodied, isEqualTo, isReadOnly, isUnread, lockExclusive, lockExclusive, lockNonExclusive, modifyBookmark, modifyReadStatus, putLock, setAttachments, setBehavior, setBranchOnChange, setFixedConfiguration, setFloatingConfiguration, setRights, setValue, unlock, update, updateRevisionComment

Methods inherited from class com.starteam.VersionedObject

getBranchRevision, getComment, getDotNotation, getRevisionNumber, getViewVersion, isFromHistory, setComment

Methods inherited from class com.starteam.TrackedObject

getModifiedBy, getModifiedTime

Methods inherited from class com.starteam.LiveObject

getCreatedBy, getCreatedTime

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, isCachedProperty, isDirty, isNew, removeFromIntegerArray, setBooleanValue, setByteArrayValue, setContentValue, setDateTimeValue, setDateValue, setDoubleValue, setEnumeratedValue, setEnumeratedValues, setIntegerArrayValue, setIntegerValue, setLinkValue, setLongValue, setStringValue, setTimeSpanValue

Methods inherited from class com.starteam.CacheRef

clone

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)

isRootShare

public boolean isRootShare()

Determines whether or not this item is the root share of its share tree.

Returns:

true if this item is the root share; false otherwise.

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

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