DataClient

AI-generated Key Takeaways

• DataClient provides an API for reading and writing data items and assets across an Android Wear network.

• Data items are synchronized across all connected devices and are private to the creating application.

• Data items are identified by a URI with the format wear://<node_id>/<path>, and URIs can use wildcards for matching across nodes.

• Concurrent modification of data items from different nodes can lead to inconsistent results, recommending patterns like "Creator owns data items" or "Producer-consumer".

• The DataClient class includes methods for adding/removing listeners for data change events, deleting data items, retrieving data items, retrieving assets, and adding data items.

public abstract class DataClient extends GoogleApi<Wearable.WearableOptions>

Exposes an API for components to read or write data items and assets.

A DataItem is synchronized across all devices in an Android Wear network. It is possible to set data items while not connected to any nodes. Those data items will be synchronized when the nodes eventually come online.

Data items are private to the application that created them, and are only accessible by that application on other nodes. They should generally be small in size, relying on assets for the transfer of larger, more persistent data objects such as images.

DataItem URI format

Each data item is identified by a URI, accessible with DataItem.getUri(), that indicates the item's creator and path. Fully specified URIs follow the following format:

wear://<node_id>/<path>

where <node_id> is the node ID of the wearable node that created the data item, and <path> is an application-defined path. This means that given a data item's URI, calling Uri.getHost() will return the creator's node ID.

Some methods, such as getDataItems(Uri) and addListener(OnDataChangedListener, Uri, int), support wildcard node IDs to match data items with the same path or path prefix created by multiple nodes. A wildcard data item URI has the following format:

wear://*/<path>

See method documentation for details.

Concurrency

Concurrent modification of data items from different nodes may result in inconsistent results. It is recommended that apps are built with some concept of ownership of data items. Two common patterns are:

• Creator owns data items: Data items may be updated only by the original creator node.
• Producer-consumer: One node is responsible for creating a data item, and a second node is responsible for deleting it, once it has been processed. Data items should have unique IDs when using this pattern, and data items should not be modified once created.

Nested Class Summary

@interface	DataClient.FilterType		Data filter types.
class	DataClient.GetFdForAssetResponse		Contains a file descriptor for the requested asset.
interface	DataClient.OnDataChangedListener		Used with DataClient.addListener(DataClient.OnDataChangedListener) to receive data events.

Constant Summary

String	ACTION_DATA_CHANGED	Data changed action for use in manifest-based listener filters.
int	FILTER_LITERAL	Filter type for getDataItems(Uri, int), deleteDataItems(Uri, int), addListener(OnDataChangedListener, Uri, int): if this filter is set, the given URI will be taken as a literal path, and the operation will apply to the matching item only.
int	FILTER_PREFIX	Filter type for getDataItems(Uri, int), deleteDataItems(Uri, int), addListener(OnDataChangedListener, Uri, int): if this filter is set, the given URI will be taken as a path prefix, and the operation will apply to all matching items.

Public Method Summary

abstract Task<Void>	addListener(DataClient.OnDataChangedListener listener) Registers a listener to receive data item changed and deleted events.
abstract Task<Void>	addListener(DataClient.OnDataChangedListener listener, Uri uri, int filterType) Registers a listener to receive data item changed and deleted events.
abstract Task<Integer>	deleteDataItems(Uri uri, int filterType) Removes all specified data items from the Android Wear network.
abstract Task<Integer>	deleteDataItems(Uri uri) Removes all specified data items from the Android Wear network.
abstract Task<DataItem>	getDataItem(Uri uri) Retrieves a single DataItem from the Android Wear network.
abstract Task<DataItemBuffer>	getDataItems(Uri uri, int filterType) Retrieves all data items matching the provided URI and filter type, from the Android Wear network.
abstract Task<DataItemBuffer>	getDataItems() Retrieves all data items from the Android Wear network.
abstract Task<DataItemBuffer>	getDataItems(Uri uri) Retrieves all data items matching the provided URI, from the Android Wear network.
abstract Task<DataClient.GetFdForAssetResponse>	getFdForAsset(DataItemAsset asset) Retrieves a ParcelFileDescriptor pointing at the bytes of an asset.
abstract Task<DataClient.GetFdForAssetResponse>	getFdForAsset(Asset asset) Retrieves a ParcelFileDescriptor pointing at the bytes of an asset.
abstract Task<DataItem>	putDataItem(PutDataRequest request) Adds a DataItem to the Android Wear network.
abstract Task<Boolean>	removeListener(DataClient.OnDataChangedListener listener) Removes a listener which was previously added through addListener(OnDataChangedListener) or addListener(OnDataChangedListener, Uri, int).

Inherited Method Summary

From class com.google.android.gms.common.api.GoogleApi

String

getApiFallbackAttributionTag(Context arg0)

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Constants

public static final String ACTION_DATA_CHANGED

