com.starbase.starteam
Class ViewPollingAgent

java.lang.Object
  |
  +--com.starbase.starteam.ViewPollingAgent

public class ViewPollingAgent

extends java.lang.Object

Used to periodically poll a given view for recent changes, triggering FolderUpdateEvents and ItemUpdateEvents 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, OLEDate 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, Type type) Registers an ItemUpdateListener, whose methods will be invoked durng a refresh() whenever changes to the items of the given type are detected.
void	addRequiredPropertyName(Type type, java.lang.String propertyName) Marks a given property name as required for a given type.
void	addRequiredPropertyNames(Type type, java.lang.String[] propertyNames) Marks a list of property names as required for a given type.
boolean	equals(java.lang.Object source) returns true if this object instance is equal to the source
int	hashCode() returns a unique hash for all instances of this type
OLEDate	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, Type type) Unregisters a previously registered ItemUpdateListener.
void	setAllPropertyNamesRequired(Type type) Marks all property names as required for a given type.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ViewPollingAgent

public ViewPollingAgent(View view,
                        OLEDate startTime)

Constructs a new ViewPollingAgent.

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.starbase.starteam.FolderUpdateListener)

removeFolderUpdateListener

public void removeFolderUpdateListener(FolderUpdateListener listener)

Unregisters a previously registered FolderUpdateListener.

Parameters:

listener - The listener to be unregistered.

See Also:

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

addItemUpdateListener

public void addItemUpdateListener(ItemUpdateListener listener,
                                  Type type)

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

Note that all ItemUpdateListeners must be added before the first refresh().

Parameters:

listener - The listener to be registered.

type - The item type.

See Also:

ItemUpdateListener, ViewPollingAgent.refresh(), ViewPollingAgent.removeItemUpdateListener(com.starbase.starteam.ItemUpdateListener, com.starbase.starteam.Type)

removeItemUpdateListener

public void removeItemUpdateListener(ItemUpdateListener listener,
                                     Type type)

Unregisters a previously registered ItemUpdateListener.

Parameters:

listener - The listener to be unregistered.

type - The item type.

See Also:

ViewPollingAgent.addItemUpdateListener(com.starbase.starteam.ItemUpdateListener, com.starbase.starteam.Type)

addRequiredPropertyName

public void addRequiredPropertyName(Type type,
                                    java.lang.String propertyName)

Marks a given property name 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.

propertyName - A property name.

See Also:

ViewPollingAgent.refresh(), ViewPollingAgent.addRequiredPropertyNames(com.starbase.starteam.Type, java.lang.String[]), ViewPollingAgent.setAllPropertyNamesRequired(com.starbase.starteam.Type)

addRequiredPropertyNames

public void addRequiredPropertyNames(Type type,
                                     java.lang.String[] propertyNames)

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

Parameters:

type - An item type.

propertyNames - A list of property names.

See Also:

ViewPollingAgent.addRequiredPropertyName(com.starbase.starteam.Type, java.lang.String)

setAllPropertyNamesRequired

public void setAllPropertyNamesRequired(Type type)

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

Parameters:

type - An item type.

See Also:

ViewPollingAgent.addRequiredPropertyName(com.starbase.starteam.Type, java.lang.String)

refresh

public OLEDate 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.

equals

public boolean equals(java.lang.Object source)

returns true if this object instance is equal to the source

Overrides:

equals in class java.lang.Object

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 java.lang.Object

Returns:

int a unique hash for all instances of this type