com.starteam.viewcomparemerge
Class VCMFolder

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

All Implemented Interfaces:

ISecurable, ISecurableContainer, Lockable, LockableObject, java.lang.Cloneable

public final class VCMFolder
extends Folder

A folder belonging to the Merge Preview It has all the characteristics of a regular StarTeam Folder, and describes the Preview State of its constituent Items and/or Sub-Folders

See Also:

VCMFolder.PreviewState

Nested Class Summary

static class

VCMFolder.PreviewState The preview state represents a highest precedence summary of all contained items and sub-folders and their contents.

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

Folder.ExcludeFlags, Folder.Status, Folder.Type, Folder.WebCacheFolder

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

Item.WebCacheItem

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

long	countItems(Item.Type type, int depth) Returns a count of the number of items (of a given type) reachable from this folder to the given depth
void	discardItems(Item.Type type, int depth) Discards cached items of the specified type in this folder.
ViewMemberCollection	getItems(Item.Type type) Returns the list of items of the specified type getItems() does not retrieve any item properties.
java.lang.String	getPathFragment() Return the path fragment to use for this folder.
VCMFolder.PreviewState	getPreviewState(Item.Type type) Returns the preview state of this folder, which is an aggregate of the states of the constituent elements (items & sub-folders) of this folder
Folder[]	getSubFolders() Returns the subfolders of this folder.
boolean	isPopulated(Item.Type type) Returns whether or not the target items have been populated.
boolean	isRefreshItemsRequired(Item.Type type, PropertyCollection properties, int depth) Determines whether or not the items of the given type need to be refreshed.
void	populate(Item.Type type, int depth) Ensures that the items of the specified type have been retrieved from the server and cached locally.
void	populate(Item.Type type, PropertyCollection properties, int depth) Ensures that the items of the specified type have been retrieved from the server and cached locally.
void	refreshItems(Item.Type type, PropertyCollection pc, int depth) Ensures that the latest list of items of the specified type for this folder has been retrieved from the server and cached locally.

Methods inherited from class com.starteam.Folder

addFolderListener, addFolderUpdateListener, addItemListener, addItemListener, addItemUpdateListener, copy, copyFolderTree, findSubFolder, getAlternatePathFragment, getCaseSensitiveFileNames, getDefaultPathFragment, getDescription, getEffectiveExcludeList, getEffectiveUserVisible, getExcludeFlags, getExcludeList, getFileEOL, getFilePath, getFolderHierarchy, getFolderTree, getHasParentFolder, getHistory, getName, getNotInViewFiles, getParentContainer, getParentFolder, getPath, getProperties, getQualifiedName, getRights, getStatus, getUserVisible, hasPermissions, isExcluded, remove, removeFolderListener, removeFolderUpdateListener, removeItemListener, removeItemUpdateListener, reverseShareTo, setAlternatePathFragment, setDefaultPathFragment, setDescription, setExcludeFlags, setExcludeList, setName, setRights, setUserVisible, setValue, shareTo, shareTo, toString, update, update, updateFolderTree

Methods inherited from class com.starteam.Item

deleteMergePoint, getCommonAncestor, getDebugString, getDisplayableProperties, getItemID, getMergeHistory, getNewRevisionComment, getParentFolderHierarchy, getParentFolderName, getParentFolderPath, getParentFolderQualifiedName, getSharedChangePackages, getSharedTraces, isEqualTo, isReverseShareRecommended, moveTo, recordMergePoint, resolve, resolveMergePoint, resolveMergePointEx, reverseShareTo, reverseShareTo, smartShareTo

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, 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, unlock, 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.ISecurableContainer

getID, getServer, isDeleted

Methods inherited from interface com.starteam.ISecurable

getServer, getType

Method Detail

getItems

public ViewMemberCollection getItems(Item.Type type)

Returns the list of items of the specified type getItems() does not retrieve any item properties. To ensure that a specific set of properties is avaliable, use populateNow().

Overrides:

getItems in class Folder

Parameters:

type - The type of the items to be retrieved.

Returns:

The items of the specified type in this folder.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

VCMFolder.isPopulated(com.starteam.Item.Type), ViewMember.refresh(), ViewMember.isDisembodied()

