com.starbase.starteam
Class Folder

java.lang.Object
  |
  +--com.starbase.starteam.CacheRef
        |
        +--com.starbase.starteam.NamedCacheRef
              |
              +--com.starbase.starteam.TypedResource
                    |
                    +--com.starbase.starteam.SimpleTypedResource
                          |
                          +--com.starbase.starteam.Item
                                |
                                +--com.starbase.starteam.Folder

All Implemented Interfaces:

java.lang.Cloneable, ISecurable, ISecurableContainer, ISecurableObject

Direct Known Subclasses:

VCMFolder

public class Folder

extends Item

implements ISecurableContainer

Represents a StarTeam Folder.

Nested Class Summary

Nested classes inherited from class com.starbase.starteam.Item

Item.LockType

Field Summary

static java.lang.String	EOL_CR Carriage-return end-of-line sequence (i.e., "\r").
static java.lang.String	EOL_CRLF Carriage-return + Line-feed end-of-line sequence (i.e., "\r\n").
static java.lang.String	EOL_LF Line-feed end-of-line sequence (i.e., "\n").
static int	EXCLUDE_INHERIT A flag that indcates that this folder inherits its exclude list from its parent folder and concatenates its own list if any.
static int	EXCLUDE_LOCAL A flag that indicates that this folder is using an exclude list specifically designated for this folder.
static int	EXCLUDE_NONE A flag that indicated this folder does not use any exclude list.

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

