7.1.1 GoogleApiClient class

The GoogleApiClient is the entry point that enables your Apps to make a connection to the Google Play Services and thereafter avail of particular features/APIs (such as Location, Maps, Drive, Wallet, Games, Android Wear, Google Fit, and so on). The GoogleApiClient class provides you with the ability to connect to Google Play Services and perform synchronous and asynchronous calls to any of the various particular services.

Figure 7-3A shows an overview and partial listing of the GoogleApiClient, which resides in the package com.google.android.gms.common. The nested GoogleApiClient.Builder class is used to set up the needed API, specify the scope, and register the various connection callback listeners before build()-ing the GoogleApiClient instance.

Other related classes in the same package include the ConnectionResult class, which is not shown in the diagram. The ConnectionResult encapsulates the success or failure of the attempt at connecting to the Google Play Services. The ConnectionResult also provides useful statues and constants such as API_UNAVAILABLE, SIGN_IN_REQUIRED, DEVELOPER_ERROR, and so on, which can be used in the GoogleApiClient.OnConnectionFailedListener implementation, to determine the reason for the failure when attempting to connect to the Google Play Services from your App.

Figure 7-3B shows a sequence diagram for accessing a particular feature/API from Google Play Services—by using the GoogleApiClient.Builder; the Builder pattern pervades the various Android APIs. The call to addApi() adds the particular feature, while the call to build() returns an instance of GoogleApiClient. Invoking connect() on the GoogleApiClient instance connects it to the Google Play Services. After the client is successfully connected, the particular feature-specific APIs that were added earlier will become available to the App (and the scopes specified earlier will be applicable).

In case an App needs multiple features from Google Play Services, it is possible—in general—to add multiple APIs and multiple scopes to the same GoogleApiClient by making multiple calls to addApi() and addScope() before calling connect(). However, particularly for accessing the Wear API using the GoogleApiClient, it is recommended to use a separate instance of the GoogleApiClient exclusively for accessing the Wear API via the Wearable class (covered in the next section). The GoogleApiClient’s attempt to connect will fail if the Android Wear App is not installed on the device. Appending multiple APIs that include the Wear API and other APIs into one GoogleApiClient instance can render the other APIs to become inaccessible, although they are available.

Detailed documentation on Google Play Services is available at

https://developer.android.com/google/play-services/index.html and

http://developer.android.com/reference/com/google/android/gms/common/package-summary.html.

In the year 2014, five versions of Google Play Services (in the series 4.x, 5.x, and 6.x) were released, along with the introduction of new constructs and updated best practices as well as deprecation of some classes and interfaces. These changes are generally accompanied by useful documentation and sample code. If you are using Google Play Services in your App, it is important to keep your App abreast with the latest version of the library and the associated best practices.

7.3.1 Wear API: wearable package

The Android Wear API’s main package, wearable (com.google.android.gms.wearable), contains about seven interfaces and 10 classes.

Figure 7-4A shows an overview of the interfaces and classes within the wearable package, which includes the Wearable class and key interfaces NodeApi, DataApi, and MessageApi. The NodeApi supports Apps in becoming aware when nodes join and leave the Wear Network. The DataApi helps read, write, and sync App data between nodes. The MessageApi helps Apps send transient messages between nodes.

7.3.1.1 Node interface

The Node encapsulates basic information about a device or host on the Android Wear Network.

Figure 7-4B shows the Node interface diagram. Conceptually, the Node has two attributes—the display or human readable name (often generated from the Bluetooth device name) and an identifier string.

7.3.1.2 WearableListenerService

Another key class is the WearableListenerService that supports Apps in receiving node connectivity events and other events via the DataApi and MessageApi, which are covered in detail in the next sections.

Figure 7-4C shows the class diagram for the WearableListenerService, which extends android.app.Service. Applications that are interested in receiving node events or data/message events via the DataApi and MessageApi while in the background will need to extend this class. There can be only one WearableListenerService class in your application. Both your Wear App and the companion handheld Apps will typically implement their own WearableListenerService if each is interested in keeping updated of changes in the Android Wear Network. As it turns out, the handheld device that’s paired and tethered to the Wear device is also a node in the Android Wear Network.

7.3.1.3 DataEvent

