com.veriplace.client.util
Class PollingManager

java.lang.Object
  com.veriplace.client.util.PollingManager

public class PollingManager
extends java.lang.Object

Maintains a thread that issues PollingAPI requests at regular intervals and passes the results to a PollingHandler.

If not configured otherwise with setIntervalSeconds(int), the polling interval will be set to the default value provided by the Veriplace server after the first successful PollingAPI query.

By default, this class calls GetLocationAPI.getLocationAccessToken(User) as needed to obtain access tokens for getting users' locations, and stores the tokens in an in-memory cache. If you have your own token caching mechanism, you can pass your own implementation of UserTokenStore to the constructor.

Since:

2.4

Field Summary

protected Token	accessToken
protected Client	client
protected int	intervalSeconds
protected boolean	onlyNewestLocation
protected PollingAPI	pollingAPI
protected PollingFilter	pollingFilter
protected PollingHandler	pollingHandler
protected UserTokenStore	userTokenStore

Constructor Summary

PollingManager()
Constructs a new PollingManager whose properties are uninitialized.

PollingManager(Client client, PollingHandler pollingHandler, boolean startPollingNow)
Constructs a new PollingManager, using the default in-memory cache for access tokens.

PollingManager(Client client, PollingHandler pollingHandler, PollingFilter pollingFilter, boolean startPollingNow)
Constructs a new PollingManager, using the default in-memory cache for access tokens, and specifying a PollingFilter.

PollingManager(Client client, PollingHandler pollingHandler, PollingFilter pollingFilter, Token accessToken, UserTokenStore userTokenStore, boolean startPollingNow)
Constructs a new PollingManager, optionally specifying an alternate application token and an implementation object for access token caching.

Method Summary

protected void	dispatchUpdate(User user, LocationUpdateReference locRef, java.lang.Object currentBatch)
Client	getClient() The Veriplace client instance.
int	getIntervalSeconds() Returns the number of seconds between update queries.
protected PollingAPI	getPollingAPI(Client client)
PollingFilter	getPollingFilter()
PollingHandler	getPollingHandler()
protected Location	getUpdateLocation(User user, LocationUpdateReference locRef)
boolean	isOnlyNewestLocation()
boolean	isPolling() Returns true if the PollingManager is running a background task to poll for location updates.
protected void	processUpdates(LocationUpdates updates)
protected void	rescheduleAfterFirstQueryFailed(com.veriplace.client.util.PollingManager.PollingTask task)
void	setAccessToken(Token accessToken) Specifies an access token for update queries.
void	setClient(Client client)
void	setIntervalSeconds(int intervalSeconds) Specifies the number of seconds between update queries.
void	setOnlyNewestLocation(boolean onlyNewestLocation)
void	setPolling(boolean polling) Turns the background polling task on or off.
void	setPollingFilter(PollingFilter pollingFilter) Specifies a filter implementation to determine which location updates are relevant.
void	setPollingHandler(PollingHandler pollingHandler) Specifies the handler object that will receive location updates.
void	setUserTokenStore(UserTokenStore userTokenStore) Specifies an implementation of UserTokenStore that can save and retrieve access tokens for each user.
void	startPolling() Starts a background task to poll for location updates.
protected void	startPolling(boolean waitForIntervalFirst)
void	stopPolling() Stops the background polling task.

Methods inherited from class java.lang.Object

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

Field Detail

client

protected Client client

pollingAPI

protected PollingAPI pollingAPI

accessToken

protected Token accessToken

pollingHandler

protected PollingHandler pollingHandler

pollingFilter

protected PollingFilter pollingFilter

userTokenStore

protected UserTokenStore userTokenStore

intervalSeconds

protected int intervalSeconds

onlyNewestLocation

protected boolean onlyNewestLocation

Constructor Detail

PollingManager

public PollingManager()
               throws ConfigurationException

Constructs a new PollingManager whose properties are uninitialized. Before you start polling, you must call setClient(Client) and setPollingHandler(PollingHandler).

Throws:

ConfigurationException

PollingManager

public PollingManager(Client client,
                      PollingHandler pollingHandler,
                      boolean startPollingNow)
               throws ConfigurationException

Constructs a new PollingManager, using the default in-memory cache for access tokens.

Parameters:

client - the Veriplace client