Item	add(Item child) Deprecated. Instead of folder.add(item), use item.shareTo(folder). Note that Folder.add() does not work correctly for TreeItems, because it does not share child items.
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, Type type, int depth) Adds a listener for Item-related events.
void	addItemListener(IItemListener listener, Type type, java.lang.String[] propertyNames, int depth) Adds a listener for Item-related events.
void	addItemUpdateListener(ItemUpdateListener listener, Type type, int depth) Listens for updates to the items of a given type in this folder.
Item	copy() Creates a copy of this Folder, with folder properties fully populated.
Folder	copyFolderTree() Copies a folder tree.
long	countItems(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(java.lang.String typeName, int depth) Discards cached items of the specified type in this folder.
java.util.Enumeration	enumerateItems(java.lang.String typeName) Returns an Enumeration of the items of the specified type that exist in this folder.
boolean	equals(java.lang.Object source) returns true if this object instance is equal to the source
AclEntry[]	getACL() Returns the Access Control List for this folder.
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.
AclEntry[]	getContainerLevelACL(java.lang.String typeName) Returns the Access Control List for items of the specified type for this folder.
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	getDotNotation() Returns the dot notation identification of this version.
int	getExcludeFlags() Returns an int 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(int context, int depth) Retrieves a copy of this Folder object in the specified context and depth.
Item[]	getHistory() Returns the past versions of this item.
Item[]	getItems(java.lang.String typeName) Ensures that the list of items of the specified type for this folder have been retrieved from the server and cached locally.
ItemList	getList(java.lang.String typeName) Returns an ItemList of the specified item types in this folder.
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 file path being used for this folder.
java.lang.String	getPathFragment() Return the path fragment to use for this folder.
java.lang.String	getQualifiedName() Gets the fully-qualified name of this folder.
int	getSubFolderCount() Returns the number of sub folders for this folder.
Folder[]	getSubFolders() Returns the subfolders of this folder.
boolean	getUserVisible() Returns true if items in this folder should be visible to the user.
int	hashCode() returns a unique hash for all instances of this type
boolean	hasParentFolder() Returns true if this folder has a parent folder.
boolean	hasPermission(int permissions, java.lang.String typeName) Returns true if desired permissions are granted for items of the specified type for this Folder
boolean	isEqualTo(Item item) Compares the properties of two Folders.
boolean	isExcluded(java.lang.String filename) Determines if the given file name is one that will be excluded (matcthes the exclude list criteria) from operations in the working directory.
boolean	isPopulated(java.lang.String typeName) Determines whether or not this folder's items have been populated.
boolean	isRefreshItemsRequired(java.lang.String typeName, java.lang.String[] propertyNames, int depth) Determines whether or not the items of the given type need to be refreshed.
void	move(Folder toFolder) Deprecated. Use moveTo().
void	moveTo(Folder toFolder) Moves this folder to the specified folder.
void	populateAsNeeded(java.lang.String typeName, java.lang.String[] propertyNames, int chunkSize) Deprecated.
void	populateInBackground(java.lang.String typeName, java.lang.String[] propertyNames, int chunkSize) Similar to populateNow().
void	populateNow(java.lang.String typeName, java.lang.String[] propertyNames, int depth) Ensures that the items of the specified type have been retrieved from the server and cached locally.
java.lang.Object	put(java.lang.String propertyName, java.lang.Object value) Sets the value of the specified property and return the old value.
java.lang.Object	putByPropertyID(int propertyID, java.lang.Object value) Set the value of the property specified by its property ID and return the old value.
ForeignRefreshResult	refreshForeignFiles(int depth) Refresh the foreign files in this folder, and its child folders depending on the specified "depth."
void	refreshItems(java.lang.String typeName, java.lang.String[] propertyNames, 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, Type type, int depth) Removes a listener for Item-related events.
void	removeItemUpdateListener(ItemUpdateListener listener, Type type, int depth) Removes a listener for item update events.
java.lang.String	resolveExcludeList() Returns the fully resolved exclude list.
boolean	resolveUserVisible() Returns false if this folder or any parent is set to be not visible.
Folder	reverseShareTo(Folder toFolder, boolean bThisFolderOnly) Reverse shares this folder to a new parent folder.
void	setACL(AclEntry[] acl) Modify the Access Control List for this folder.
void	setAlternatePathFragment(java.lang.String path) Sets the alternate working file path to be used for this view.
void	setContainerLevelACL(AclEntry[] acl, java.lang.String typeName) Modifies the Access Control List for items of the specified type for this folder.
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(int flag) 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	setUserVisible(boolean visible) Change whether or not items in this folder should be visible to the user.
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	updateFolderTree(int depth) Calls update() on itself, and recursively calls Folder.updateAllFolders() on Folders returned from getSubFolders().

Methods inherited from class com.starbase.starteam.Item

acquireOwnership, addAttachment, createAttachment, createAttachmentFromFile, createItem, deleteMergePoint, discard, get, getAllLabels, getAttachedLabels, getAttachment, getAttachmentIDs, getAttachmentNames, getAttachmentToFile, getBehavior, getBranchRevisionFromDotNotation, getByProperty, getByPropertyID, getByteArray, getCachedProperties, getComment, getCommonAncestor, getCreatedBy, getCreatedTime, getDeletedTime, getDeletedUserID, getDisplayValue, getDouble, getEnumDisplayName, getFlag, getFlagDisplayName, getFromHistoryByDate, getFromHistoryByLabelID, getFromHistoryByVersion, getID, getInt, getIntArray, getItemID, getItemRevisions, getLocker, getMergeHistory, getModifiedBy, getModifiedTime, getMyLock, getNewRevisionComment, getObjectID, getOLEDate, getOwner, getParentFolderHierarchy, getParentFolderName, getParentFolderPath, getParentFolderQualifiedName, getParentRevision, getPossibleFlag, getPossibleReadStatus, getPossibleValues, getPropertyNames, getReadStatus, getReadStatusDisplayName, getReference, getReferences, getRevisionNumber, getRootObjectID, getServer, getString, getType, getTypeNames, getView, getViewVersion, getViewVersionFromDotNotation, hasPermission, hasValues, isBranchable, isDeleted, isDirty, isDisembodied, isFromHistory, isNew, isRefreshRequired, isRefreshRequired, isReverseShareRecommended, isRootShare, lock, modifyFlagForUser, modifyReadStatusForUser, populate, populate, putLock, recordMergePoint, refresh, refresh, removeAttachment, resolveMergePoint, reverseShareTo, setBehavior, setBranchOnChange, setComment, setFixedConfig, setFloatingConfig, smartShareTo, toDebugString, unlock, updateRevisionComment

Methods inherited from class com.starbase.starteam.TypedResource

addToIntArray, removeFromIntArray

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

EXCLUDE_NONE

public static final int EXCLUDE_NONE

A flag that indicated this folder does not use any exclude list.

See Also:

Constant Field Values

EXCLUDE_LOCAL

public static final int EXCLUDE_LOCAL

A flag that indicates that this folder is using an exclude list specifically designated for this folder.

See Also:

Constant Field Values

EXCLUDE_INHERIT

public static final int EXCLUDE_INHERIT

A flag that indcates that this folder inherits its exclude list from its parent folder and concatenates its own list if any.

See Also:

Constant Field Values

EOL_CRLF

public static final java.lang.String EOL_CRLF

Carriage-return + Line-feed end-of-line sequence (i.e., "\r\n").

See Also:

Constant Field Values

EOL_LF

public static final java.lang.String EOL_LF

Line-feed end-of-line sequence (i.e., "\n").

See Also:

Constant Field Values

EOL_CR

public static final java.lang.String EOL_CR

Carriage-return end-of-line sequence (i.e., "\r").

See Also:

Constant Field Values

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. NOTE that this needs to remain public because it's used in the COM API for CreateProjectEx().

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

put

public java.lang.Object put(java.lang.String propertyName,
                            java.lang.Object value)
                     throws NoSuchPropertyException,
                            java.lang.ClassCastException

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

Overrides:

put in class Item

Parameters:

propertyName - the name of 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

putByPropertyID

public java.lang.Object putByPropertyID(int propertyID,
                                        java.lang.Object value)
                                 throws NoSuchPropertyException,
                                        java.lang.ClassCastException

Set the value of the property specified by its property ID and return the old value.

Overrides:

putByPropertyID in class Item

Parameters:

propertyID - the ID of 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

See Also:

Property.getID()

getDotNotation

public java.lang.String getDotNotation()

Returns the dot notation identification of this version. The first version of an item added to the repository will have a dot notation of "1.0". Each new revision will increment the version number portion so the second revision would be "1.1". When an item branches a new branch number will be issued and revision will start counting from 0 again. For example, branching from version "1.2" might result in "1.2.5.0" after which the next version will be "1.2.5.1". The value 5 in the previous example was assigned by the server based on the number of branches already made from the revision being branched.

Overrides:

getDotNotation in class Item

Returns:

The dot notation identification of this version.

See Also:

PropertyNames.DOTNOTATION

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.

Returns:

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

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

getSubFolderCount

public int getSubFolderCount()

Returns the number of sub folders for this folder.

Returns:

the number of sub folders for this folder.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

getDescription

public java.lang.String getDescription()

Returns the description of this folder.

Returns:

the description of this folder.

See Also:

PropertyNames.FOLDER_DESCRIPTION

setDescription

public void setDescription(java.lang.String description)

Sets this folder's description.

Parameters:

description - the new description for this folder.

See Also:

PropertyNames.FOLDER_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:

PropertyNames.FOLDER_WORKING_FOLDER, 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:

PropertyNames.FOLDER_WORKING_FOLDER, 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()

getPath

public java.lang.String getPath()

Returns the local working file 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 file path being used for this folder.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

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

getExcludeFlags

public int getExcludeFlags()

Returns an int 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.EXCLUDE_NONE, Folder.EXCLUDE_LOCAL, Folder.EXCLUDE_INHERIT

setExcludeFlags

public void setExcludeFlags(int flag)

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

Parameters:

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

See Also:

Folder.EXCLUDE_NONE, Folder.EXCLUDE_LOCAL, Folder.EXCLUDE_INHERIT

getExcludeList

public java.lang.String getExcludeList()

Returns the portion of the exclude list that this folder contributes. Use resolveExcludeList 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.resolveExcludeList()

setExcludeList

public void setExcludeList(java.lang.String excludeList)

Sets this folder's local exclude list.

Parameters:

excludeList -

See Also:

Folder.getExcludeList(), Folder.resolveExcludeList(), 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:

DisembodiedItemException - if the Folder is disembodied

See Also:

Folder.getName(), Folder.getQualifiedName(), Item.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:

DisembodiedItemException - if the Folder is disembodied

See Also:

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

isExcluded

public boolean isExcluded(java.lang.String filename)

Determines if the given file name is one that will be excluded (matcthes 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.resolveExcludeList()

resolveExcludeList

public java.lang.String resolveExcludeList()

Returns the fully resolved exclude list. This may be the catenation 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:

DisembodiedItemException - if the Folder is disembodied

See Also:

Folder.getExcludeFlags(), Item.isDisembodied()

getName

public java.lang.String getName()

Returns the name of the folder.

Returns:

the name of the folder.

See Also:

PropertyNames.FOLDER_NAME

setName

public void setName(java.lang.String name)

Sets the name of this folder.

Parameters:

name - the new folder name.

See Also:

PropertyNames.FOLDER_NAME

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:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

hasParentFolder

public boolean hasParentFolder()

Returns true if this folder has a parent folder.

Returns:

true if this folder has a parent folder.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

enumerateItems

public java.util.Enumeration enumerateItems(java.lang.String typeName)

Returns an Enumeration of the items of the specified type that exist in this folder.

Parameters:

typeName - the type name of the sub items of this folder.

Returns:

an Enumeration of the specified items in this folder.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), TypeNames

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:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), Folder.EOL_CRLF, Folder.EOL_CR, Folder.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:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

