Module com.gluonhq.cloudlink.client

Package com.gluonhq.cloudlink.client.data

Class DataClient

java.lang.Object

com.gluonhq.cloudlink.client.data.DataClient

public class DataClient
extends Object

The DataClient is the access point to the Gluon CloudLink Data Storage service. It assists in using the DataProvider with data stored on Gluon CloudLink as the data source. For instance, to retrieve a list from Gluon CloudLink, you can use the following code:

     DataClient dataClient = DataClientBuilder.create().build();
     GluonObservableList<Item> items = DataProvider.retrieveList(dataClient.createListDataReader("items", Item.class));
 

Note: data will be always be stored in the private storage location for the application on the device. As a result, the DataClient depends on the StorageService, so make sure that the storage plugin has been enabled in your Gluon Mobile application build configuration:

    <dependency>
        <groupId>com.gluonhq.attach</groupId>
        <artifactId>storage</artifactId>
        <version>${attach.version}</version>
    </dependency>
    ...
    <plugin>
      <groupId>com.gluonhq</groupId>
      <artifactId>client-maven-plugin</artifactId>
      <version>${client.plugin.version}</version>
      <configuration>
        <attachList>
          <list>storage</list>
        </attachList>
      </configuration>
    </plugin>
 

Method Summary

Modifier and Type	Method	Description
<E> ListDataReader<E>	createListDataReader(String identifier, Class<E> objectClass)	Creates an instance of ListDataReader that can be passed directly in the DataProvider.retrieveList(ListDataReader) method.
<E> ListDataReader<E>	createListDataReader(String identifier, Class<E> objectClass, SyncFlag... syncFlags)	Creates an instance of ListDataReader that can be passed directly in the DataProvider.retrieveList(ListDataReader) method.
<T> ObjectDataReader<T>	createObjectDataReader(String identifier, Class<T> objectClass, SyncFlag... syncFlags)	Creates an instance of ObjectDataReader that can be passed directly in the DataProvider.retrieveObject(ObjectDataReader) method.
<T> ObjectDataRemover<T>	createObjectDataRemover()	Creates an instance of ObjectDataRemover that can be passed directly in the DataProvider.removeObject(GluonObservableObject, ObjectDataRemover) method.
<T> ObjectDataWriter<T>	createObjectDataWriter(String identifier, Class<T> objectClass, SyncFlag... syncFlags)	Creates an instance of ObjectDataWriter that can be passed directly in the DataProvider.storeObject(Object, ObjectDataWriter) method.
OperationMode	getOperationMode()	Get the operation mode to use when storing or retrieving data with this DataClient instance.
<E> void	push(GluonObservableList<E> list)	Push any changes made to the list.
<E> void	push(GluonObservableList<E> list, boolean fully)	Push any changes made to the list.
<T> void	push(GluonObservableObject<T> object)	Push any changes made to the object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getOperationMode

public OperationMode getOperationMode()

Get the operation mode to use when storing or retrieving data with this DataClient instance.

Returns:

the operation mode to use when storing or retrieving data

createObjectDataReader

public <T> ObjectDataReader<T> createObjectDataReader(String identifier,
                                                      Class<T> objectClass,
                                                      SyncFlag... syncFlags)

Creates an instance of ObjectDataReader that can be passed directly in the DataProvider.retrieveObject(ObjectDataReader) method. The object data reader will read the object with the specified identifier.

Any of the following synchronization flags can be passed in with the syncFlags parameter: SyncFlag.OBJECT_READ_THROUGH and SyncFlag.OBJECT_WRITE_THROUGH. All other flags will be silently ignored.

Type Parameters:

T - the type of the object that is retrieved

Parameters:

identifier - the identifier of the object to retrieve

objectClass - the class of the object to retrieve

syncFlags - an optional list of synchronization flags

Returns:

an ObjectDataReader instance that reads the object with the specified parameters

createObjectDataWriter

public <T> ObjectDataWriter<T> createObjectDataWriter(String identifier,
                                                      Class<T> objectClass,
                                                      SyncFlag... syncFlags)

Creates an instance of ObjectDataWriter that can be passed directly in the DataProvider.storeObject(Object, ObjectDataWriter) method. The object data writer will write the object with the specified identifier.

Any of the following synchronization flags can be passed in with the syncFlags parameter: SyncFlag.OBJECT_READ_THROUGH and SyncFlag.OBJECT_WRITE_THROUGH. All other flags will be silently ignored.

