database-distributedobject-guidelines.md 8.5 KB
Newer Older
A
annie_wangli 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
# Distributed Data Object Development

## When to Use

The distributed data objects allow data across devices to be processed like local variables by shielding complex data interaction between devices. For the devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other devices. The devices can listen for the data changes and online and offline states of other devices. The distributed data objects support basic data types, such as number, string, and Boolean, as well as complex data types, such as array and nested basic types.


## Available APIs

### 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
| Package| API| Description| 
| -------- | -------- | -------- |
A
annie_wangli 已提交
18
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.<br>- &nbsp;**source**: attributes of the **distributedObject** set.<br>- &nbsp;**DistributedObject**: returns the distributed object created.| 
A
annie_wangli 已提交
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45

### 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
| Package| API| Description|
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| genSessionId(): string | Generates a session ID, which can be used as the session ID of a distributed data object.|

### Setting a SessionID for Distributed Data Objects

Call setSessionId() to set the 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
| Class| API| Description|
| -------- | -------- | -------- |
| DistributedDataObject | setSessionId(sessionId?: string): boolean | Sets a session ID for distributed data objects.|

### 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
| Class| API| Description| 
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void | Subscribes to data changes.| 
A
annie_wangli 已提交
46
| DistributedDataObject| off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void | Unsubscribes from data changes. Callback used to return changes of the distributed object. If this parameter is not specified, all callbacks related to data changes will be unregistered.|
A
annie_wangli 已提交
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84

### 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
| Class| API| Description|
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }>): void | Subscribes to the status changes of a distributed data object.|
| DistributedDataObject| off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }>): void | Unsubscribes from status changes of a distributed data object.|



## How to Develop

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

1. Import the @ohos.data.distributedDataObject module to the development environment.
   ```js
   import distributedObject from '@ohos.data.distributedDataObject'
   ```

2. Obtain a distributed data object instance.

   The sample code is as follows:
   ```js
   var local_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true, 
                  parent:undefined, list:undefined});
   ```


3. Add the synchronization network. The data objects in the synchronization network include the local and remote objects.
   
   The sample code is as follows:

   ```js
   // Local object
   var local_object = distributedObject.createDistributedObject({name:"jack", age:18, isVis:true, 
A
annie_wangli 已提交
85 86
       parent:{mother:"jack mom",father:"jack Dad"},list:[{mother:"jack mom"}, {father:"jack Dad"}]});
   local_object.setSessionId(sessionId);
A
annie_wangli 已提交
87 88 89 90
   
   // Remote object
   var remote_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true, 
                  parent:undefined, list:undefined});
A
annie_wangli 已提交
91
   remote_object.setSessionId(sessionId);
A
annie_wangli 已提交
92 93 94 95 96 97 98 99
   // After obtaining that the device status goes online, the remote object synchronizes data. That is, name changes to jack and age to 18.
   ```
   
4. Observe the data changes of the distributed data object. Subscribe to data changes of the remote end. When the data is the peer end changes, a callback will be called to return the data changes.

   The sample code is as follows:
   
   ```js
A
annie_wangli 已提交
100
   function changeCallback(sessionId, changeData) {
A
annie_wangli 已提交
101 102 103 104 105 106 107 108 109 110 111
        console.info("change" + sessionId);
   
        if (changeData != null && changeData != undefined) {
            changeData.forEach(element => {
                console.info("changed !" + element + " " + local_object[element]);
        });
        }
    } 
    local_object.on("change", this.changeCallback);
   ```
   
112
5. Modify object attributes. The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types).
A
annie_wangli 已提交
113 114 115 116 117 118 119 120 121 122
   
   The sample code is as follows:
   ```js
   local_object.name = "jack";
   local_object.age = 19;
   local_object.isVis = false;
   local_object.parent = {mother:"jack mom",father:"jack Dad"};
   local_object.list = [{mother:"jack mom"}, {father:"jack Dad"}];
   ```

123
   > ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**<br/>
A
annie_wangli 已提交
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
   > For the distributed data object of the complex type, only the root attribute can be modified. The subordinate attributes cannot be modified. Example:
   ```js
   // Supported modification.
   local_object.parent = {mother:"mom", father:"dad"};
   // Modification not supported.
   local_object.parent.mother = "mom";
   ```

6. Access the distributed data object. Obtain the distributed data object attribute, which is the latest data on the network.
   
   The sample code is as follows:
   ```js
   console.info("name " + local_object["name"]); 
   ```
7. Unsubscribe from data changes. You can specify the callback to unsubscribe from. If you do not specify the callback, all data change callbacks of the distributed data object will be unsubscribed from.

   The sample code is as follows:
   ```js
   // Unsubscribe from changeCallback.
   local_object.off("change", changeCallback);
   // Unsubscribe from all data change callbacks. 
   local_object.off("change"); 
   ```
8. Subscribe to the status (online/offline) changes of the distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline.
   The sample code is as follows:
   ```js
A
annie_wangli 已提交
150
    function statusCallback(sessionId, networkid, status) {
A
annie_wangli 已提交
151 152 153 154 155 156 157 158 159 160 161 162 163 164
      this.response += "status changed " + sessionId + " " + status + " " + networkId;
    }
   
    local_object.on("status", this.changeCallback);
   ```
9. Unsubscribe from the status changes of the distributed data object. You can specify the callback to unsubscribe from. If you do not specify the callback, all status change callbacks will be unsubscribe from. 
   
    The sample code is as follows:
   ```js
   // Unsubscribe from changeCallback.
   local_object.off("status", changeCallback);
   // unsubscribe from all status change callbacks.
   local_object.off("status");
   ```
A
annie_wangli 已提交
165
10. Remove a distributed data object from the synchronization network. After the distributed data object is removed from the network, the data changes on the local end will not be synchronized to the remote end.
A
annie_wangli 已提交
166 167 168 169 170 171 172 173 174

     The sample code is as follows:
       ```js
       local_object.setSessionId("");
       ```