getFolderTree

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

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

Parameters:

context - one of these values: Filter.CONTEXT_SERVER, Filter.CONTEXT_LOCAL and Filter.CONTEXT_LOCAL_AND_SERVER.

depth - the depth of levels of Folders affected.

Returns:

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

java.io.IOException

See Also:

Filter.CONTEXT_SERVER, Filter.CONTEXT_LOCAL, Filter.CONTEXT_LOCAL_AND_SERVER, Folder.getSubFolders()

updateFolderTree

public void updateFolderTree(int depth)

Calls update() on itself, and recursively calls Folder.updateAllFolders() 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.

java.io.IOException

getHistory

public Item[] getHistory()

Returns the past versions of this item.

Overrides:

getHistory in class Item

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

add

public Item add(Item child)

Deprecated. Instead of folder.add(item), use item.shareTo(folder). Note that Folder.add() does not work correctly for TreeItems, because it does not share child items.

Adds the specified item to this folder. The added item will still exist in its original folder as well as in this one.

Parameters:

child - the item to add to this folder

Returns:

the item object representing the newly added item

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), Item.shareTo(com.starbase.starteam.Folder), TreeItem

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:

DisembodiedItemException - if the target folder is disembodied.

See Also:

Item.isDisembodied(), Item.moveTo(com.starbase.starteam.Folder), Item.reverseShareTo(com.starbase.starteam.Folder), Folder.shareTo(Folder,boolean), Item.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:

DisembodiedItemException - if the target folder is disembodied.

See Also:

SupportedFeatures.canShareFolderOnly(), 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:

DisembodiedItemException - if the target folder is disembodied.

See Also:

SupportedFeatures.canShareFolderOnly(), Item.reverseShareTo(Folder)

move

public void move(Folder toFolder)

Deprecated. Use moveTo().

Moves this folder to the specified parent folder. The folder is removed from its previous parent folder.

Overrides:

move in class Item

Parameters:

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

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), #moveTo().

moveTo

public void moveTo(Folder toFolder)

Moves this folder to the specified folder. This folder will be removed from its current folder.

Overrides:

moveTo in class Item

Parameters:

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

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

getList

public ItemList getList(java.lang.String typeName)

Returns an ItemList of the specified item types in this folder.

Parameters:

typeName - the type name of the items to be returned

Returns:

an ItemList of the specified item types in this folder.

See Also:

TypeNames

getItems

public Item[] getItems(java.lang.String typeName)

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 avaliable, use populateNow().

Parameters:

typeName - The type name of the items to be retrieved.

Returns:

The items of the specified type in this folder.

Throws:

DisembodiedItemException - if the Folder is disembodied.

See Also:

TypeNames, Folder.populateNow(java.lang.String, java.lang.String[], int), Folder.isPopulated(java.lang.String), Item.refresh(), Item.isDisembodied()