getPathFragment

public java.lang.String getPathFragment()

Return the path fragment to use for this folder. If an alternate path fragment is set then it will be used instead of the default path fragment.

Overrides:

getPathFragment in class Folder

Returns:

the path fragment to use for this folder.

See Also:

Folder.getDefaultPathFragment(), Folder.getAlternatePathFragment()

getSubFolders

public Folder[] getSubFolders()

Returns the subfolders of this folder. Will not return null but may return an empty array if the folder has no subfolders.

Overrides:

getSubFolders in class Folder

Returns:

the subfolders of this folder. Will not return null but may return an empty array if the folder has no subfolders.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

ViewMember.isDisembodied()

isPopulated

public boolean isPopulated(Item.Type type)

Returns whether or not the target items have been populated.

Overrides:

isPopulated in class Folder

Parameters:

type - The type of the items to be tested.

Returns:

true if the items of the given type have been populated in this folder; false if they have not yet been populated.

See Also:

VCMFolder.getItems(com.starteam.Item.Type)

populate

public void populate(Item.Type type,
                     PropertyCollection properties,
                     int depth)

Ensures that the items of the specified type have been retrieved from the server and cached locally. Also ensures that the specified properties have been retrieved for each item.

populate() does not retrieve any items or properties that have already been cached. Therefore, the item and property information may or may not be up-to-date with respect to the latest information on the server. To ensure that the item and property information is up-to-date, use refresh().

When an application attempts to access the value of a given property of an item, and that property has not yet been retrieved from the server, a command is issued to the server to retrieve all the properties of that item and cache them locally. For applications that examine many items, it is much more efficient to populate all the required properties up front, using populate().

It is sometimes difficult to determine exactly which item properties are used by a given application. If performance problems cause you to suspect that there is a property that has not been populated correctly, you can use NetMonitor to help diagnose the problem. If accessing a specific item property results in a fetch from the server, NetMonitor will display a message indicating which property caused the fetch.

Overrides:

populate in class Folder

Parameters:

type - The type of the items to be retrieved.

properties - The properties whose values are to be retrieved. Specifying null causes all properties to be retrieved. Specifying a client-calculated property causes all dependent properties to be included.

depth - The number of levels deep in the folder tree that child folders should also be populated. A value of 0 causes only this folder to be populated. A positive value n will cause this folder and all subfolders up to n levels deeper to be populated. A negative value causes this folder and all subfolders to be populated.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

VCMFolder.getItems(com.starteam.Item.Type), ViewMember.refresh(), ViewMember.isDisembodied()

populate

public void populate(Item.Type type,
                     int depth)

Ensures that the items of the specified type have been retrieved from the server and cached locally. Also ensures that the specified properties have been retrieved for each item.

populate() does not retrieve any items or properties that have already been cached. Therefore, the item and property information may or may not be up-to-date with respect to the latest information on the server. To ensure that the item and property information is up-to-date, use refresh().

When an application attempts to access the value of a given property of an item, and that property has not yet been retrieved from the server, a command is issued to the server to retrieve all the properties of that item and cache them locally. For applications that examine many items, it is much more efficient to populate all the required properties up front, using populate().

It is sometimes difficult to determine exactly which item properties are used by a given application. If performance problems cause you to suspect that there is a property that has not been populated correctly, you can use NetMonitor to help diagnose the problem. If accessing a specific item property results in a fetch from the server, NetMonitor will display a message indicating which property caused the fetch.

Overrides:

populate in class Folder

Parameters:

type - The type of the items to be retrieved.

depth - The number of levels deep in the folder tree that child folders should also be populated. A value of 0 causes only this folder to be populated. A positive value n will cause this folder and all subfolders up to n levels deeper to be populated. A negative value causes this folder and all subfolders to be populated.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

VCMFolder.getItems(com.starteam.Item.Type), ViewMember.refresh(), ViewMember.isDisembodied()

isRefreshItemsRequired

public boolean isRefreshItemsRequired(Item.Type type,
                                      PropertyCollection properties,
                                      int depth)

