Class 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 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,
                                                          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,
                             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