isPopulated

public boolean isPopulated(java.lang.String typeName)

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

Parameters:

typeName - 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(java.lang.String)

populateNow

public void populateNow(java.lang.String typeName,
                        java.lang.String[] propertyNames,
                        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.

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

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:

typeName - The type name of the items to be retrieved.

propertyNames - The names of 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:

DisembodiedItemException - if the Folder is disembodied.

See Also:

TypeNames, PropertyNames, Folder.getItems(java.lang.String), Item.refresh(), Item.isDisembodied(), NetMonitor

populateAsNeeded

public void populateAsNeeded(java.lang.String typeName,
                             java.lang.String[] propertyNames,
                             int chunkSize)

Deprecated.

Deprecated. Use populateNow().

Parameters:

typeName - The type name of the items to be retrieved.

propertyNames - The names of 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.

chunkSize - the number of items to retrieve per server call.

Throws:

DisembodiedItemException - if the Folder is disembodied.

See Also:

Folder.populateNow(java.lang.String, java.lang.String[], int)

populateInBackground

public void populateInBackground(java.lang.String typeName,
                                 java.lang.String[] propertyNames,
                                 int chunkSize)

Similar to populateNow(). Items are populated in a background thread.

Parameters:

typeName - The type name of the items to be retrieved.

propertyNames - The names of 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.

chunkSize - Obsolete. chunkSize is ignored.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), TypeNames, PropertyNames, Folder.populateNow(java.lang.String, java.lang.String[], int)

isRefreshItemsRequired

