com.starteam
Class FolderListManager

java.lang.Object
  com.starteam.FolderListManager

public final class FolderListManager
extends java.lang.Object

Manages a collection of folders created by including and excluding selected folders and their sub-folders. Currently, all folders in the list must belong to the same view. Remembers the set of operations used to create the collection, so that the collection can be refreshed using the latest information from the StarTeam repository.

Constructor Summary

FolderListManager(FolderListManager folderList)
Creates a new folder list with the same folders as an existing folder list.

FolderListManager(View view)
Constructs a new folder list.

FolderListManager(View view, FolderListManager folderList)
Creates a new folder list with the same folders as an existing folder list.

Method Summary

void	addFolderListener(IFolderListener listener) Adds a listener for Folder-related events.
void	addFolderUpdateListener(FolderUpdateListener listener) Listens for updates to this view's folder tree.
void	clear() Removes all folders from the folder list.
void	discard() Discards cached folder information.
void	excludeFolder(Folder folder) Excludes the given folder from the folder list.
void	excludeFolders(Folder folder, Filter.Context context, int depth) Excludes the given folder, and optionally its sub-folders, from the folder list.
void	excludeFolders(Folder folder, int depth) Excludes the given folder, and optionally its sub-folders, from the folder list.
Folder[]	findFolders(java.lang.String name, boolean ignoreCase) return the (sub-)set of included folders that have the same name no matter what their full path in the folder tree
int	getFolderID(Folder folder) Returns the ItemID for a folder; if we're managing not-in-view folders, this may be a negative, temporary ID that can be used to uniquely identify the not-in-view folder object until it's been added to the repository.
ViewMemberCollection	getFolders() Gets the complete list of folders in the folder list.
View	getView() Returns the view for this FolderListManager.
void	includeFolder(Folder folder) Includes the given folder in the folder list.
void	includeFolders(Folder folder, Filter.Context context, int depth) Includes the given folder in the folder list in the context and depth specified.
void	includeFolders(Folder folder, int depth) Includes the given folder, and optionally its sub-folders, in the folder list.
boolean	isFolderIncluded(Folder folder) Determines whether or not the given folder is included in the folder list.
boolean	isFullScope() Determines whether or not all folders are included by definition.
boolean	isRefreshRequired() Returns true if a refresh() operation might have resulted in the folder list being updated; returns false if and only if it is known that the Folder list had not been changed since the last refresh.
void	refresh() Refreshes the list of folders using the latest information available from the repository.
void	removeFolderListener(IFolderListener listener) Removes a listener for Folder-related events.
void	removeFolderUpdateListener(FolderUpdateListener listener) Removes a listener for folder update events.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FolderListManager

public FolderListManager(View view)

Constructs a new folder list.

Parameters:

view - The view from which the folders will be added.

FolderListManager

public FolderListManager(FolderListManager folderList)

Creates a new folder list with the same folders as an existing folder list.

Parameters:

folderList - A folder list to be copied.

FolderListManager

public FolderListManager(View view,
                         FolderListManager folderList)

Creates a new folder list with the same folders as an existing folder list.

Parameters:

view - The view from which the folders will be added.

folderList - A folder list to be copied.

Method Detail

getView

public View getView()

Returns the view for this FolderListManager.

Returns:

the view for this FolderListManager.

See Also:

View

includeFolder

public void includeFolder(Folder folder)

Includes the given folder in the folder list.

Parameters:

folder - A folder to be included in the folder list.

See Also:

FolderListManager.includeFolders(com.starteam.Folder, int), FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.getFolders(), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

includeFolders

public void includeFolders(Folder folder,
                           int depth)

Includes the given folder, and optionally its sub-folders, in the folder list.

Parameters:

folder - A folder to be included in the folder list.

depth - Determines the depth to which sub-folders are also included. If depth is 0, only the folder itself is included. If depth is 1, only the immediate sub-folders are included; if depth is 2, two levels are included; and so on. If depth is -1, all sub-folders at any depth are included.

See Also:

FolderListManager.includeFolder(com.starteam.Folder), FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.getFolders(), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

includeFolders

public void includeFolders(Folder folder,
                           Filter.Context context,
                           int depth)

Includes the given folder in the folder list in the context and depth specified.

Parameters:

folder - A folder to be included in the folder list.

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

depth - Determines the depth to which subfolders are also included. If depth is 0, only the folder itself is included. If depth is 1, only the immediate subfolders are included; if depth is 2, two levels are included; and so on. If depth is -1, all subfolders at any depth are included.

See Also:

Filter.Context.SERVER, Filter.Context.LOCAL, Filter.Context.BOTH, FolderListManager.includeFolders(com.starteam.Folder, int), FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.getFolders(), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

excludeFolder

public void excludeFolder(Folder folder)

Excludes the given folder from the folder list.

Parameters:

