com.starteam
Class ViewPollingAgent

java.lang.Object
  com.starteam.ViewPollingAgent

public final class ViewPollingAgent
extends java.lang.Object

Used to periodically poll a given view for recent changes, triggering FolderUpdateEvents, ItemUpdateEvents and ViewMemberUpdateEvents describing the changes detected since the last poll.

Events are triggered only for differences detectable across the polling interval. For example, if an item is added then removed without an intervening refresh, then no events would be triggered for that item.

Events are triggered in an order that reflects the times the change actually occurred, when possible. For some older server versions, it is not possible to determine when a move has occurred. It is also not currently possible to determine when a folder or item was removed. Such events are triggered last.

There are two basic ways to use a ViewPollingAgent. The first way is to create one and keep it around for a long time, periodically calling refresh() to trigger events. This is generally faster than creating a new ViewPollingAgent for each refresh(). However, the ViewPollingAgent consumes memory while it is in use.

The second way is to create a new ViewPollingAgent at each polling interval, call refresh() once to trigger events, and save the time returned by refresh() to use later when creating a ViewPollingAgent for the next poll. This is slower, but uses less memory between polls.

Constructor Summary

ViewPollingAgent(View view, DateTime startTime)
Constructs a new ViewPollingAgent.

Method Summary

void	addFolderUpdateListener(FolderUpdateListener listener) Registers a FolderUpdateListener, whose methods will be invoked during a refresh() whenever changes to the folder tree are detected.
void	addItemUpdateListener(ItemUpdateListener listener, Item.Type type) Registers an ItemUpdateListener, whose methods will be invoked during a refresh() whenever changes to the items of the given type are detected.
void	addRequiredProperties(ViewMember.Type type, PropertyCollection pc) Marks a list of properties as required for a given type.
void	addRequiredProperty(ViewMember.Type type, Property property) Marks a given property as required for a given type.
void	addViewMemberUpdateListener(ViewMemberUpdateListener listener, ViewMember.Type type) Registers a ViewMemberUpdateListener, whose methods will be invoked during a refresh() whenever changes to the view members of the given type are detected.
void	close() Frees all cached resources associated with this ViewPollingAgent, and closes the associated view.
DateTime	refresh() Refreshes the view, triggering FolderUpdateEvents and ItemUpdateEvents for all changes detected since the previous refresh (or since the start ViewPollingAgent's start time, if this is the first refresh).
void	removeFolderUpdateListener(FolderUpdateListener listener) Unregisters a previously registered FolderUpdateListener.
void	removeItemUpdateListener(ItemUpdateListener listener, Item.Type type) Unregisters a previously registered ItemUpdateListener.
void	removeViewMemberUpdateListener(ViewMemberUpdateListener listener, ViewMember.Type type) Unregisters a previously registered ViewMemberUpdateListener.
void	setAllPropertiesRequired(ViewMember.Type type) Marks all properties as required for a given type.

Methods inherited from class java.lang.Object

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

Constructor Detail

ViewPollingAgent

public ViewPollingAgent(View view,
                        DateTime startTime)

Constructs a new ViewPollingAgent. Use DateTime.CURRENT_SERVER_TIME to triggers events that occur after the current server time.

Parameters:

view - The view whose changes are to be monitored.

startTime - The start time for detecting changes. Often the same as the time returned by the last call to refresh() from a previously instantiated ViewPollingAgent.

Method Detail

addFolderUpdateListener

public void addFolderUpdateListener(FolderUpdateListener listener)

Registers a FolderUpdateListener, whose methods will be invoked during a refresh() whenever changes to the folder tree are detected.

Parameters:

listener - The listener to be registered.

See Also:

FolderUpdateListener, ViewPollingAgent.refresh(), ViewPollingAgent.removeFolderUpdateListener(com.starteam.events.FolderUpdateListener)

removeFolderUpdateListener

public void removeFolderUpdateListener(FolderUpdateListener listener)

Unregisters a previously registered FolderUpdateListener.

Parameters:

listener - The listener to be unregistered.

See Also:

ViewPollingAgent.addFolderUpdateListener(com.starteam.events.FolderUpdateListener)

addItemUpdateListener

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

Registers an ItemUpdateListener, whose methods will be invoked during a refresh() whenever changes to the items of the given type are detected.

Note that all ItemUpdateListeners must be added before the first refresh(). Use this listener interface for viewMembers that live in folders (e.g. File, ChangeRequest)

Parameters:

listener - The listener to be registered.

type - The item type.

See Also:

ItemUpdateListener, ViewPollingAgent.refresh(), ViewPollingAgent.removeItemUpdateListener(com.starteam.events.ItemUpdateListener, com.starteam.Item.Type)

removeItemUpdateListener

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

Unregisters a previously registered ItemUpdateListener.

Parameters:

listener - The listener to be unregistered.

type - The item type.

See Also:

ViewPollingAgent.addItemUpdateListener(com.starteam.events.ItemUpdateListener, com.starteam.Item.Type)

addViewMemberUpdateListener

public void addViewMemberUpdateListener(ViewMemberUpdateListener listener,
                                        ViewMember.Type type)

Registers a ViewMemberUpdateListener, whose methods will be invoked during a refresh() whenever changes to the view members of the given type are detected. Use this listener interface for (non-item) ViewMembers that do not live in folders e.g. (ChangePackage, Trace)

Parameters:

listener - The listener to be registered.

type - The view member type.

See Also:

ViewMemberUpdateListener, ViewPollingAgent.refresh(), ViewPollingAgent.removeViewMemberUpdateListener(com.starteam.events.ViewMemberUpdateListener, com.starteam.ViewMember.Type)

removeViewMemberUpdateListener

public void removeViewMemberUpdateListener(ViewMemberUpdateListener listener,
                                           ViewMember.Type type)

Unregisters a previously registered ViewMemberUpdateListener.

Parameters:

listener - The listener to be unregistered.

type - The viewMember type.

See Also:

ViewPollingAgent.addViewMemberUpdateListener(com.starteam.events.ViewMemberUpdateListener, com.starteam.ViewMember.Type)

addRequiredProperty

public void addRequiredProperty(ViewMember.Type type,
                                Property property)

Marks a given property as required for a given type. All refresh operations on that type will include this property.

If addPropertyName() or any of its variations is never called for a given type, then a default set of properties (including the type's descriptors) is assumed. In fact, if neither addPropertyName() nor addItemUpdateListener() is called, then that item type is not even refreshed.

Parameters:

type - An item type.

property - A property .

See Also:

ViewPollingAgent.refresh(), ViewPollingAgent.setAllPropertiesRequired(com.starteam.ViewMember.Type)

addRequiredProperties

public void addRequiredProperties(ViewMember.Type type,
                                  PropertyCollection pc)

Marks a list of properties as required for a given type. All refresh operations on that type will include these properties.

Parameters:

type - An item type.

pc - A collection of properties.

See Also:

ViewPollingAgent.addRequiredProperty(com.starteam.ViewMember.Type, com.starteam.Property)

setAllPropertiesRequired

public void setAllPropertiesRequired(ViewMember.Type type)

Marks all properties as required for a given type. All refresh operations on that type will include all properties.

Parameters:

type - An item type.

See Also:

ViewPollingAgent.addRequiredProperty(com.starteam.ViewMember.Type, com.starteam.Property)

refresh

public DateTime refresh()

Refreshes the view, triggering FolderUpdateEvents and ItemUpdateEvents for all changes detected since the previous refresh (or since the start ViewPollingAgent's start time, if this is the first refresh).

The folder tree is always refreshed. In addition, all items a refreshed for each item type that the application has shown an interest in, either by adding an ItemUpdateListener for that item type, or by calling addRequiredPropertyName() with that item type.

Returns:

The poll time used for this refresh operation. You can continue to refresh using this ViewPollingAgent, or use this poll time as the start time for a new ViewPollingAgent to pick up where this one left off.

close

public void close()

Frees all cached resources associated with this ViewPollingAgent, and closes the associated view.

See Also:

View.close()