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

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.
 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, lock, modifyFlagForUser, modifyReadStatusForUser, populate, populate, putLock, recordMergePoint, refresh, refresh, removeAttachment, resolveMergePoint, reverseShareTo, setBehavior, setBranchOnChange, setComment, setFixedConfig, setFloatingConfig, 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)

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:

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


StarTeam SDK 9.0, Build 287
Copyright © 2003-2004 Borland Software Corporation. All rights reserved.