com.starteam
Class ViewMemberListManager

java.lang.Object
  com.starteam.ViewMemberListManager

public final class ViewMemberListManager
extends java.lang.Object

Generates and manages a list of ViewMembers. All ViewMembers in the list have a given type. Items are generated from a list of folders determined by a FolderListManager, (non item) ViewMembers are generated from the view The ViewMember list can be filtered, sorted, refreshed, queried, and so on. ViewMembers are retrieved via getViewMembers(), which is optimized to do as little work as possible. For example, if only the sort order has changed since the last time the ViewMember list was retrieved, then the existing ViewMembers in the list are simply resorted.

See Also:

FolderListManager, Filter, Query, Item, ViewMember

Nested Class Summary

static class

ViewMemberListManager.GroupNode Describes a group of objects that may be a subgroup of a larger, indexable group.

Constructor Summary

ViewMemberListManager(Item.Type type, FolderListManager folders)
Constructs a new ViewMember list.

ViewMemberListManager(ViewMember.Type type, View view)
Constructs a new ViewMember list.

Method Summary

void	addItemListener(IItemListener listener) Adds a listener for Item-related events.
void	addItemUpdateListener(ItemUpdateListener listener) Listens for updates to this ViewMemberListManager.
void	addViewMemberListener(ViewMemberListener listener) Adds a listener for non-Item ViewMember-related events.
void	addViewMemberUpdateListener(ViewMemberUpdateListener listener) Listens for updates to the view members of a given type in this view.
void	close() Close this ViewMemberListManager, release all its resources, and sever its ties to its parent FolderListManager it will automatically be re-opened when needed.
void	discard() Discards all relevant cached data.
ViewMember	findViewMember(int vmID) Searches for a given viewMember in the viewMember list.
PropertyCollection	getAllCachedProperties() Gets the list of properties that will be pre-fetched and cached for members of this item list.
PropertyCollection	getCachedPropertiesForFilter() Gets the list of properties that will be pre-fetched and cached for members of this item list based on Filter criteria.
PropertyCollection	getExtraCachedProperties() Gets the list of "extra" properties that will be pre-fetched and cached for members of this item list.
Filter	getFilter() Gets the filter that is applied to the viewMember list.
FolderListManager	getFolderListManager() Gets the FolderListManager that determines which folders will be used to generate viewMembers in the item list.
java.lang.String[]	getFullDisplay() Returns the current display state of the list.
ViewMemberListManager.GroupNode	getGroupNodeAtLine(int line) Returns the GroupNode at line, given the list's current collapsed/expanded state, or null if that line doesn't contain a GroupNode.
ViewMember.Type	getType() Gets the type of viewMember included in the viewMember list.
boolean	getUserVisibleFoldersOnly() Returns true if only ViewMembers in user-visible Folders are included, otherwise false.
View	getView() Returns the view from which the ViewMembers will be culled
ViewMember	getViewMemberAtLine(int line) Returns the ViewMember at line, given the list's current collapsed/expanded state, or null if that line doesn't contain an ViewMember.
ViewMemberListManager.GroupNode[]	getViewMemberGroups() Returns an array of GroupNodes that describes the group membership of all ViewMembers managed by the ViewMemberListManager.
int	getViewMemberID(ViewMember item) Returns the VMID for an item; if we're managing not-in-view files, this may be a negative, temporary ID that can be used to uniquely identify the not-in-view file object until it's been added to the repository.
ViewMemberCollection	getViewMembers() Returns the viewMembers in the viewMember list.
ViewMemberCollection	getViewMembers(Folder folder, boolean bDescendants) Returns a collection containing the viewMembers in a Folder and optionally all its descendants.
int	getVisibleLines() Returns the number of visible lines in the list, given the current collapsed/expanded state of its nodes.
void	groupViewMembers(boolean bGroup) Determines whether this ViewMemberListManager should group viewMembers when returning them? ViewMembers can only be grouped if sortViewMembers is also set to True ViewMembers will be grouped if the ViewMemberListManager is attached to a Filter that specifies Group Sorting Information A ViewMemberListManager is grouped by default
boolean	isGrouped() Returns true if this ViewMemberListManager has grouping criteria applied.
boolean	isGroupNodeAtLine(int line) Returns true if the object at line is a GroupNode or false if it's an ViewMember, given the list's current collapsed/expanded state.
boolean	isRefreshRequired() Returns true if a refresh() operation might have resulted in the viewMember list being updated; returns false if and only if it is known that the viewMember list had not been changed since the last refresh.
void	refresh() Updates the list of viewMembers to reflect recent changes made on the server.
void	removeItemListener(IItemListener listener) Removes a listener for Item-related events.
void	removeItemUpdateListener(ItemUpdateListener listener) Removes a listener for item update events.
void	removeViewMemberListener(ViewMemberListener listener) Removes a listener for non-Item ViewMember-related events.
void	removeViewMemberUpdateListener(ViewMemberUpdateListener listener) Removes a listener for view member update events.
ViewMemberCollection	selectBy(Label label) Gets the subset of viewMembers in the viewMember list to which the given label has been applied.
ViewMemberCollection	selectBy(Query query) Gets the subset of viewMembers in the viewMember list that match the given query.
void	setExtraCachedProperties(PropertyCollection properties) Sets the list of "extra" properties that will be pre-fetched and cached for members of this item list, beyond what is specified by the Filter.
void	setFilter(Filter filter) Sets the filter to be applied to the item list.
void	setUserVisibleFoldersOnly(boolean bUserVisibleFoldersOnly) Sets the option to include only ViewMembers in user-visible Folders on or off.
void	sortViewMembers(boolean bSort) Determines whether this ViewMemberListManager should sort viewMembers when returning them? ViewMembers will be sorted if the ViewMemberListManager is attached to a Filter that specifies Group Sorting Information A ViewMemberListManager is sorted by default