The DataEvent is an interface for receiving data changes via the data change listener in the DataApi or the WearableListenerService.

Figure 7-4D shows the DataEvent (as well as the MessageEvent, which is covered in the next section). The getDataItem() method provides access to the data item, while the getType() method specifies whether the data was changed(TYPE_CHANGED) or deleted(TYPE_DELETED).

7.3.2 Wearable class

The Wearable class is the main entry point into the Wear API and contains key static attributes: API, NodeApi, DataApi, and MessageApi. It also contains a nested class WearableOptions.

Figure 7-5A shows the Wearable class and its attributes and nested class WearableOptions. The static attribute API is used in invoking the addApi() method while building the GoogleApiClient instance.

The inner class Wearable.WearableOptions represents the API configuration parameters for the Wear API.

Figure 7-5B shows the Wearable.WearableOptions inner class, which implements the Api. piOptions.ApiOptions interface from the com.google.android.gms.common.api package.

7.3.3 NodeApi

The NodeApi interface supports detecting and learning about nodes as they connect and join the Wear network or disconnect and drop off. The NodeApi can be said to be tuned into the Node connection and disconnection events on the Wear network. When the NodeApi detects these Node connection and disconnection events, it delivers them to the Wear Apps, which have registered interest in these events.

Figure 7-6 shows the class diagram of the NodeApi class and it has the nested interface NodeApi.NodeListener (which helps your App detect that a peer on the Wear Network has connected or disconnected), NodeApi.GetConnectedNodesResult (which helps your App obtain a list of connected nodes on the Wear Network), and NodeApi.GetLocalNodeResult (which helps your App in accessing the node object which represents “this” device, the local device that your App is running on).

7.3.4 DataApi

The DataApi interface and its associated family of interfaces and classes provide Apps with the ability to read, write, and synchronize data across the devices on an Android Wear network while maintaining the privacy of the data within the App. Fundamentally, the DataApi provides the put and get functionality in order to read and write data to the Wear Network. The DataApi works closely with the DataItem, which encapsulates the data.

Figure 7-7 shows a partial listing of the DataApi interface and its inner interfaces DataApi.DataListener (which can be used to register a listener using the addListener() method), DataApi.DataItemResult (which can be used to read a single DataItem when using the getDataItem() family of calls), DataApi.DeleteDataItemsResult (which is used to verify that number of items deleted upon making the call to deleteDataItems()), and the DataApi.GetFdForAssetResult (which can be used to obtain the file descriptor of an Asset—a binary blob data covered in Section 7.6.1 of this chapter—when making the getFdForAsset() family of calls).

Fundamentally, the DataApi provides the ability to add, retrieve, and delete DataItems on the Android Wear Network. It also provides the ability in the nested DataListener to listen for changes in the data. The WearableListenerService, which implements the DataApi and was covered earlier in this chapter, is useful for listening for data changes in the background. Calling the getDataItems() on booting can help keep up to date with changes while the device was offline.

7.4.1 DataItem

A DataItem is an interface that represents the data that needs to be read and written via the DataApi to the Android Wear network. DataItems are inherently synchronized across all the nodes in the user’s Android Wear Network. DataItems can be set on a local node even while that node is not connected to the Wear network. Whenever such a local node gets connected to the Wear network, the local DataItems that are pending synchronization will get synchronized.

Each DataItem contains a payload, which is a byte array. The payload is intended to be small in size—up to about 100 KB—but in practice you must strive to keep your DataItem’s payload much smaller than this limit. As with all remote procedure calls and interprocess communication, it is best to lean toward the side of being more conservative. Chapter 3 on Android IPC and AIDL has covered some of these constraints on the size of the payloads when performing IPC in general. Assets—covered in a subsequent section—are appropriate for encapsulating larger binary, blob data such as images. Each DataItem is identified by a path or URI on the Wear network in the format wear://<node_id>/<path>, where node_id represents the node that created the data, while the path portion of the URI is defined by the application.

A given DataItem remains private to the App that created it. Although the DataItem is a fundamental block for the persistence and synchronization of data on the Wear network, it does not have a constructor or Builder—the classes that are used when creating and using DataItems in the DataApi operations include the PutDataRequest, DataMapItem, and DataMap; these have been covered in the following sections.

Figure 7-8 shows the DataItem interfaces along with the DataItemMap and DataMap classes.

