com.digi.wva.device

Class Data

java.lang.Object

com.digi.wva.device.Data

public class Data
extends Object

This object allows users to access both raw and derived data about the current operation of a vehicle. These endpoints offer a subscription model for continuous updates, and an alarm model for handling/logging special events.

You should not need to create an instance of this class manually. Use the WVA class to manage all interactions with the WVA.

Field Summary

Fields

Modifier and Type	Field and Description
static String	SUB_SUFFIX Suffix used to create the default short names for subscriptions.

Constructor Summary

Constructors

Constructor and Description
Data(HttpClient client)

Method Summary

Methods

Modifier and Type	Method and Description
void	createAlarm(String endpoint, AlarmType type, double threshold, int seconds, WvaCallback<Void> cb) Alarm are similar to subscriptions, but they do not occur at regular intervals.
void	deleteAlarm(String endpoint, AlarmType type, boolean deleteCallbacks, WvaCallback<Void> cb) Removes the alarm attached to the given endpoint.
void	fetchVehicleData(String endpoint) Asynchronously queries the WVA for the newest data at the given endpoint and caches the result.
void	fetchVehicleData(String endpoint, WvaCallback<VehicleDataResponse> cb) Asynchronously queries the WVA for the newest data at the given endpoint and caches the result.
void	fetchVehicleDataEndpoints(WvaCallback<Set<String>> onInitialized) Initializes the cache of vehicle data endpoints for the vehicle.
VehicleDataResponse	getCachedVehicleData(String endpoint) Synchronously returns the last response received by this library for a given endpoint.
Set<String>	getVehicleDataEndpoints()
void	notifyListeners(VehicleDataEvent e) Triggers the listener associated with e's AbstractEvent.getEndpoint() endpoint name} (if there are any), and then the "catch-all" listener (if any).
void	removeAllListeners() Removes all listeners setVehicleDataListener(String, VehicleDataListener) with all endpoint names, as well as the "catch-all" listener, if any.
void	removeVehicleDataListener(String endpoint) Removes any VehicleDataListener that has been set to be invoked on new vehicle data pertaining to the given endpoint.
void	setVehicleDataListener(String endpoint, VehicleDataListener listener) Sets the VehicleDataListener to be invoked when a new vehicle data event with the given endpoint name arrives via the event channel.
void	setVehicleDataListener(VehicleDataListener listener) Sets the VehicleDataListener to be invoked when any vehicle data arrives via the event channel.
void	subscribe(String endpoint, int seconds, WvaCallback<Void> cb) Subscribe to the given vehicle data endpoint on the WVA.
void	unsubscribe(String endpoint, boolean deleteCallbacks, WvaCallback<Void> cb) Ends the periodic updating of the given endpoint.
void	updateCachedVehicleData(String uri, VehicleDataResponse response) Updates the cached value of an endpoint, and also calls notifyListeners(VehicleDataEvent) with a new Event constructed from uri and response.
void	updateCachedVehicleData(VehicleDataEvent e) Updates the cached value of an endpoint, and also calls notifyListeners(VehicleDataEvent) with e.

Methods inherited from class java.lang.Object

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

Field Detail

SUB_SUFFIX

public static final String SUB_SUFFIX

Suffix used to create the default short names for subscriptions. Appended onto the endpoint name, e.g. "EngineSpeed" becomes "EngineSpeed~sub".

See Also:

Constant Field Values

Constructor Detail

Data

public Data(HttpClient client)

Method Detail

fetchVehicleDataEndpoints

public void fetchVehicleDataEndpoints(WvaCallback<Set<String>> onInitialized)

Initializes the cache of vehicle data endpoints for the vehicle. The set of Strings passed into the provided callback is the set of vehicle data endpoint names available for subscriptions and alarms.

getVehicleDataEndpoints

public Set<String> getVehicleDataEndpoints()

Returns:

the set of available vehicle data endpoints

notifyListeners

public void notifyListeners(VehicleDataEvent e)

Triggers the listener associated with e's AbstractEvent.getEndpoint() endpoint name} (if there are any), and then the "catch-all" listener (if any).

Parameters:

e - the event to be used to trigger the aforementioned listeners

removeAllListeners

public void removeAllListeners()

Removes all listeners setVehicleDataListener(String, VehicleDataListener) with all endpoint names, as well as the "catch-all" listener, if any.

This only removes the VehicleDataListener objects from this Data's internal map. It does not remove any subscriptions or alarms from the WVA device itself.

updateCachedVehicleData

public void updateCachedVehicleData(VehicleDataEvent e)

Updates the cached value of an endpoint, and also calls notifyListeners(VehicleDataEvent) with e. It is convenient for testing when no WVA and/or TCP connection is available.

Parameters:

e - a VehicleDataEvent object

updateCachedVehicleData

public void updateCachedVehicleData(String uri,
                           VehicleDataResponse response)

Updates the cached value of an endpoint, and also calls notifyListeners(VehicleDataEvent) with a new Event constructed from uri and response. It is convenient for testing when no WVA and/or TCP connection is available.

Parameters:

uri - the web service URI whose data is being updated

response - the data from the WVA

setVehicleDataListener

public void setVehicleDataListener(VehicleDataListener listener)

Sets the VehicleDataListener to be invoked when any vehicle data arrives via the event channel.

To unset this listener, simply call again with null.

Parameters:

listener - the listener to be invoked with all event channel vehicle data

See Also:

setVehicleDataListener(String, VehicleDataListener)