public boolean isRefreshItemsRequired(java.lang.String typeName,
                                      java.lang.String[] propertyNames,
                                      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:

typeName - The type name of the items to be examined.

propertyNames - 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 if a refresh is required; false otherwise.

Throws:

DisembodiedItemException - if the Folder is disembodied.

See Also:

TypeNames, PropertyNames, Folder.refreshItems(java.lang.String, java.lang.String[], int), Item.isDisembodied(), Server.enableMPX()

refreshItems

public void refreshItems(java.lang.String typeName,
                         java.lang.String[] propertyNames,
                         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.

Parameters:

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

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

DisembodiedItemException - if the Folder is disembodied.

See Also:

TypeNames, PropertyNames, Folder.getItems(java.lang.String), Folder.populateNow(java.lang.String, java.lang.String[], int), Folder.isRefreshItemsRequired(java.lang.String, java.lang.String[], int), Folder.discardItems(String, int), Item.isDisembodied(), Server.enableMPX()

countItems

public long countItems(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 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

refreshForeignFiles

public ForeignRefreshResult refreshForeignFiles(int depth)

Refresh the foreign files in this folder, and its child folders depending on the specified "depth."

Parameters:

depth - The depth of the folders to be refreshed: 0 = this folder only, -1 = full tree.

Returns:

The result from running this method as a ForeignRefreshResult object.

Throws:

DisembodiedItemException - if the Folder is disembodied.

See Also:

ForeignRefreshResult

discardItems

public void discardItems(java.lang.String typeName,
                         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:

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

DisembodiedItemException - if the Folder is disembodied.

See Also:

TypeNames, Folder.populateNow(String, String[], int), Folder.refreshItems(String, String[], int), Item.isDisembodied(), Server.enableMPX()

hasPermission

public boolean hasPermission(int permissions,
                             java.lang.String typeName)

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

Specified by:

hasPermission in interface ISecurableContainer

Parameters:

permissions - the desired permissions

typeName - the name of 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, TypeNames

getACL

public AclEntry[] getACL()

Returns the Access Control List for this folder. This will return null if this folder has not access control list.

Specified by:

getACL in interface ISecurable

Overrides:

getACL in class Item

Returns:

the access control list for this folder. May return null.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

setACL

public void setACL(AclEntry[] acl)

Modify the Access Control List for this folder. If the input parameter is null then the access control list will be dropped.

Specified by:

setACL in interface ISecurable

Overrides:

setACL in class Item

Parameters:

acl - the new access control list or null if to be dropped.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied()

getContainerLevelACL

public AclEntry[] getContainerLevelACL(java.lang.String typeName)

Returns the Access Control List for items of the specified type for this folder. This will return null if this folder has not access control list for the specified type.

Specified by:

getContainerLevelACL in interface ISecurableContainer

Parameters:

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

Returns:

the access control list for this folder. May return null.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), TypeNames

setContainerLevelACL

public void setContainerLevelACL(AclEntry[] acl,
                                 java.lang.String typeName)

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:

setContainerLevelACL in interface ISecurableContainer

Parameters:

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

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

Returns:

the access control list for this folder. May return null.

Throws:

DisembodiedItemException - if the Folder is disembodied

See Also:

Item.isDisembodied(), TypeNames

update

public void update()

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

Overrides:

update in class Item

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.starbase.starteam.Folder), StarTeamClientOptions.setFolderUserVisible(com.starbase.starteam.Folder, 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.starbase.starteam.Folder), StarTeamClientOptions.setFolderUserVisible(com.starbase.starteam.Folder, boolean)

resolveUserVisible

public boolean resolveUserVisible()

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

See Also:

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

copy

public Item copy()

Creates a copy of this Folder, with folder properties fully populated. Useful to applications that want to save a snapshot of the Folder in a given state, for example, before calling View.refreshFolders().

Overrides:

copy in class Item

Returns:

A new copy of this Folder object.

See Also:

Folder.isEqualTo(com.starbase.starteam.Item)

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

See Also:

Folder.copy()

isEqualTo

public boolean isEqualTo(Item item)

Compares the properties of two Folders.

Overrides:

isEqualTo in class Item

Parameters:

item - The Folder to be compared to this one.

Returns:

true if no differences were found.

See Also:

Folder.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, FolderAdapter, FolderTreeListener, FolderTreeAdapter, Folder.removeFolderListener(com.starbase.starteam.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.starbase.starteam.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.starbase.starteam.FolderUpdateListener, int), Folder.addFolderListener(com.starbase.starteam.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.starbase.starteam.FolderUpdateListener, int)

addItemListener

public void addItemListener(IItemListener listener,
                            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,Type,String[],int), Folder.removeItemListener(com.starbase.starteam.IItemListener, com.starbase.starteam.Type, int), Server.enableMPX()

addItemListener

public void addItemListener(IItemListener listener,
                            Type type,
                            java.lang.String[] propertyNames,
                            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.

propertyNames - Names of 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,Type,int), Folder.removeItemListener(com.starbase.starteam.IItemListener, com.starbase.starteam.Type, int), Server.enableMPX()

removeItemListener

public void removeItemListener(IItemListener listener,
                               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,Type,int)

addItemUpdateListener

public void addItemUpdateListener(ItemUpdateListener listener,
                                  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.starbase.starteam.ItemUpdateListener, com.starbase.starteam.Type, int), View.addItemUpdateListener(com.starbase.starteam.ItemUpdateListener, com.starbase.starteam.Type), Folder.addItemListener(com.starbase.starteam.IItemListener, com.starbase.starteam.Type, int)

removeItemUpdateListener

public void removeItemUpdateListener(ItemUpdateListener listener,
                                     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.starbase.starteam.ItemUpdateListener, com.starbase.starteam.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 ISecurableContainer

Overrides:

getParentContainer in class Item

Returns:

This object's parent container.

See Also:

ISecurableContainer

equals

public boolean equals(java.lang.Object source)

returns true if this object instance is equal to the source

Overrides:

equals in class Item

Parameters:

source - Object the source to comapre with

Returns:

boolean true if this object is equal to the source

hashCode

public int hashCode()

returns a unique hash for all instances of this type

Overrides:

hashCode in class Item

Returns:

int a unique hash for all instances of this type