Synchronizes data among a user's devices.
Terms
Each user can have several syncable data stores, one per namespaces. Each
namespace contains a collection of datasets, each with a unique name, the listing of which is known as the
directory for the namespace. A dataset is a collection of related data, and it is the smallest unit of
syncable data that can be fetched from the server. It is up to the application developer to decide how to partition
their data into datasets. Currently, the only type of dataset available is a map of strings to strings.
Typical Usage
Connecting to a user's data
A {@link com.amazon.device.sync.SyncableDataStore} object provides access to data in the calling application's
namespace that is owned by a given user. The following code requests access to data belonging to the current session
user of the device:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java GetDataAccess}
Loading a dataset
If the dataset has a well-known name, it can be fetched directly:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java GetDatasetWithWellKnownName}
If the name of the desired dataset is unknown, datasets can be enumerated:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java EnumerateDatasets}
Working with a dataset
{@link com.amazon.device.sync.SyncableStringMap}s can be used as a Map<String, String>:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java UsingSyncableMap}
Conflict resolution
Modifications to the content are cached in the local storage and applied to the server in the
background. In the case where changes to records result in conflicts, the conflicted values are stored in local
storage.
Conflicts with respect to the current map can be retrieved by doing the following:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java GetSyncableMapConflicts}
A conflict is considered resolved (thus removed from local storage) when:
when conflicts are committed:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java ApplyConflicts}
Subscribe for update notifications
To listen to dataset changes in a namespace:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java SubscribeNamespaceUpdates}
To listen to record changes in a dataset (in a particular namespace):
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java SubscribeDatasetUpdates}
To stop receiving notifications:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java TerminateSubscription}
Synchronizing with the cloud
To upload all the pending local changes to the cloud and to download unseen changes:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java SynchronizeAll}
To upload all the pending local changes to the cloud:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java UploadAll}
To download unseen changes from the cloud:
{@sample sync/internal-sdk/src/com/amazon/device/sync/Sample.java DownloadAll}
Thread and Process Safety
Methods that return {@link java.util.concurrent.Future}s in the Sync API can be called on the main thread
but should be awaited upon in a background thread. All objects in the Sync API are thread
safe and can be concurrently shared across multiple threads.