com.starteam
Class Folder

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

All Implemented Interfaces:

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

Direct Known Subclasses:

VCMFolder

public class Folder
extends Item
implements ISecurableContainer

Represents a StarTeam Folder. A folder is an Item, i.e. it does not have a parent id property However, (sub)folders reside within folders, which makes a folder a type of hierarchy tree Folders are also containers, in that, other items reside in folders

Nested Class Summary

static class	Folder.ExcludeFlags Criteria used to exclude folders from the display
static class	Folder.Status The status of this folder; a value of the Status Property
static class	Folder.Type The Type for Folder
static class	Folder.WebCacheFolder Item accessor for cached SDK Items contained objects are obtained from the artifact cache

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

Constructor Summary

Folder(Folder parent)
Creates a new folder specifying in which folder it is to reside.

Folder(Folder parent, java.lang.String name, java.lang.String workingFolder)
Creates a new folder specifying in which folder it is to reside, its name and its working path relative to the working path of its parent folder.

Folder(Server server)
Special constructor for the root folder of a view, to be used during the creation of a project.

Method Summary

void	addFolderListener(IFolderListener listener, int depth) Adds a listener for Folder-related events.
void	addFolderUpdateListener(FolderUpdateListener listener, int depth) Listens for updates to this view's folder tree.
void	addItemListener(IItemListener listener, Item.Type type, int depth) Adds a listener for Item-related events.
void	addItemListener(IItemListener listener, Item.Type type, PropertyCollection properties, int depth) Adds a listener for Item-related events.
void	addItemUpdateListener(ItemUpdateListener listener, Item.Type type, int depth) Listens for updates to the items of a given type in this folder.
ViewMember	copy() Creates a copy of the Folder and all of its properties.
Folder	copyFolderTree() Copies a folder tree.
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.
Folder	findSubFolder(java.lang.String name) Find an immediate sub folder with the given name
java.lang.String	getAlternatePathFragment() Returns the alternate working file path to be used for this view.
boolean	getCaseSensitiveFileNames() Returns true if the names of files in this folder are case sensitive.
java.lang.String	getDefaultPathFragment() Returns this folder's specified default working path.
java.lang.String	getDescription() Returns the description of this folder.
java.lang.String	getEffectiveExcludeList() Returns the fully resolved exclude list.
boolean	getEffectiveUserVisible() Returns false if this folder or any parent is set to be not visible.
Folder.ExcludeFlags	getExcludeFlags() Returns the ExcludeFlags representing the method by which the exclude list is determined.
java.lang.String	getExcludeList() Returns the portion of the exclude list that this folder contributes.
java.lang.String	getFileEOL() Returns the end-of-line character sequence to be used for text files in this folder.
java.lang.String	getFilePath(java.lang.String fileName) For a given file name, this method returns the concatenation of the file name and the working directory path of this folder.
java.lang.String	getFolderHierarchy() Gets the fully-qualified name of this folder.
Folder	getFolderTree(Filter.Context context, int depth) Retrieves a copy of this Folder object in the specified context and depth.
boolean	getHasParentFolder() Returns true if this folder has a parent folder.
ViewMemberCollection	getHistory() Returns the past versions of this item.
ViewMemberCollection	getItems(Item.Type type) Ensures that the list of items of the specified type for this folder have been retrieved from the server and cached locally.
java.lang.String	getName() Returns the name of the folder.
File[]	getNotInViewFiles() Returns an array of "not in view" File objects in this Folder, applying exclusions as appropriate.
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 that contains this folder, or null if this is the root folder.
java.lang.String	getPath() Returns the local working folder path being used for this folder.
java.lang.String	getPathFragment() Return the path fragment to use for this folder.
Folder.Type.PropertyCollection	getProperties() Returns the properties for the folder type
java.lang.String	getQualifiedName() Gets the fully-qualified name of this folder.
ACE[]	getRights(Type type) Returns the Access Control List for items of the specified type for this folder.
Folder.Status	getStatus() Gets the status of the default working folder relative to the latest version of this folder in the repository.
Folder[]	getSubFolders() Returns the sub-folders of this folder.
boolean	getUserVisible() Returns true if items in this folder should be visible to the user.
boolean	hasPermissions(PermissionCollection permissions, Type type) Returns true if desired permissions are granted for items of the specified type for this Folder
boolean	isExcluded(java.lang.String filename) Determines if the given file name is one that will be excluded (Matches the exclude list criteria) from operations in the working directory.
boolean	isPopulated(Item.Type type) Determines whether or not this folder's 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 properties, 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.
void	remove() Removes this item from its current folder.
void	removeFolderListener(IFolderListener listener, int depth) Removes a listener for Folder-related events.
void	removeFolderUpdateListener(FolderUpdateListener listener, int depth) Removes a listener for folder update events.
void	removeItemListener(IItemListener listener, Item.Type type, int depth) Removes a listener for Item-related events.
void	removeItemUpdateListener(ItemUpdateListener listener, Item.Type type, int depth) Removes a listener for item update events.
Folder	reverseShareTo(Folder toFolder, boolean bThisFolderOnly) Reverse shares this folder to a new parent folder.
void	setAlternatePathFragment(java.lang.String path) Sets the alternate working file path to be used for this view.
void	setDefaultPathFragment(java.lang.String path) Sets this folder's working path.
void	setDescription(java.lang.String description) Sets this folder's description.
void	setExcludeFlags(Folder.ExcludeFlags flags) Sets the exclude flag for this folder.
void	setExcludeList(java.lang.String excludeList) Sets this folder's local exclude list.
void	setName(java.lang.String name) Sets the name of this folder.
void	setRights(Type type, ACE[] acl) Modifies the Access Control List for items of the specified type for this folder.
void	setUserVisible(boolean visible) Change whether or not items in this folder should be visible to the user.
java.lang.Object	setValue(Property property, java.lang.Object value) Sets the value of the specified property and return the old value.
Item	shareTo(Folder toFolder) Shares this folder to a new parent folder.
Folder	shareTo(Folder toFolder, boolean bThisFolderOnly) Shares this folder to a new parent folder.
java.lang.String	toString() Returns the name of this folder.
void	update() Stores the underlying entity in the server.
void	update(boolean bRecursive) Stores the underlying entity in the server.
void	updateFolderTree(int depth) Calls update() on itself, and recursively calls Folder.updateFolderTree() on Folders returned from getSubFolders().

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