Data changed action for use in manifest-based listener filters.

See Also

• WearableListenerService

Constant Value: "com.google.android.gms.wearable.DATA_CHANGED"

public static final int FILTER_LITERAL

Filter type for getDataItems(Uri, int), deleteDataItems(Uri, int), addListener(OnDataChangedListener, Uri, int): if this filter is set, the given URI will be taken as a literal path, and the operation will apply to the matching item only.

Constant Value: 0

public static final int FILTER_PREFIX

Filter type for getDataItems(Uri, int), deleteDataItems(Uri, int), addListener(OnDataChangedListener, Uri, int): if this filter is set, the given URI will be taken as a path prefix, and the operation will apply to all matching items.

Constant Value: 1

Public Methods

public abstract Task<Void> addListener (DataClient.OnDataChangedListener listener)

Registers a listener to receive data item changed and deleted events. This call should be balanced with a call to removeListener(OnDataChangedListener), to avoid leaking resources.

Listeners will be called on the main thread, or the looper set in Wearable.WearableOptions.

public abstract Task<Void> addListener (DataClient.OnDataChangedListener listener, Uri uri, int filterType)

Registers a listener to receive data item changed and deleted events. This call should be balanced with a call to removeListener(OnDataChangedListener), to avoid leaking resources.

uri and filterType can be used to filter the data item changes sent to the listener. For example, if uri and filterType create a path prefix filter, then only items matching that prefix will be notified. The uri follows the rules of the <data> element of <intent-filter>. The path is ignored if a URI host is not specified. The host should be an Android Wear node ID, or * to match any node. For example, you should use:

wear://*/<path>

or

wear://<nodeId>/<path>

Listeners will be called on the main thread, or the looper set in Wearable.WearableOptions.

Callers wishing to be notified of events in the background should use WearableListenerService.

public abstract Task<Integer> deleteDataItems (Uri uri, int filterType)

Removes all specified data items from the Android Wear network.

If uri is fully specified, this method will delete at most one data item. If uri contains a wildcard host, multiple data items may be deleted, since different nodes may create data items with the same path. See DataClient for details of the URI format.

The filterType parameter changes the interpretation of uri. For example, if uri represents a path prefix, all items matching that prefix will be deleted.

Returns

• the number of deleted items.

public abstract Task<Integer> deleteDataItems (Uri uri)

Removes all specified data items from the Android Wear network.

If uri is fully specified, this method will delete at most one data item. If uri contains a wildcard host, multiple data items may be deleted, since different nodes may create data items with the same path. See DataClient for details of the URI format.

Returns

• the number of deleted items.

public abstract Task<DataItem> getDataItem (Uri uri)

Retrieves a single DataItem from the Android Wear network. A fully qualified URI must be specified. The URI's host must be the ID of the node that created the item.

See DataClient for details of the URI format.

public abstract Task<DataItemBuffer> getDataItems (Uri uri, int filterType)

Retrieves all data items matching the provided URI and filter type, from the Android Wear network.

The URI must contain a path. If uri is fully specified, at most one data item will be returned. If uri contains a wildcard host, multiple data items may be returned, since different nodes may create data items with the same path. See DataClient for details of the URI format.

Callers must call AbstractDataBuffer.release() on the returned buffer when finished processing results.

The filterType parameter changes the interpretation of uri. For example, if uri represents a path prefix, all items matching that prefix will be returned.

public abstract Task<DataItemBuffer> getDataItems ()

Retrieves all data items from the Android Wear network.

Callers must call AbstractDataBuffer.release() on the returned buffer when finished processing results.

public abstract Task<DataItemBuffer> getDataItems (Uri uri)

Retrieves all data items matching the provided URI, from the Android Wear network.

The URI must contain a path. If uri is fully specified, at most one data item will be returned. If uri contains a wildcard host, multiple data items may be returned, since different nodes may create data items with the same path. See DataClient for details of the URI format.

Callers must call AbstractDataBuffer.release() on the returned buffer when finished processing results.

public abstract Task<DataClient.GetFdForAssetResponse> getFdForAsset (DataItemAsset asset)

Retrieves a ParcelFileDescriptor pointing at the bytes of an asset. Only assets previously stored in a DataItem may be retrieved.

public abstract Task<DataClient.GetFdForAssetResponse> getFdForAsset (Asset asset)

Retrieves a ParcelFileDescriptor pointing at the bytes of an asset. Only assets previously stored in a DataItem may be retrieved.

public abstract Task<DataItem> putDataItem (PutDataRequest request)

Adds a DataItem to the Android Wear network. The updated item is synchronized across all devices.

public abstract Task<Boolean> removeListener (DataClient.OnDataChangedListener listener)

Removes a listener which was previously added through addListener(OnDataChangedListener) or addListener(OnDataChangedListener, Uri, int).