Methods inherited from class java.lang.Object

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

Constructor Detail

ViewMemberListManager

public ViewMemberListManager(ViewMember.Type type,
                             View view)

Constructs a new ViewMember list. Use this constructor for (non-item) ViewMembers that do not live in folders e.g. (ChangePackage, Trace) OR for item type viewMembers spanning the entire folder tree

Parameters:

type - The type of ViewMember to be included in the ViewMember list.

view - The view to be included in the ViewMember list.

See Also:

ChangePackage, Trace

ViewMemberListManager

public ViewMemberListManager(Item.Type type,
                             FolderListManager folders)

Constructs a new ViewMember list. Use this constructor for viewMembers that live in folders (e.g. File, ChangeRequest)

Parameters:

type - The type of item to be included in the ViewMember list.

folders - The list of folders to be included in the ViewMember list.

See Also:

ViewMember, TreeItem

Method Detail

close

public void close()

Close this ViewMemberListManager, release all its resources, and sever its ties to its parent FolderListManager it will automatically be re-opened when needed.

sortViewMembers

public void sortViewMembers(boolean bSort)

Determines whether this ViewMemberListManager should sort viewMembers when returning them? ViewMembers will be sorted if the ViewMemberListManager is attached to a Filter that specifies Group Sorting Information A ViewMemberListManager is sorted by default

Parameters:

bSort - True to sort the viewMembers, False to return them in default order

See Also:

ViewMemberListManager.getViewMembers()

groupViewMembers

public void groupViewMembers(boolean bGroup)

Determines whether this ViewMemberListManager should group viewMembers when returning them? ViewMembers can only be grouped if sortViewMembers is also set to True ViewMembers will be grouped if the ViewMemberListManager is attached to a Filter that specifies Group Sorting Information A ViewMemberListManager is grouped by default

Parameters:

bGroup - True to group the viewMembers, False to return them in default order

See Also:

ViewMemberListManager.sortViewMembers(boolean), ViewMemberListManager.getViewMembers()

getType

public ViewMember.Type getType()

Gets the type of viewMember included in the viewMember list.

Returns:

The type of viewMember included in the viewMember list.

getViewMemberID

public int getViewMemberID(ViewMember item)

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

Parameters:

item - The viewMember whose VMID is returned.

Returns:

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

getFolderListManager

public FolderListManager getFolderListManager()

Gets the FolderListManager that determines which folders will be used to generate viewMembers in the item list. The viewMember list tracks changes to the folder list, and adjusts the viewMember list accordingly. For example, if a folder is added to the list after a previous call to getViewMembers(), then on the next call to getViewMembers(), the new folder is automatically populated, the viewMembers in the new folder are filtered, and the entire viewMember list is resorted.