Constructor Detail

Folder

public Folder(Server server)

Special constructor for the root folder of a view, to be used during the creation of a project. This is the only way to create the root of an initial folder tree, to be passed as a parameter to the project constructor

Parameters:

server - the server on which the root folder of this view is being constructed

Folder

public Folder(Folder parent)

Creates a new folder specifying in which folder it is to reside. Note that a valid name is required prior to update.

Parameters:

parent - the parent folder in which this new folder will reside.

Folder

public Folder(Folder parent,
              java.lang.String name,
              java.lang.String workingFolder)

Creates a new folder specifying in which folder it is to reside, its name and its working path relative to the working path of its parent folder.

Parameters:

parent - the parent folder in which this new folder will reside.

name - the name of this folder.

workingFolder - the working path for this folder, relative to its parent's working path.

Method Detail

getProperties

public Folder.Type.PropertyCollection getProperties()

Returns the properties for the folder type

Returns:

the properties for the folder type

copy

public ViewMember copy()

Creates a copy of the Folder 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 Item

Returns:

A copy of the Folder and all of its properties.

See Also:

Item.isEqualTo(com.starteam.Item)

setValue

public java.lang.Object setValue(Property property,
                                 java.lang.Object value)
                          throws NoSuchPropertyException,
                                 java.lang.ClassCastException

Sets the value of the specified property and return the old value.

Overrides:

setValue in class ViewMember

Parameters:

property - the property to set

value - the new value to set for the specified property

Returns:

the old property value

Throws:

NoSuchPropertyException - if the named property does not exist

java.lang.ClassCastException - if the value is of the wrong type for the specified property

findSubFolder

public Folder findSubFolder(java.lang.String name)

Find an immediate sub folder with the given name

Parameters:

name - the name of the subfolder

Returns:

a sub folder with the given name or NULL

getSubFolders

public Folder[] getSubFolders()

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

Returns:

the sub-folders 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()

getDescription

public java.lang.String getDescription()

Returns the description of this folder.

Returns:

the description of this folder.

See Also:

LiveObject.Type.DescriptionProperty, Folder.Type.PropertyCollection.DESCRIPTION

setDescription

public void setDescription(java.lang.String description)