Determines whether or not the items of the given type need to be refreshed. A refresh is required if the cached items are not known to be up-to-date with respect to the latest information in the repository. Specifically, a refresh is required if:

• MPX is not enabled, or
• At least one new item has been added since the last refresh, or
• At least one item has been deleted since the last refresh, or
• The value of one or more of the specified properties is not yet known for at least one of the items, or
• The properties of at least one item have changed since the last refresh.

Overrides:

isRefreshItemsRequired in class Folder

Parameters:

type - The type of the items to be examined.

properties - The names of the properties whose values are to be examined. Specifying null causes all properties to be examined. Specifying a client-calculated property causes all dependent properties to be examined.

depth - The number of levels deep in the folder tree that child folders should also be examined. A value of 0 causes only this folder to be examined. A positive value n will cause this folder and all subfolders up to n levels deeper to be examined. A negative value causes this folder and all subfolders to be examined.

Returns:

true.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

VCMFolder.refreshItems(com.starteam.Item.Type, com.starteam.PropertyCollection, int), ViewMember.isDisembodied(), Server.enableMPX()

refreshItems

public void refreshItems(Item.Type type,
                         PropertyCollection pc,
                         int depth)

Ensures that the latest list of items of the specified type for this folder has been retrieved from the server and cached locally. Also ensures that the latest values of the specified properties have been retrieved for each item.

refreshItems() is similar to populateNow(). However, refreshItems() ensures that the list of items and the properties of each item are up-to-date with respect to the latest information on the server.

refreshItems() re-uses existing Item objects whenever possible, changing cached property values as necessary to bring older Items up-to-date.

When MPX is enabled, refreshItems() is optimized to avoid unnecessary server commands.

Overrides:

refreshItems in class Folder

Parameters:

type - The type name of the items to be refreshed.

pc - The names of the properties whose values are to be refreshed. Specifying null causes all properties to be refreshed. Specifying a client-calculated property causes all dependent properties to be refreshed.

depth - The number of levels deep in the folder tree that child folders should also be refreshed. A value of 0 causes only this folder to be refreshed. A positive value n will cause this folder and all subfolders up to n levels deeper to be refreshed. A negative value causes this folder and all subfolders to be refreshed.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

VCMFolder.getItems(com.starteam.Item.Type), VCMFolder.isRefreshItemsRequired(com.starteam.Item.Type, com.starteam.PropertyCollection, int), VCMFolder.discardItems(Item.Type, int), ViewMember.isDisembodied(), Server.enableMPX()

discardItems

public void discardItems(Item.Type type,
                         int depth)

Discards cached items of the specified type in this folder. Subsequent calls to getItems will re-fetch the items from the server (even when MPX is enabled).

Overrides:

discardItems in class Folder

Parameters:

type - The type of the items to be discarded.

depth - The number of levels deep in the folder tree that items should also be discarded. A value of 0 causes only the items in this folder to be discarded. A positive value n will cause the items in this folder and in all subfolders up to n levels deeper to be discarded. A negative value causes the items in this folder and in all subfolders to be discarded.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

VCMFolder.populate(Item.Type, PropertyCollection, int), VCMFolder.refreshItems(Item.Type, PropertyCollection, int), ViewMember.isDisembodied(), Server.enableMPX()

countItems

public long countItems(Item.Type type,
                       int depth)

Returns a count of the number of items (of a given type) reachable from this folder to the given depth

Overrides:

countItems in class Folder

Parameters:

type - Type the type of Item for which the count is to be retrieved If verbosePreview is set to true, then the returned count includes all unchanged items of the specified type

depth - int The number of levels deep in the folder tree that child folders should also be populated. A value of 0 causes only this folder to be populated. A positive value n will cause this folder and all subfolders up to n levels deeper to be populated. A negative value causes this folder and all subfolders to be populated.

Returns:

long the number of items reachable from here

See Also:

Session.isVerbosePreview

getPreviewState

public VCMFolder.PreviewState getPreviewState(Item.Type type)

Returns the preview state of this folder, which is an aggregate of the states of the constituent elements (items & sub-folders) of this folder

Parameters:

type - Type the type for which to request the state (use null for all types).

Returns:

PreviewState the preview State of this folder