setVehicleDataListener

public void setVehicleDataListener(String endpoint,
                          VehicleDataListener listener)

Sets the VehicleDataListener to be invoked when a new vehicle data event with the given endpoint name arrives via the event channel.

If you have configured both a listener for a given endpoint ("EngineSpeed", for instance), and the catch-all listener (using setVehicleDataListener(VehicleDataListener), then the listener set using this method will be invoked first.

Parameters:

endpoint - the endpoint to associate with the listener

listener - the listener to be invoked with matching event channel vehicle data

See Also:

removeVehicleDataListener(String)

removeVehicleDataListener

public void removeVehicleDataListener(String endpoint)

Removes any VehicleDataListener that has been set to be invoked on new vehicle data pertaining to the given endpoint.

Parameters:

endpoint - the endpoint whose listener is to be removed

See Also:

setVehicleDataListener(String, com.digi.wva.async.VehicleDataListener)

getCachedVehicleData

public VehicleDataResponse getCachedVehicleData(String endpoint)

Synchronously returns the last response received by this library for a given endpoint. No networking is involved in this request. To update this field to the latest value, use update() or create a subscription.

Parameters:

endpoint - the name of the vehicle data endpoint to look at

Returns:

most recent, cached value for the given vehicle data endpoint, or null if no value is cached currently

fetchVehicleData

public void fetchVehicleData(String endpoint,
                    WvaCallback<VehicleDataResponse> cb)

Asynchronously queries the WVA for the newest data at the given endpoint and caches the result.

Note that this is a relatively resource-intensive request and intended to be an ad-hoc operation. Instead of using fetchVehicleData() in a loop to query endpoints, create subscriptions to receive new information as it arrives.

Parameters:

endpoint - the name of the vehicle data endpoint to query

cb - the callback to handle the response

fetchVehicleData

public void fetchVehicleData(String endpoint)

Asynchronously queries the WVA for the newest data at the given endpoint and caches the result.

Note that this is a relatively resource-intensive request and intended to be an ad-hoc operation. Instead of using fetchVehicleData() in a loop to query endpoints, create subscriptions to receive new information as it arrives.

This method calls fetchVehicleData(String, WvaCallback) with a null callback.

Parameters:

endpoint - the name of the vehicle data endpoint to query

subscribe

public void subscribe(String endpoint,
             int seconds,
             WvaCallback<Void> cb)
               throws JSONException

Subscribe to the given vehicle data endpoint on the WVA.

See setVehicleDataListener(String, VehicleDataListener) for information on configuring a callback to be invoked each time subscription data arrives for the given endpoint.

When a subscription is created for an endpoint, that endpoint will automatically update at regular intervals. This is the preferred method of receiving vehicle data from the WVA device because it does not have to create an HTTP connection for every piece of data received.

Parameters:

endpoint - The vehicle data endpoint name to subscribe to

seconds - The interval of time between updates

cb - callback to give feedback on whether the subscription creation succeeds or not

Throws:

JSONException - If an error occurs while creating the request

unsubscribe

public void unsubscribe(String endpoint,
               boolean deleteCallbacks,
               WvaCallback<Void> cb)

Ends the periodic updating of the given endpoint. if deleteCallbacks is true, all subscription listeners for that endpoint will be dissociated as well.

This method will only delete a subscription created by the WVA Android library (or one with a name matching <endpoint>~sub).

Parameters:

endpoint - the name of the vehicle data endpoint to unsubscribe from

deleteCallbacks - whether to dissociate any VehicleDataListeners (held internally) from this endpoint

cb - callback to give feedback on whether the unsubscribe call succeeds or not

createAlarm

public void createAlarm(String endpoint,
               AlarmType type,
               double threshold,
               int seconds,
               WvaCallback<Void> cb)
                 throws JSONException

Alarm are similar to subscriptions, but they do not occur at regular intervals. Instead, alarms produce data when special conditions occur; see the JavaDoc for AlarmType for more information about the capabilities of alarms. Because alarms can be associated with near-instantaneous events, it is best-practice to always associate a callback with an alarm to make sure it is handled. There can only be one alarm of each type per endpoint (i.e. 4 alarms per endpoint).

setVehicleDataListener(String, VehicleDataListener) sets the listener invoked when new alarm events come in through the event channel. In your VehicleDataListener, use the getType() method on the event to determine whether the data is from a subscription or an alarm.

Parameters:

endpoint - the name of the vehicle data endpoint to alarm on

type - the type of alarm to create. One endpoint can't have two alarms of the same type

threshold - changes meaning depending on AlarmType

seconds - the minimum number of seconds before two alarms of the same type will be generated (for instance, only send an alarm for speeding once in a five-minute period)

cb - Executed when the HTTP response is received with the short_name of the alarm

Throws:

JSONException

deleteAlarm

public void deleteAlarm(String endpoint,
               AlarmType type,
               boolean deleteCallbacks,
               WvaCallback<Void> cb)

Removes the alarm attached to the given endpoint. If deleteCallbacks is true, the alarm listeners attached to that endpoint will also be removed.

This method will only delete an Alarm created by the WVA Android library (or one with a name matching <endpoint>~<type>).

Parameters:

endpoint - the name of the vehicle data endpoint to remove an alarm from

type - the type of alarm to delete

deleteCallbacks - whether to dissociate any VehicleDataListeners (held internally) from this alarm

cb - callback to give feedback on whether the alarm deletion call succeeds or not