folder - A folder to be excluded from the folder list.

See Also:

FolderListManager.excludeFolders(com.starteam.Folder, int), FolderListManager.includeFolder(com.starteam.Folder), FolderListManager.getFolders(), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

excludeFolders

public void excludeFolders(Folder folder,
                           int depth)

Excludes the given folder, and optionally its sub-folders, from the folder list.

Parameters:

folder - A folder to be excluded from the folder list.

depth - Determines the depth to which sub-folders are also excluded. If depth is 0, only the folder itself is excluded. If depth is 1, only the immediate sub-folders are excluded; if depth is 2, two levels are excluded; and so on. If depth is -1, all sub-folders at any depth are excluded.

See Also:

FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.includeFolder(com.starteam.Folder), FolderListManager.getFolders(), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

excludeFolders

public void excludeFolders(Folder folder,
                           Filter.Context context,
                           int depth)

Excludes the given folder, and optionally its sub-folders, from the folder list.

Parameters:

folder - A folder to be excluded from the folder list.

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

depth - Determines the depth to which sub-folders are also excluded. If depth is 0, only the folder itself is excluded. If depth is 1, only the immediate sub-folders are excluded; if depth is 2, two levels are excluded; and so on. If depth is -1, all sub-folders at any depth are excluded.

See Also:

FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.includeFolder(com.starteam.Folder), FolderListManager.getFolders(), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

clear

public void clear()

Removes all folders from the folder list.

getFolderID

public int getFolderID(Folder folder)

Returns the ItemID for a folder; if we're managing not-in-view folders, this may be a negative, temporary ID that can be used to uniquely identify the not-in-view folder object until it's been added to the repository.

Parameters:

folder - The folder whose ItemID is returned.

Returns:

the ItemID for a folder; if we're managing not-in-view folders, this may be a negative, temporary ID that can be used to uniquely identify the not-in-view folder object until it's been added to the repository.

getFolders

public ViewMemberCollection getFolders()

Gets the complete list of folders in the folder list.

Returns:

The list of folders in the folder list.

See Also:

FolderListManager.includeFolder(com.starteam.Folder), FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.isFolderIncluded(com.starteam.Folder), Folder

findFolders

public Folder[] findFolders(java.lang.String name,
                            boolean ignoreCase)

return the (sub-)set of included folders that have the same name no matter what their full path in the folder tree

Parameters:

name - the name of the folder

ignoreCase - true to do a case insensitive comparison

Returns:

the (sub-)set of folders with a given name but different paths

isFolderIncluded

public boolean isFolderIncluded(Folder folder)

Determines whether or not the given folder is included in the folder list.

Parameters:

folder - The folder to be tested.

Returns:

true if the folder is included, and false otherwise.

See Also:

FolderListManager.includeFolder(com.starteam.Folder), FolderListManager.excludeFolder(com.starteam.Folder), FolderListManager.getFolders(), Folder

refresh

public void refresh()

Refreshes the list of folders using the latest information available from the repository. The result is similar to refreshing the folders in the underlying view, emptying the folder list, and re-issuing the sequence of include and exclude calls that were used to construct the original folder list. If MPX is enabled, refresh() is optimized to avoid unnecessary server commands.

See Also:

FolderListManager.isRefreshRequired(), FolderListManager.discard(), Server.enableMPX(), View.refreshFolders()

isRefreshRequired

public boolean isRefreshRequired()

Returns true if a refresh() operation might have resulted in the folder list being updated; returns false if and only if it is known that the Folder list had not been changed since the last refresh. If MPX is not enabled, then isRefreshRequired() returns true.

Returns:

true if a refresh() operation might have resulted in the folder list being updated, and false otherwise.

See Also:

FolderListManager.refresh()

discard

public void discard()

Discards cached folder information. It will be re-fetched from the server the next time the folder list is retrieved (even when MPX is enabled).

See Also:

FolderListManager.refresh()

addFolderListener

public void addFolderListener(IFolderListener listener)

Adds a listener for Folder-related events. Events are triggered only for those folders that are in scope at the time the event occurs.

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.

See Also:

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

removeFolderListener

public void removeFolderListener(IFolderListener listener)

Removes a listener for Folder-related events.

Parameters:

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

See Also:

IFolderListener, FolderListManager.addFolderListener(com.starteam.events.IFolderListener)

addFolderUpdateListener

public void addFolderUpdateListener(FolderUpdateListener listener)

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.

See Also:

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

removeFolderUpdateListener

public void removeFolderUpdateListener(FolderUpdateListener listener)

Removes a listener for folder update events.

Parameters:

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

See Also:

FolderListener, FolderListManager.addFolderUpdateListener(com.starteam.events.FolderUpdateListener)

isFullScope

public boolean isFullScope()

Determines whether or not all folders are included by definition.

Returns:

true if all folders are included by definition; false otherwise.