Returns:

The FolderListManager that determines which folders will be used to generate viewMembers in the item list.

getView

public View getView()

Returns the view from which the ViewMembers will be culled

Returns:

the view from which the ViewMembers will be culled

setFilter

public void setFilter(Filter filter)

Sets the filter to be applied to the item list. Only viewMembers that are accepted by the filter will be included in the item list. By default, no filter is applied.

Parameters:

filter - The filter to be applied to the item list.

See Also:

Filter

getFilter

public Filter getFilter()

Gets the filter that is applied to the viewMember list. By default, no filter is applied.

Returns:

The filter to be applied to the viewMember list.

See Also:

Filter

setExtraCachedProperties

public void setExtraCachedProperties(PropertyCollection properties)

Sets the list of "extra" properties that will be pre-fetched and cached for members of this item list, beyond what is specified by the Filter. By default (i.e., when no Filter is applied), all properties are pre-fetched and cached.

Parameters:

properties - The list of "extra" properties that will be pre-fetched and cached for members of this viewMember list.

See Also:

ViewMemberListManager.getExtraCachedProperties(), Property

getExtraCachedProperties

public PropertyCollection getExtraCachedProperties()

Gets the list of "extra" properties that will be pre-fetched and cached for members of this item list. By default, all properties are pre-fetched and cached. If a Filter is applied, the properties described in the Filter will be cached, along with zero or more "extra" properties set by the user. If no filter is applied, all properties are pre-fetched and cached, regardless of the extra properties set by the user.

Returns:

The list of "extra" properties that will be pre-fetched and cached for members of this viewMember list.

See Also:

ViewMemberListManager.setExtraCachedProperties(com.starteam.PropertyCollection), Property

getCachedPropertiesForFilter

public PropertyCollection getCachedPropertiesForFilter()

Gets the list of properties that will be pre-fetched and cached for members of this item list based on Filter criteria. By default, all properties are pre-fetched and cached. If a Filter is applied, the properties described in the Filter will be cached, along with zero or more "extra" properties set by the user. If no filter is applied, all properties are pre-fetched and cached, regardless of the extra properties set by the user.

Returns:

The list of properties that will be pre-fetched and cached for members of this viewMember list based on Filter criteria.

See Also:

ViewMemberListManager.setExtraCachedProperties(com.starteam.PropertyCollection), Property

getAllCachedProperties

public PropertyCollection getAllCachedProperties()

Gets the list of properties that will be pre-fetched and cached for members of this item list. By default, all properties are pre-fetched and cached. If a Filter is applied, the properties described in the Filter will be cached, along with zero or more "extra" properties set by the user. If no filter is applied, all properties are pre-fetched and cached, regardless of the extra properties set by the user.

Returns:

The list of properties that will be pre-fetched and cached for members of this viewMember list.

See Also:

ViewMemberListManager.setFilter(com.starteam.Filter), ViewMemberListManager.setExtraCachedProperties(com.starteam.PropertyCollection), Property, Filter

getViewMembers

public ViewMemberCollection getViewMembers()

Returns the viewMembers in the viewMember list. Optimized to do as little work as possible. For example, if only the sort order has changed since the last time the viewMember list was retrieved, then the existing viewMembers in the list are resorted only.

Returns:

The collection of viewMemebrs in the viewMember list, updated, if necessary, to reflect any changes that have been made (in the folder list, filter, sort order, and so on) since the last time the viewMember list was retrieved.

getViewMembers

public ViewMemberCollection getViewMembers(Folder folder,
                                           boolean bDescendants)

Returns a collection containing the viewMembers in a Folder and optionally all its descendants.

Parameters:

folder - the folder whose viewMembers are returned

bDescendants - true = plus all descendants of folder; false = folder only

Returns:

a collection containing the viewMembers in a Folder and optionally all its descendants.

See Also:

ViewMemberListManager.getViewMembers()

findViewMember

public ViewMember findViewMember(int vmID)

Searches for a given viewMember in the viewMember list.

Parameters:

vmID - The result of a call to getViewMemberID(item).