The DataItem interface extends the Freezable interface from the com.google.android.gms.common.data package. The Freezable interface pertains to transforming volatile data into an immutable representation via its freeze() method. When the application code receives data change events in the listener such as onDataChanged(), it receives a DataEventBuffer of data events. When items in this buffer are used outside of the call scope, freeze() should be invoked on such items.

DataItems are not intended for concurrent modifications and attempting so can result in inconsistent results. Therefore, it becomes the responsibility of the App to implement its concurrent modification strategy. In one approach, only the creator node that originally created the DataItem may modify the data. There are several other approaches, and it is left to the App to use a concurrent update strategy for its DataItems.

7.4.2 DataMapItem

The DataMapItem wraps a DataItem like object and is a structured and serializable representation of a DataItem. The original DataItem is not expected to be modified after the DataMapItem has been created based on it. Figure 7-8 in the previous section includes the class diagram of the DataMapItem.

The DataMapItem is closely associated with the PutDataMapRequest and the DataMap classes, both of which are covered in the following sections.

7.4.3 DataMap

The DataMap provides a key value pair-based support for storing basic data types such as int, long, float, double, byte, as well as arrays and Bundles. Figure 7-8 shows some of the methods available in the DataMap class. While the DataItem works with raw bytes of payload data and requires serialization and deserialization to be handled in the application code, the DataMap provides off-the-shelf support for storing fundamental data types as well as Bundles. The DataMap works along with the PutDataMapRequest class, covered in the following section.

7.5.1 PutDataRequest

The PutDataRequest class implements the Parcelable interface and is used to create and encapsulate new DataItems on the Android Wear Network. It has a static create() method which supports creating an instance of PutDataRequest with an associated, encapsulated DataItem instance. The setData() method sets the payload on the encapsulated DataItem instance. The putAsset() method adds an Asset to the associated DataItem. Once the PutDataRequest instance has been populated, it can be added to the Android Wear Network by calling the DataApi’s putDataItem() method.

Figure 7-9 shows class diagram of the PutDataRequest class that shows several of its available methods. The PutDataRequest is the key class that works with the DataApi in order to make the request to put/add DataItems to the Android Wear Network.

7.5.2 PutDataMapRequest

The PutDataMapRequest is a useful utility closely associated with and secondary to the PutDataRequest. The PutDataMapRequest and DataMap classes make it convenient to sync data to the Android Wear Network by using the serialization and de-serialization that’s available off the shelf. The PutDataMapRequest encapsulates a DataMap.

As shown in Figure 7.10, the PutDataMapRequest provides static methods to create its instance. Once instantiated, the getDataMap() method provides access to the encapsulated DataMap. Once the DataMap instance has been set with data as intended, the asPutDataRequest() method creates a PutDataRequest instance with the encapsulated data. After that, calling the DataApi’s putDataItem() method makes the request to add the data to the Android Wear Network. The DataApi does not have a put method that caters to the PutDataMapRequest directly.

There are far fewer methods in PutDataMapRequest as compared to PutDataRequest, because it’s the DataMap operations that address the setting of the data.

7.6.1 Asset class

The Asset class represents data that may not yet have been added to the Android Wear Network (Figure 7-11A).

The Asset class implements the Parcelable interface. The Asset instance can be created via its static create family of methods. A bitmap can be converted into a byte stream, which can be used to create an Asset instance using the static createFromBytes() method. The PutDataRequest covered in the earlier section has a method putAsset(), which can be used to populate the asset into the request. The DataApi has a putDataItem() method, which can be used to make the request to add data to the Android Wear Network. Alternatively, the Asset instance can be added to a DataMap instance via its putAsset() method, and the PutDataMapRequest can be used to create the PutDataRequest eventually.

The getDigest() method returns a digest—a one way hash of the content—which can be used to identify the Asset across devices on the Android Wear Network.

Assets can be received/extracted from data change events in the listener callbacks.

7.6.2 DataItemAsset interface

The DataItemAsset is a reference to an Asset after it has been added to the Android Wear Network as part of a PutDataRequest (Figure 7-11B).

The getId() method returns a unique identifier for the Asset in the Android Wear Network. The getDataItemKey() returns an identifier for the asset in the context of an existing DataItem.