Type Parameters:

T - the type of the object that is stored

Parameters:

identifier - the identifier of the object to store

objectClass - the class of the object to store

syncFlags - an optional list of synchronization flags

Returns:

an ObjectDataWriter instance that writes the object with the specified parameters

createObjectDataRemover

public <T> ObjectDataRemover<T> createObjectDataRemover()

Creates an instance of ObjectDataRemover that can be passed directly in the DataProvider.removeObject(GluonObservableObject, ObjectDataRemover) method. The observable object that is passed in with the removeObject method will be used to get the identifier of the object that needs to be removed.

Note: this method can only be used for removing observable objects that were either retrieved using an ObjectDataReader created by a DataClient instance or stored using an ObjectDataWriter created by a DataClient instance.

Type Parameters:

T - the type of the object to remove

Returns:

an ObjectDataRemover instance that can remove an object

createListDataReader

public <E> ListDataReader<E> createListDataReader(String identifier,
                                                  Class<E> objectClass)

Creates an instance of ListDataReader that can be passed directly in the DataProvider.retrieveList(ListDataReader) method. This method is the same as calling createListDataReader(String, Class, SyncFlag...) with the following two synchronization flags: SyncFlag.LIST_READ_THROUGH and SyncFlag.LIST_WRITE_THROUGH.

Type Parameters:

E - the type of the objects contained in the list to read

Parameters:

identifier - the identifier of the list to retrieve

objectClass - the class of the objects contained in the list to read

Returns:

a ListDataReader instance that reads a list together with its objects using the specified parameters

createListDataReader

public <E> ListDataReader<E> createListDataReader(String identifier,
                                                  Class<E> objectClass,
                                                  SyncFlag... syncFlags)

Creates an instance of ListDataReader that can be passed directly in the DataProvider.retrieveList(ListDataReader) method. The list data reader will read the list with the specified identifier together with the objects it contains.

Type Parameters:

E - the type of the objects contained in the list to read

Parameters:

identifier - the identifier of the list to retrieve

objectClass - the class of the objects contained in the list to read

syncFlags - an optional list of synchronization flags

Returns:

a ListDataReader instance that reads a list together with its objects using the specified parameters

push

public <E> void push(GluonObservableList<E> list)

Push any changes made to the list. This method is the same as calling push(GluonObservableList, boolean) with a value of true for the fully parameter.

Type Parameters:

E - the type of the objects contained in the list to push

Parameters:

list - the observable list to push

See Also:

push(GluonObservableList, boolean)

push

public <E> void push(GluonObservableList<E> list,
                     boolean fully)

Push any changes made to the list. This method is useful for lists that are retrieved without write through flags. Every time an item is removed, added or updated in the list, that item will be marked for removal, addition or update respectively. When calling this method, these marks will be checked for on every item and reflected back to the list in the data store. Should an item have multiple markers, the order of precedence of the markers is as follows: removal over addition over update.

When the fully parameter is set to true, all items in the list will be considered as marked for update. Otherwise, only items that were removed or added or updated manually will be pushed. Again, note that when using fully with a value of true, items that were marked for removal will still be removed because the removal marker takes precedence over the update marker.

Type Parameters:

E - the type of the objects contained in the list to push

Parameters:

list - the observable list to push

fully - when true all items in the list are considered as marked for update

push

public <T> void push(GluonObservableObject<T> object)

Push any changes made to the object. This method is useful for objects that are retrieved without the write through flag.

A push can be used as a convenient way to store updates to an observable object that was already retrieved. Consider the following code, to see an example of the push method:

     GluonObservableObject<Sample> sample = DataProvider.retrieveObject(dataClient.createObjectDataReader("sample", Sample.class));

     // somewhere the object gets updated and you want to store the updates
     dataClient.push(sample);
 

Actually, the push method is a simple alternative to the storeObject method that is available in DataProvider. Using that method, updating the object can be done as follows, which is more cumbersome to write and you need to pass in the object identifier again:

     DataProvider.storeObject(sample.get(), dataClient.createObjectDataWriter("sample", Sample.class));
 

Note: this method can only be used with observable objects that were either retrieved using an ObjectDataReader created by a DataClient instance or stored using an ObjectDataWriter created by a DataClient instance.

Type Parameters:

T - the type of the object to push

Parameters:

object - the observable object to push