Returns:

The viewMember, or null if no viewMember with the given ID was found in the viewMember list.

See Also:

ViewMemberListManager.getViewMemberID(com.starteam.ViewMember)

refresh

public void refresh()

Updates the list of viewMembers to reflect recent changes made on the server. Existing ViewMember objects are modified in place whenever possible. If MPX is enabled, refresh() is optimized to avoid unnecessary server commands.

See Also:

ViewMemberListManager.getViewMembers(), ViewMemberListManager.isRefreshRequired(), ViewMemberListManager.discard(), Server.isMPXEnabled()

isRefreshRequired

public boolean isRefreshRequired()

Returns true if a refresh() operation might have resulted in the viewMember list being updated; returns false if and only if it is known that the viewMember 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:

ViewMemberListManager.refresh()

discard

public void discard()

Discards all relevant cached data. It will be re-fetched from the server the next time the viewMember list is retrieved (even when MPX is enabled).

See Also:

ViewMemberListManager.refresh()

selectBy

public ViewMemberCollection selectBy(Label label)

Gets the subset of viewMembers in the viewMember list to which the given label has been applied.

Parameters:

label - The label to be tested.

Returns:

The subset of viewMembers in the viewMember list to which the given label has been applied.

See Also:

ViewMemberListManager.getViewMembers()

selectBy

public ViewMemberCollection selectBy(Query query)

Gets the subset of viewMembers in the viewMember list that match the given query.

Parameters:

query - The query to be matched.

Returns:

The subset of viewMembers in the viewMember list that match the given query.

isGrouped

public boolean isGrouped()

Returns true if this ViewMemberListManager has grouping criteria applied.

Returns:

true if this ViewMemberListManager has grouping criteria applied.

See Also:

Filter, Filter.Grouping

getViewMemberGroups

public ViewMemberListManager.GroupNode[] getViewMemberGroups()

Returns an array of GroupNodes that describes the group membership of all ViewMembers managed by the ViewMemberListManager. May return an empty array.

Returns:

an array of GroupNodes that describes the group membership of all ViewMembers managed by the ViewMemberListManager. May return an empty array.

See Also:

ViewMemberListManager.GroupNode, Filter, Filter.Grouping, ViewMemberListManager.isGrouped()

getVisibleLines

public int getVisibleLines()

Returns the number of visible lines in the list, given the current collapsed/expanded state of its nodes.

Returns:

the number of visible lines in the list, given the current collapsed/expanded state of its nodes.

See Also:

ViewMemberListManager.GroupNode, Filter, Filter.Grouping

isGroupNodeAtLine

public boolean isGroupNodeAtLine(int line)

Returns true if the object at line is a GroupNode or false if it's an ViewMember, given the list's current collapsed/expanded state.

Parameters:

line - the zero-based line to query, given the current collapsed/expanded state of the list.

Returns:

true if the object at line is a GroupNode or false if it's an ViewMember, given the list's current collapsed/expanded state.

See Also:

ViewMemberListManager.GroupNode

getGroupNodeAtLine

public ViewMemberListManager.GroupNode getGroupNodeAtLine(int line)

Returns the GroupNode at line, given the list's current collapsed/expanded state, or null if that line doesn't contain a GroupNode.

Parameters:

line - the line to query, given the current collapsed/expanded state of the list.

Returns:

the GroupNode at line, given the list's current collapsed/expanded state, or null if that line doesn't contain a GroupNode.

See Also:

ViewMemberListManager.GroupNode

getViewMemberAtLine

public ViewMember getViewMemberAtLine(int line)

Returns the ViewMember at line, given the list's current collapsed/expanded state, or null if that line doesn't contain an ViewMember.

Parameters:

line - the line to query, given the current collapsed/expanded state of the list.

Returns:

the ViewMember at line, given the list's current collapsed/expanded state, or null if that line doesn't contain an ViewMember.

See Also:

ViewMemberListManager.GroupNode, ViewMember

getFullDisplay

public java.lang.String[] getFullDisplay()

Returns the current display state of the list. The '\t' character indicates indents. The '|' character separates column values. Useful for debugging.

Returns:

the current display state of the list. The '\t' character indicates indents. The '|' character separates column values. Useful for debugging.