pollingHandler - the handler that will receive location updates

startPollingNow - true to start polling immediately

Throws:

ConfigurationException - if you attempted to start polling but a required properties was null

PollingManager

public PollingManager(Client client,
                      PollingHandler pollingHandler,
                      PollingFilter pollingFilter,
                      boolean startPollingNow)
               throws ConfigurationException

Constructs a new PollingManager, using the default in-memory cache for access tokens, and specifying a PollingFilter.

Parameters:

client - the Veriplace client

pollingHandler - the handler that will receive location updates

pollingFilter - a filter implementation to determine which location updates are relevant

startPollingNow - true to start polling immediately

Throws:

ConfigurationException - if you attempted to start polling but a required properties was null

PollingManager

public PollingManager(Client client,
                      PollingHandler pollingHandler,
                      PollingFilter pollingFilter,
                      Token accessToken,
                      UserTokenStore userTokenStore,
                      boolean startPollingNow)
               throws ConfigurationException

Constructs a new PollingManager, optionally specifying an alternate application token and an implementation object for access token caching.

Parameters:

client - the Veriplace client

pollingHandler - the handler that will receive location updates

pollingFilter - an optional filter implementation to determine which location updates are relevant

accessToken - the application-specific access token; null to use the one that's in the client configuration (which you should normally do; this parameter supports special cases such as aggregator services)

userTokenStore - an implementation of UserTokenStore that can save and retrieve access tokens for each user; if null, a simple in-memory cache is used

startPollingNow - true to start polling immediately

Throws:

ConfigurationException - if you attempted to start polling but a required properties was null

Method Detail

getPollingAPI

protected PollingAPI getPollingAPI(Client client)

getClient

public Client getClient()

The Veriplace client instance.

setClient

public void setClient(Client client)

getPollingHandler

public PollingHandler getPollingHandler()

setPollingHandler

public void setPollingHandler(PollingHandler pollingHandler)

Specifies the handler object that will receive location updates.

getPollingFilter

public PollingFilter getPollingFilter()

setPollingFilter

public void setPollingFilter(PollingFilter pollingFilter)

Specifies a filter implementation to determine which location updates are relevant.

getIntervalSeconds

public int getIntervalSeconds()

Returns the number of seconds between update queries.

setAccessToken

public void setAccessToken(Token accessToken)

Specifies an access token for update queries. This will override the application-specific access token from the client configuration.

setUserTokenStore

public void setUserTokenStore(UserTokenStore userTokenStore)

Specifies an implementation of UserTokenStore that can save and retrieve access tokens for each user.

setIntervalSeconds

public void setIntervalSeconds(int intervalSeconds)

Specifies the number of seconds between update queries. By default, this is one-half of the period specified with PollingAPI.setPeriodSeconds(int) or, if that was not specified, then one-half of the default period used by the server, which will be detected when we get our first query results.

isOnlyNewestLocation

public boolean isOnlyNewestLocation()

setOnlyNewestLocation

public void setOnlyNewestLocation(boolean onlyNewestLocation)

isPolling

public boolean isPolling()

Returns true if the PollingManager is running a background task to poll for location updates.

setPolling

public void setPolling(boolean polling)
                throws ConfigurationException

Turns the background polling task on or off. Equivalent to calling startPolling() or stopPolling().

Throws:

ConfigurationException

startPolling

public void startPolling()
                  throws ConfigurationException

Starts a background task to poll for location updates. Has no effect if the polling task is already running.

Throws:

ConfigurationException - if necessary properties have not been initialized

startPolling

protected void startPolling(boolean waitForIntervalFirst)
                     throws ConfigurationException

Throws:

ConfigurationException

stopPolling

public void stopPolling()

Stops the background polling task. Has no effect if the task was not running.

processUpdates

protected void processUpdates(LocationUpdates updates)

dispatchUpdate

protected void dispatchUpdate(User user,
                              LocationUpdateReference locRef,
                              java.lang.Object currentBatch)

getUpdateLocation

protected Location getUpdateLocation(User user,
                                     LocationUpdateReference locRef)
                              throws VeriplaceException

Throws:

VeriplaceException

rescheduleAfterFirstQueryFailed

protected void rescheduleAfterFirstQueryFailed(com.veriplace.client.util.PollingManager.PollingTask task)