Sets this folder's description.

Parameters:

description - the new description for this folder.

See Also:

LiveObject.Type.DescriptionProperty, Folder.Type.PropertyCollection.DESCRIPTION

getDefaultPathFragment

public java.lang.String getDefaultPathFragment()

Returns this folder's specified default working path. This is the FOLDER_WORKING_FOLDER property associated with this folder. The folder's fully resolved location on disk may use this value along with the values for all of its parent folders.

Returns:

this folder's specified working path.

See Also:

Folder.Type.WorkingFolderPathProperty.NAME, Folder.Type.WorkingFolderPathProperty.NAME, Folder.getPathFragment(), Folder.getAlternatePathFragment()

setDefaultPathFragment

public void setDefaultPathFragment(java.lang.String path)

Sets this folder's working path. This value should be relative to the value for its parent folders.

Parameters:

path - the new working path for this folder.

See Also:

LiveObject.Type.WorkingFolderProperty, Folder.getPathFragment(), Folder.getAlternatePathFragment()

getAlternatePathFragment

public java.lang.String getAlternatePathFragment()

Returns the alternate working file path to be used for this view. This is the value stored client-side as an override to the default path.

Returns:

the alternate or overridden working path for this folder.

See Also:

Folder.getPathFragment(), Folder.getDefaultPathFragment()

setAlternatePathFragment

public void setAlternatePathFragment(java.lang.String path)

Sets the alternate working file path to be used for this view. This method only sets the alternate value for the local Folder object and is not persisted in any way. If set, this value will override the Folder's default path fragment.

Parameters:

path - the alternate working path to use for this folder.

See Also:

Folder.getPathFragment(), Folder.getDefaultPathFragment()

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.

Returns:

the path fragment to use for this folder.

See Also:

Folder.getDefaultPathFragment(), Folder.getAlternatePathFragment()

getStatus

public Folder.Status getStatus()

Gets the status of the default working folder relative to the latest version of this folder in the repository.

Returns:

The current status of this folder.

See Also:

Folder.Status

getPath

public java.lang.String getPath()

Returns the local working folder path being used for this folder. This path is the concatenation of either the default path fragment or the alternate path fragment with the path of this folder's parent folder or the path of the view if this folder has no parent. A non-null alternate path fragment takes precedence over a default path fragment.

Returns:

the local working folder path being used for this folder.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

Folder.getPathFragment(), Folder.getDefaultPathFragment(), Folder.getAlternatePathFragment(), ViewMember.isDisembodied()

getExcludeFlags

public Folder.ExcludeFlags getExcludeFlags()

Returns the ExcludeFlags representing the method by which the exclude list is determined.

Returns:

the exclude type being used for this folder's exclude list

See Also:

Folder.ExcludeFlags.NONE, Folder.ExcludeFlags.LOCAL, Folder.ExcludeFlags.INHERIT

setExcludeFlags

public void setExcludeFlags(Folder.ExcludeFlags flags)

Sets the exclude flag for this folder. This is the method by which the exclude list is determined.

Parameters:

flags - the exclude type to be used for this folder's exclude list

See Also:

Folder.ExcludeFlags.NONE, Folder.ExcludeFlags.LOCAL, Folder.ExcludeFlags.INHERIT

getExcludeList

public java.lang.String getExcludeList()

Returns the portion of the exclude list that this folder contributes. Use getEffectiveExcludeList to get the full exclude list which may include specifications inherited from the parent folder.

Returns:

the portion of the exclude list that this folder contributes.

See Also:

Folder.getEffectiveExcludeList()

setExcludeList

public void setExcludeList(java.lang.String excludeList)

Sets this folder's local exclude list.

Parameters:

excludeList - this folder's local exclude list

See Also:

Folder.getExcludeList(), Folder.getEffectiveExcludeList(), Folder.getExcludeFlags()

getFilePath

public java.lang.String getFilePath(java.lang.String fileName)

For a given file name, this method returns the concatenation of the file name and the working directory path of this folder.

Parameters:

fileName - the name of the local file.

Returns:

the full local working path to the specified file name

getFolderHierarchy

public java.lang.String getFolderHierarchy()

Gets the fully-qualified name of this folder. The names of this folder and 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 folder.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

Folder.getName(), Folder.getQualifiedName(), ViewMember.isDisembodied()

getQualifiedName