getUserVisibleFoldersOnly

public boolean getUserVisibleFoldersOnly()

Returns true if only ViewMembers in user-visible Folders are included, otherwise false. By default all ViewMembers are included, even those in Folders that are not user-visible.

Returns:

true if only ViewMembers in user-visible Folders are included, otherwise false.

See Also:

ViewMemberListManager.setUserVisibleFoldersOnly(boolean), Folder.getEffectiveUserVisible()

setUserVisibleFoldersOnly

public void setUserVisibleFoldersOnly(boolean bUserVisibleFoldersOnly)

Sets the option to include only ViewMembers in user-visible Folders on or off. By default all ViewMembers are included, even those in Folders that are not user-visible.

Parameters:

bUserVisibleFoldersOnly - = true if only ViewMembers in user-visible Folders will be included, otherwise false

See Also:

ViewMemberListManager.getUserVisibleFoldersOnly(), Folder.getEffectiveUserVisible()

addItemListener

public void addItemListener(IItemListener listener)

Adds a listener for Item-related events.

If listener is an ItemListener, then the properties that are populated in Item objects passed to the application's event handlers are those same properties that would normally be populated by the ViewMemberListManager. To populate a specific set of properties for the event handlers, set the appropriate filter (and/or call setExtraCachedProperties) before registering the listener.

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.

See Also:

IItemListener, ItemListener, ItemIDListener, ItemListListener, NotificationListener, ViewMemberListManager.removeItemListener(com.starteam.events.IItemListener), Server.enableMPX()

addViewMemberListener

public void addViewMemberListener(ViewMemberListener listener)

Adds a listener for non-Item ViewMember-related events.

ViewMember 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 descriptors.

In order to handle events, an application must enable MPX. Applications intending to receive Item events must use ViewMemberListManager.addItemListener(IItemListener)

Parameters:

listener - Application-specific event handler for non-Item ViewMember-related events.

See Also:

ViewMemberListener, ViewMemberListManager.removeViewMemberListener(com.starteam.events.ViewMemberListener), Server.enableMPX()

removeViewMemberListener

public void removeViewMemberListener(ViewMemberListener listener)

Removes a listener for non-Item ViewMember-related events.

Parameters:

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

See Also:

ViewMemberListener, ViewMemberListManager.addViewMemberListener(com.starteam.events.ViewMemberListener)

addViewMemberUpdateListener

public void addViewMemberUpdateListener(ViewMemberUpdateListener listener)

Listens for updates to the view members of a given type in this view.

Events are triggered by explicit operations performed by the client application. For example, calling Trace.update(), or Trace.remove() might each trigger update events.

MPX is not required to receive view member update events. Applications intending to receive Item update events must use ViewMemberListManager.addItemUpdateListener(ItemUpdateListener)

Parameters:

listener - Application-specific event handler for view member update events.

See Also:

ViewMemberUpdateListener, ViewMemberListManager.removeViewMemberUpdateListener(com.starteam.events.ViewMemberUpdateListener)

removeViewMemberUpdateListener

public void removeViewMemberUpdateListener(ViewMemberUpdateListener listener)

Removes a listener for view member update events.

Parameters:

listener - Previously-registered event handler for view member update events.

See Also:

ViewMemberUpdateListener, ViewMemberListManager.addViewMemberUpdateListener(com.starteam.events.ViewMemberUpdateListener)

removeItemListener

public void removeItemListener(IItemListener listener)

Removes a listener for Item-related events.

Parameters:

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

See Also:

IItemListener, ViewMemberListManager.addItemListener(com.starteam.events.IItemListener)

addItemUpdateListener

public void addItemUpdateListener(ItemUpdateListener listener)

Listens for updates to this ViewMemberListManager.

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.

See Also:

ItemUpdateListener, ViewMemberListManager.removeItemUpdateListener(com.starteam.events.ItemUpdateListener), ViewMemberListManager.addItemListener(com.starteam.events.IItemListener)

removeItemUpdateListener

public void removeItemUpdateListener(ItemUpdateListener listener)

Removes a listener for item update events.

Parameters:

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

See Also:

ItemUpdateListener, ViewMemberListManager.addItemUpdateListener(com.starteam.events.ItemUpdateListener)