Distributed Data Object Development

When to Use

The distributedDataObject module provides APIs to implement data collaboration of the same application across multiple devices. In addition, the devices that form a Super Device can listen for object status and data changes with each other.

For example, when the data of a distributed data object is added, deleted, or modified for application A on device 1, application A on device 2 can obtain the updated data. In addition, device 2 can listen for data changes and online/offline of the data objects on device 1.

Available APIs

For details about the APIs, see Distributed Data Object.

Creating a Distributed Data Object Instance

Call createDistributedObject() to create a distributed data object instance. You can specify the attributes of the instance in source.

Table 1 API for creating a distributed data object instance

Generating a Session ID

Call genSessionId() to generate a session ID randomly. The generated session ID can be used to set the session ID of a distributed data object.

Table 2 API for generating a session ID randomly

Setting a Session ID for a Distributed Data Object

Call setSessionId() to set a session ID for a distributed data object. The session ID is a unique identifier for one collaboration across devices. The distributed data objects to be synchronized must be associated with the same session ID.

Table 3 API for setting a session ID

Observing Data Changes

Call on() to subscribe to data changes of a distributed data object. When the data changes, a callback will be invoked to return the data changes. You can use off() to unsubscribe from the data changes.

Table 4 APIs for observing data changes of a distributed data object

Observing Online or Offline Status

Call on() to subscribe to status changes of a distributed data object. The status can be online or offline. When the status changes, a callback will be invoked to return the status. You can use off() to unsubscribe from the status changes.

Table 5 APIs for observing status changes of a distributed data object

Saving or Deleting a Distributed Data Object

Call save() to save a distributed data object. When the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored.

Call revokeSave() to delete a distributed data object that is no longer required. If the distributed data object is saved on the local device, revokeSave() will delete the data from all trusted devices. If the distributed data object is not saved on the local device, revokeSave() will delete the data from the local device.

The saved data will be released in the following cases:

• The data is stored for more than 24 hours.
• The application has been uninstalled.
• Data is successfully restored.

Table 6 APIs for saving and deleting a distributed data object

How to Develop

The following example shows how to implement distributed data object synchronization.

1. Import the @ohos.data.distributedDataObject module to the development environment.

   import distributedObject from '@ohos.data.distributedDataObject';   

1. Apply for the permission.

Add the permissions required (FA model) to the config.json file.

   {
       "module": {
           "reqPermissions": [
               {
                   "name": "ohos.permission.DISTRIBUTED_DATASYNC"
               }
           ]
       }
   }

For the apps based on the stage model, see Declaring Permissions.

This permission must also be granted by the user when the application is started for the first time.

   import featureAbility from '@ohos.ability.featureAbility';
	
   function grantPermission() {
       console.info('grantPermission');
       let context = featureAbility.getContext();
       context.requestPermissionsFromUser(['ohos.permission.DISTRIBUTED_DATASYNC'], 666, function (result) {
           console.info(`result.requestCode=${result.requestCode}`)
    
       })
       console.info('end grantPermission');
   }
    
   grantPermission();

1. Obtain a distributed data object instance.

   let localObject = distributedObject.createDistributedObject({
       name: undefined,
       age: undefined,
       isVis: true,
       parent: undefined,
       list: undefined
   });
   let sessionId = distributedObject.genSessionId();

1. Add the distributed data object instance to a network for data synchronization. The data objects in the synchronization network include the local and remote objects.

   // Local object
   let localObject = distributedObject.createDistributedObject({
       name: "jack",
       age: 18,
       isVis: true,
       parent: { mother: "jack mom", father: "jack Dad" },
       list: [{ mother: "jack mom" }, { father: "jack Dad" }]
   });
   localObject.setSessionId(sessionId);
   
   // Remote object
   let remoteObject = distributedObject.createDistributedObject({
       name: undefined,
       age: undefined,
       isVis: true,
       parent: undefined,
       list: undefined
   });
   // After learning that the local device goes online, the remote object synchronizes data. That is, name changes to jack and age to 18.
   remoteObject.setSessionId(sessionId);

1. Observe the data changes of the distributed data object. You can subscribe to data changes of the remote object. When the data in the remote object changes, a callback will be invoked to return the data changes.

   function changeCallback(sessionId, changeData) {
       console.info("change" + sessionId);
   
       if (changeData != null && changeData != undefined) {
           changeData.forEach(element => {
               console.info("changed !" + element + " " + localObject[element]);
           });
       }
   } 
   
   // To refresh the page in changeCallback, correctly bind (this) to the changeCallback.
   localObject.on("change", this.changeCallback.bind(this));

1. Modify attributes of the distributed data object. The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types).

   localObject.name = "jack";
   localObject.age = 19;
   localObject.isVis = false;
   localObject.parent = { mother: "jack mom", father: "jack Dad" };
   localObject.list = [{ mother: "jack mom" }, { father: "jack Dad" }];

NOTE
For the distributed data object of the complex type, only the root attribute can be modified. The subordinate attributes cannot be modified.

   // Supported modification.
   localObject.parent = { mother: "mom", father: "dad" };
   // Modification not supported.
   localObject.parent.mother = "mom";

1. Access the distributed data object.

Obtain the distributed data object attributes, which are the latest data on the network.

console.info("name " + localObject["name"]); 

1. Unsubscribe from data changes. You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered.

// Unregister the specified data change callback.
   localObject.off("change", changeCallback);
   // Unregister all data change callbacks. 
   localObject.off("change"); 

1. Subscribe to status changes of this distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline.

   function statusCallback(sessionId, networkId, status) {
       this.response += "status changed " + sessionId + " " + status + " " + networkId;
   }
   
   localObject.on("status", this.statusCallback);

1. Save a distributed data object and delete it.

   // Save a distributed data object.
   localObject.save("local").then((result) => {
       console.info("save sessionId " + result.sessionId);
       console.info("save version " + result.version);
       console.info("save deviceId " + result.deviceId);
   }, (result) => {
       console.info("save local failed.");
   });
   // Revoke the data saving operation.
   localObject.revokeSave().then((result) => {
       console.info("revokeSave success.");
   }, (result) => {
       console.info("revokeSave failed.");
   });
   

2. Unsubscribe from the status changes of the distributed data object.

   You can specify the callback to unregister. If you do not specify the callback, all status change callbacks of this distributed data object will be unregistered.

   // Unregister the specified status change callback.
   localObject.off("status", this.statusCallback);
   // Unregister all status change callbacks.
   localObject.off("status");
   

3. Remove the distributed data object from the synchronization network. The data changes on the local object will not be synchronized to the removed distributed data object.

   localObject.setSessionId("");
   

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Data Management

harmony 鸿蒙DataShare Development

harmony 鸿蒙DataShare Overview

harmony 鸿蒙Distributed Data Object Overview

harmony 鸿蒙Distributed Data Service Development

harmony 鸿蒙Distributed Data Service Overview

harmony 鸿蒙Preferences Development

harmony 鸿蒙Preferences Overview

harmony 鸿蒙RDB Development

harmony 鸿蒙RDB Overview