An asynchronous RPC model for interacting with the Whispersync server.

Each method on an RPC class makes a single request of the Whispersync server, including

Constructing the URL (unless it is provided)
Adding standard headers
Formatting the request body (if any)
Adding authentication information
Making the request (pipelined with others if appropriate)
Parsing the response
Retrying with jittered exponential backoff if necessary
Reporting latency metrics

Typical usage

{@sample src/com/amazon/device/sync/rpc/Sample.java SyncRPCSample}

Data Hierarchy

The Whispersync data store is fundamentally hierarchical. A user has multiple apps, each of which has multiple datasets, each of which has multiple records. The entry point to the Whispersync RPC layer, {@link com.amazon.device.sync.rpc.DatasetListRPC}, provides access to the list of datasets for the calling app in one user's account. Use methods on {@link com.amazon.device.sync.rpc.DatasetRPC} to drill into datasets and records.

Threading

This component is intended for use internally to the Whispersync client. Therefore, all methods are expected to be called on background threads.

Some methods initiate asynchronous operations. Their names end in Async, and they offer two ways of obtaining the result of the operation:

Waiting on the {@link java.util.concurrent.Future} they return
Providing a {@link com.amazon.dcp.framework.Callback}, which will receive the result directly

If using a {@link com.amazon.dcp.framework.Callback}, the returned {@link java.util.concurrent.Future} may be ignored. {@link com.amazon.dcp.framework.Callback}s are called on background threads, but not necessarily the same thread that invoked the method.

Self URIs

In order to avoid having to re-enumerate datasets using {@link com.amazon.device.sync.rpc.DatasetListRPC} each time your app starts up, keep track of the URIs returned by {@link com.amazon.device.sync.rpc.DatasetRPC#getSelfUri()} and use them to instantiate {@link com.amazon.device.sync.rpc.DatasetRPC} objects directly.

Pagination

Any request that returns a large amount of data will do so in multiple pages. Such methods in the API return a {@link com.amazon.device.sync.rpc.PaginatedUpdateableResponse} to provide access to the pages. If your application fails to retrieve a given page (for example, due to lost connectivity), keep track of the URI returned by {@link com.amazon.device.sync.rpc.PaginatedUpdateableResponse#getNextPageUri()} and use it to resume your pagination later.

Updates

After the initial enumeration of data, applications should download changes incrementally. The URI returned by {@link com.amazon.device.sync.rpc.PaginatedUpdateableResponse#getUpdatesUri()} allows that.

Errors

The RPC layer takes care of retrying failed requests with proper jittered exponential backoff. It will only throw exceptions or issue onError callbacks after these retries have failed to achieve success. Therefore, any errors coming from this API should be considered non-retryable. Typically the right handling is to tell the user to try again later.

Pipelining

All methods in this namespace that make server requests return Future objects. This is not for responsiveness, as all methods are expected to be called on background threads anyway, but rather to enable HTTP pipelining of requests. To take advantage of HTTP pipelining for your requests, kick off as many requests as you can, keeping track of the Futures returned by them, and then process the Futures in order.