public java.lang.String getQualifiedName()

Gets the fully-qualified name of this folder. The names of this folder and all parent folders up to the root are included, separated by the backslash character ("\") on all platforms. There is no terminating backslash.

Returns:

The fully-qualified name of this folder.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

Folder.getName(), Folder.getFolderHierarchy(), ViewMember.isDisembodied()

isExcluded

public boolean isExcluded(java.lang.String filename)

Determines if the given file name is one that will be excluded (Matches the exclude list criteria) from operations in the working directory. Most StarTeam clients make use of a folder's exclude list by not allowing excluded files to be added to the repository. Nothing in the StarTeam SDK prevents any file being added to a repository it must be implemented as specific client-side logic. For example, the StarTeam GUI will not display any excluded files whose status is "Not In View" in the list control.

Parameters:

filename - the name of the file to be checked for exclusion

Returns:

true if the specified file name should be considered as excluded from being added to the StarTeam repository/

See Also:

Folder.getEffectiveExcludeList()

getEffectiveExcludeList

public java.lang.String getEffectiveExcludeList()

Returns the fully resolved exclude list. This may be the concatenation of this folder's exclude list with its parent exclude list depending on the exclude list types.

Returns:

the fully resolved exclude list for this folder.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

Folder.getExcludeFlags(), ViewMember.isDisembodied()

getName

public java.lang.String getName()

Returns the name of the folder.

Returns:

the name of the folder.

See Also:

Folder.Type.PropertyCollection.NAME, LiveObject.Type.NameProperty

setName

public void setName(java.lang.String name)

Sets the name of this folder.

Parameters:

name - the new folder name.

See Also:

Folder.Type.PropertyCollection.NAME, LiveObject.Type.NameProperty

getParentFolder

public Folder getParentFolder()

Returns the folder that contains this folder, or null if this is the root folder.

Overrides:

getParentFolder in class Item

Returns:

this folder's parent folder or null if root.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

ViewMember.isDisembodied()

getHasParentFolder

public boolean getHasParentFolder()

Returns true if this folder has a parent folder.

Returns:

true if this folder has a parent folder.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

ViewMember.isDisembodied()

getFileEOL

public java.lang.String getFileEOL()

Returns the end-of-line character sequence to be used for text files in this folder.

Returns:

The end-of-line character sequence to be used for text files in this folder.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

ViewMember.isDisembodied(), Platform.EOL.CRLF, Platform.EOL.CR, Platform.EOL.LF

getCaseSensitiveFileNames

public boolean getCaseSensitiveFileNames()

Returns true if the names of files in this folder are case sensitive.

Returns:

True if the names of files in this folder are case sensitive, and false otherwise.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

ViewMember.isDisembodied()

getFolderTree

public Folder getFolderTree(Filter.Context context,
                            int depth)
                     throws java.io.IOException

Retrieves a copy of this Folder object in the specified context and depth. If the LOCAL context is specified, Not-In-View folders are included in the tree

Parameters:

context - one of these values: Filter.Context.SERVER, Filter.Context.LOCAL and Filter.Context.BOTH.

depth - the depth of levels of Folders affected.

Returns:

a copy of this Folder object in the specified context and depth.

Throws:

java.io.IOException

See Also:

Filter.Context.SERVER, Filter.Context.LOCAL, Filter.Context.BOTH, Folder.getSubFolders()

updateFolderTree

public void updateFolderTree(int depth)

Calls update() on itself, and recursively calls Folder.updateFolderTree() on Folders returned from getSubFolders().

Parameters:

depth - the depth of levels of Folders that's affected.

See Also:

Folder.getSubFolders()

getNotInViewFiles

public File[] getNotInViewFiles()
                         throws java.io.IOException

Returns an array of "not in view" File objects in this Folder, applying exclusions as appropriate.

Returns:

an array of "not in view" File objects in this Folder, applying exclusions as appropriate.

Throws:

java.io.IOException

getHistory

public ViewMemberCollection getHistory()

Returns the past versions of this item.

Overrides:

getHistory in class ViewMember

Returns:

the past versions of this item.

remove

public void remove()

Removes this item from its current folder. This is not quite a delete operation because other items might refer to the same underlying object.

Overrides:

remove in class Item

shareTo

public Item shareTo(Folder toFolder)

Shares this folder to a new parent folder. In addition to the folder itself, all child folders and all items contained within the folders are shared.

If this is a deleted folder, shareTo() will create a new folder 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.

Overrides:

shareTo in class Item

Parameters:

toFolder - The new parent folder.

Returns:

The folder object representing the newly shared folder.

Throws:

DisembodiedException - if the target folder is disembodied.

See Also:

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

shareTo

public Folder shareTo(Folder toFolder,
                      boolean bThisFolderOnly)

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

If bThisFolderOnly is true, then this folder is shared without sharing any of its contained items. Such shares are supported by StarTeam server versions 9.0 and later. On older servers, this is simulated by first moving the contained items to a temporary folder, and moving them back after the share.

Parameters:

toFolder - The new parent folder.

bThisFolderOnly - true to share this folder only; false to share this folder, all of its children to any depth, and all of the items contained within those folders.

Returns:

The folder object representing the newly shared folder.

Throws:

DisembodiedException - if the target folder is disembodied.

See Also:

Folder.shareTo(Folder)

reverseShareTo

public Folder reverseShareTo(Folder toFolder,
                             boolean bThisFolderOnly)

Reverse shares this folder to a new parent folder.

If bThisFolderOnly is true, then this folder is shared without sharing any of its contained items. Such shares are supported by StarTeam server versions 9.0 and later. On older servers, this is simulated by first moving the contained items to a temporary folder, and moving them back after the share.

Parameters:

toFolder - The new parent folder.

bThisFolderOnly - true to share this folder only; false to share this folder, all of its children to any depth, and all of the items contained within those folders.

Returns:

The folder object representing the newly shared folder.

Throws:

DisembodiedException - if the target folder is disembodied.

See Also:

Item.reverseShareTo(Folder)

getItems

public ViewMemberCollection getItems(Item.Type type)

Ensures that the list of items of the specified type for this folder have been retrieved from the server and cached locally. The list of items is retrieved from the server only if it has not already been retrieved. Therefore, the list of items may or may not be up-to-date with respect to the latest information on the server. To ensure that the list is up-to-date, use refresh(). getItems() does not retrieve any item properties. To ensure that a specific set of properties is available, use populate().

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:

CacheService.populate(), Folder.isPopulated(com.starteam.Item.Type), CacheService.refresh(), ViewMember.isDisembodied()

isPopulated

public boolean isPopulated(Item.Type type)

Determines whether or not this folder's items have been populated.

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:

Folder.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.

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:

Folder.getItems(com.starteam.Item.Type), CacheService.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.

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 sub-folders 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:

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

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

Parameters:

type - Type the type of Item for which the count is to be retrieved

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

Returns:

long the number of items reachable from here

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.

Parameters:

type - The type of the items to be examined.

properties - 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 sub-folders to be examined.

Returns:

true if a refresh is required; false otherwise.

Throws:

DisembodiedException - if the Folder is disembodied.

See Also:

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

refreshItems

public void refreshItems(Item.Type type,
                         PropertyCollection properties,
                         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 populate(). 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.

Parameters:

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

properties - 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:

Folder.getItems(com.starteam.Item.Type), CacheService.populate(), Folder.isRefreshItemsRequired(com.starteam.Item.Type, com.starteam.PropertyCollection, int), Folder.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).

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:

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

hasPermissions

public boolean hasPermissions(PermissionCollection permissions,
                              Type type)

Returns true if desired permissions are granted for items of the specified type for this Folder

Specified by:

hasPermissions in interface ISecurableContainer

Parameters:

permissions - the desired permissions

type - the type for access to be tested on

Returns:

true if all the requested permissions are granted; false if at least one of the requested permissions is denied.

See Also:

Permission

getRights

public ACE[] getRights(Type type)

Returns the Access Control List for items of the specified type for this folder. This will return null if this folder has no access control list for the specified type. The access control list is not cached, and will be fetched from the server on demand Cached lists are accessible via the AccessRightsManager

Specified by:

getRights in interface ISecurableContainer

Parameters:

type - the name of the type being controlled by the returned ACL

Returns:

the access control list for this folder or NULL.

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

AccessRightsManager.getRights(ISecurableContainer,Type), ViewMember.isDisembodied(), Type

setRights

public void setRights(Type type,
                      ACE[] acl)

Modifies the Access Control List for items of the specified type for this folder. If the ACL is null then the access control list for items of the specified type will be dropped.

Specified by:

setRights in interface ISecurableContainer

Parameters:

type - the name of the type being controlled by the returned ACL

acl - the new access control list for items of the specified type in this folder

Throws:

DisembodiedException - if the Folder is disembodied

See Also:

ViewMember.isDisembodied()

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. Calling this method is equivalent to calling Folder.update( true ).

Overrides:

update in class ViewMember

Throws:

java.lang.IllegalStateException - if this item was obtained from history

See Also:

VersionedObject.isFromHistory()

update

public void update(boolean bRecursive)

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

Parameters:

bRecursive - if true, it will cause update() to trickle down to the sub-folders

Throws:

java.lang.IllegalStateException - if this item was obtained from history

See Also:

VersionedObject.isFromHistory()

toString

public java.lang.String toString()

Returns the name of this folder.

Overrides:

toString in class Item

Returns:

the name of this folder.

getUserVisible

public boolean getUserVisible()

Returns true if items in this folder should be visible to the user. Typically, a UI should not display the items in an invisible folder. The value for this folder may have been set upon opening a view based on client settings.

See Also:

StarTeamClientOptions.getFolderUserVisible(com.starteam.Folder), StarTeamClientOptions.setFolderUserVisible(com.starteam.util.GUID, int, boolean)

setUserVisible

public void setUserVisible(boolean visible)

Change whether or not items in this folder should be visible to the user. Typically, a UI should not display the items in an invisible folder. This method has no side effects other than to set the flag for this folder only.

Parameters:

visible - true if the items in this folder should be presented to the user, false otherwise

See Also:

StarTeamClientOptions.getFolderUserVisible(com.starteam.Folder), StarTeamClientOptions.setFolderUserVisible(com.starteam.util.GUID, int, boolean)

getEffectiveUserVisible

public boolean getEffectiveUserVisible()

Returns false if this folder or any parent is set to be not visible.

Returns:

false if this folder or any parent is set to be not visible

See Also:

Folder.getUserVisible(), Folder.setUserVisible(boolean)

copyFolderTree

public Folder copyFolderTree()

Copies a folder tree. Does not populate any properties or copy any cached items.

Returns:

A copy of this folder and its sub-folders.

See Also:

ViewMember.copy()

addFolderListener

public void addFolderListener(IFolderListener listener,
                              int depth)

Adds a listener for Folder-related events.

In order to handle events, an application must enable MPX.

Parameters:

listener - Application-specific event handler for Folder-related events. Any class that implements the FolderListener or FolderTreeListener interface (or both) is supported.

depth - Indicates how much of the folder tree will be monitored. Zero indicates just this folder should be monitored; 1 indicates that this folder and its immediate child folders should be monitored; -1 indicates that this folder and all child folders at any depth should be monitored.

See Also:

IFolderListener, FolderListener, FolderTreeListener, Folder.removeFolderListener(com.starteam.events.IFolderListener, int), Server.enableMPX()

removeFolderListener

public void removeFolderListener(IFolderListener listener,
                                 int depth)

Removes a listener for Folder-related events.

Parameters:

listener - Previously-registered event handlers for Folder-related events.

depth - The depth used when the event handlers were registered.

See Also:

IFolderListener, Folder.addFolderListener(com.starteam.events.IFolderListener, int)

addFolderUpdateListener

public void addFolderUpdateListener(FolderUpdateListener listener,
                                    int depth)

Listens for updates to this view's folder tree.

Similar to addFolderListener(), except that events are triggered by explicit operations performed by the client application. For example, calling View.refreshFolders(), Folder.update() or Folder.remove() might each trigger update events.

MPX is not required to receive folder update events.

Parameters:

listener - Application-specific event handler for folder update events.

depth - Indicates how much of the folder tree will be monitored. Zero indicates just this folder should be monitored; 1 indicates that this folder and its immediate child folders should be monitored; -1 indicates that this folder and all child folders at any depth should be monitored.

See Also:

FolderListener, Folder.removeFolderUpdateListener(com.starteam.events.FolderUpdateListener, int), Folder.addFolderListener(com.starteam.events.IFolderListener, int)

removeFolderUpdateListener

public void removeFolderUpdateListener(FolderUpdateListener listener,
                                       int depth)

Removes a listener for folder update events.

Parameters:

listener - Previously-registered event handler for folder update events.

depth - The depth used when the event handlers were registered.

See Also:

FolderListener, Folder.addFolderUpdateListener(com.starteam.events.FolderUpdateListener, int)

addItemListener

public void addItemListener(IItemListener listener,
                            Item.Type type,
                            int depth)

Adds a listener for Item-related events.

If listener is an ItemListener, then Item objects passed to application event handlers may not have fully-populated properties. The only properties that are guaranteed to be populated in all cases are the Item's descriptors.

In order to handle events, an application must enable MPX.

Parameters:

listener - Application-specific event handler for Item-related events. Any class that implements one (or more) of the IItemListener interfaces is supported.

type - The Type of the items of interest.

depth - Indicates how much of the folder tree will be monitored. Zero indicates just this folder should be monitored; 1 indicates that this folder and its immediate child folders should be monitored; -1 indicates that this folder and all child folders at any depth should be monitored.

See Also:

IItemListener, ItemListener, ItemIDListener, ItemListListener, NotificationListener, Folder.addItemListener(IItemListener,Item.Type,PropertyCollection,int), Folder.removeItemListener(com.starteam.events.IItemListener, com.starteam.Item.Type, int), Server.enableMPX()

addItemListener

public void addItemListener(IItemListener listener,
                            Item.Type type,
                            PropertyCollection properties,
                            int depth)

Adds a listener for Item-related events.

In order to handle events, an application must enable MPX.

Parameters:

listener - Application-specific event handler for Item-related events. Any class that implements one (or more) of the IItemListener interfaces is supported.

type - The Type of the items of interest.

properties - - properties that must always be populated whenever an Item object is passed to an application event-handler. Relevant only when listener is an ItemListener.

depth - Indicates how much of the folder tree will be monitored. Zero indicates just this folder should be monitored; 1 indicates that this folder and its immediate child folders should be monitored; -1 indicates that this folder and all child folders at any depth should be monitored.

See Also:

IItemListener, ItemListener, ItemIDListener, ItemListListener, NotificationListener, Folder.addItemListener(IItemListener,Item.Type,int), Folder.removeItemListener(com.starteam.events.IItemListener, com.starteam.Item.Type, int), Server.enableMPX()

removeItemListener

public void removeItemListener(IItemListener listener,
                               Item.Type type,
                               int depth)

Removes a listener for Item-related events.

Parameters:

listener - Previously-registered event handlers for Item-related events.

type - The Type of the items of interest.

depth - Indicates how much of the folder tree will be monitored.

See Also:

IItemListener, Folder.addItemListener(IItemListener,Item.Type,int)

addItemUpdateListener

public void addItemUpdateListener(ItemUpdateListener listener,
                                  Item.Type type,
                                  int depth)

Listens for updates to the items of a given type in this folder.

Similar to addItemListener(), except that events are triggered by explicit operations performed by the client application. For example, calling Folder.refreshItems(), Item.update() or Item.remove() might each trigger update events.

MPX is not required to receive item update events.

Parameters:

listener - Application-specific event handler for item update events.

type - The Type of the items of interest.

depth - Indicates how much of the folder tree will be monitored. Zero indicates just this folder should be monitored; 1 indicates that this folder and its immediate child folders should be monitored; -1 indicates that this folder and all child folders at any depth should be monitored.

See Also:

ItemUpdateListener, Folder.removeItemUpdateListener(com.starteam.events.ItemUpdateListener, com.starteam.Item.Type, int), View.addItemUpdateListener(com.starteam.events.ItemUpdateListener, com.starteam.Item.Type), Folder.addItemListener(com.starteam.events.IItemListener, com.starteam.Item.Type, int)

removeItemUpdateListener

public void removeItemUpdateListener(ItemUpdateListener listener,
                                     Item.Type type,
                                     int depth)

Removes a listener for item update events.

Parameters:

listener - Previously-registered event handler for item update events.

type - The Type of the items of interest.

depth - Indicates how much of the folder tree will be monitored.

See Also:

ItemUpdateListener, Folder.addItemUpdateListener(com.starteam.events.ItemUpdateListener, com.starteam.Item.Type, int)

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

Specified by:

getParentContainer in interface ISecurableContainer

Overrides:

getParentContainer in class Item

Returns:

This object's parent container.

See Also:

ISecurableContainer