com.amazonaws.mobileconnectors.cognito
Interface Dataset

public interface Dataset

Dataset is the container of Records. It can have up to 1k Record or 1 MB in size. A typical use of Dataset is the following.

 // open or create dataset
 Dataset dataset = cognitoClient.openOrCreate("new dataset");
 // synchronize. It pulls down latest changes from remote storage
 // and push local changes to remote storage
 dataset.synchronize(syncCallback);
 // reads value
 String highScore = dataset.getValue("high_score");
 String name = dataset.getValue("name");
 // sets value
 dataset.put("high_score", "90");
 dataset.put("name", "John");
 // push changes to remote if needed
 dataset.synchronizesyncCallback);
 

Nested Class Summary

static interface

Dataset.SyncCallback This is the callback used in synchronize(SyncCallback).

Method Summary

void	delete() Delete this Dataset.
java.lang.String	get(java.lang.String key) Gets the value of a Record with the given key.
java.util.Map<java.lang.String,java.lang.String>	getAll() Gets the key-value representation of all records of this dataset.
java.util.List<Record>	getAllRecords() Retrieves all raw records, marked deleted or not, from local storage.
DatasetMetadata	getDatasetMetadata() Retrieves the associated DatasetMetadata from local storage.
long	getLastSyncCount() Get the last sync count of this Dataset.
long	getSizeInBytes(java.lang.String key) Gets the size of a record with the given key.
long	getTotalSizeInBytes() Gets the total size in bytes of this dataset.
boolean	isChanged(java.lang.String key) Retrieves the status of a record.
void	put(java.lang.String key, java.lang.String value) Puts a Record with the given key and value into the Dataset.
void	putAll(java.util.Map<java.lang.String,java.lang.String> values)
void	remove(java.lang.String key) Marks a Record with the given key as deleted.
void	resolve(java.util.List<Record> resolvedConflicts) Saves resolved conflicting Records into local storage.
void	subscribe() Subscribes the user to update notifications for a dataset.
void	synchronize(Dataset.SyncCallback callback) Synchronize Dataset between local storage and remote storage.
void	synchronizeOnConnectivity(Dataset.SyncCallback callback) Attempt to synchronize Dataset when connectivity is available.
void	unsubscribe() Unsubscribe the user from receiving notifications on updates to a dataset which has previously been subscribed to.

Method Detail

getDatasetMetadata

DatasetMetadata getDatasetMetadata()

Retrieves the associated DatasetMetadata from local storage.

Returns:

metadata

synchronize

void synchronize(Dataset.SyncCallback callback)

Synchronize Dataset between local storage and remote storage.

Parameters:

callback - call back

synchronizeOnConnectivity

void synchronizeOnConnectivity(Dataset.SyncCallback callback)

Attempt to synchronize Dataset when connectivity is available. If the connectivity is available right away, it behaves the same as synchronize(SyncCallback). Otherwise it listens to connectivity changes, and will do a sync once the connectivity is back. Note that if this method is called multiple times, only the last synchronize request is kept and only the last callback will fire. If either the dataset or the callback is garbage collected, this method will not perform a sync and the callback won't fire.

Parameters:

callback - call back

get

java.lang.String get(java.lang.String key)

Gets the value of a Record with the given key. If the Record doesn't exist or is marked deleted, null will be returned.

Parameters:

key - key of the record in the dataset.

Returns:

the string value of the record, or null if the record doesn't exist or is marked deleted.

put

void put(java.lang.String key,
         java.lang.String value)

Puts a Record with the given key and value into the Dataset. If a Record with the same key exists, its value will be overwritten. If a Record is marked as deleted previously, then it will be resurrected with new value while the sync count continues with previous value. No matter whether the value changes or not, the record is considered as updated, and it will be written to Cognito Sync service on next synchronize operation. If value is null, a NullPointerException will be thrown.

Parameters:

key - key of the record

value - string value of a Record to be put into the Dataset

putAll

void putAll(java.util.Map<java.lang.String,java.lang.String> values)

Parameters:

values -

remove

void remove(java.lang.String key)

Marks a Record with the given key as deleted. Nothing happens if the Record doesn't exist or is deleted already.

Parameters:

key -

resolve

void resolve(java.util.List<Record> resolvedConflicts)

Saves resolved conflicting Records into local storage. This is used inside Dataset.SyncCallback.onConflict(Dataset, List) after you resolve all conflicts.

Parameters:

resolvedConflicts - a list of records to save into local storage

getAllRecords

java.util.List<Record> getAllRecords()

Retrieves all raw records, marked deleted or not, from local storage.

Returns:

a list of all raw records

getAll

java.util.Map<java.lang.String,java.lang.String> getAll()

Gets the key-value representation of all records of this dataset. Marked as deleted records are excluded.

Returns:

key-value representation of all records, excluding deleted ones

getTotalSizeInBytes

long getTotalSizeInBytes()

Gets the total size in bytes of this dataset. Records that are marked as deleted don't contribute to the total size.

Returns:

size in bytes

getSizeInBytes

long getSizeInBytes(java.lang.String key)

Gets the size of a record with the given key. If the key is deleted, -1 will be returned.

Parameters:

key - the key of a record

Returns:

size in bytes

isChanged

boolean isChanged(java.lang.String key)

Retrieves the status of a record.

Parameters:

key - the key of a record

Returns:

True if it is modified locally. False otherwise

delete

void delete()

Delete this Dataset. No more following operations on this dataset, or else IllegalStateException will be thrown.

getLastSyncCount

long getLastSyncCount()

Get the last sync count of this Dataset.

Returns:

last sync count

subscribe

void subscribe()

Subscribes the user to update notifications for a dataset. This should only be called after the device has been registered.

unsubscribe

void unsubscribe()

Unsubscribe the user from receiving notifications on updates to a dataset which has previously been subscribed to.