1# Distributed Data Object Development 2 3## When to Use 4 5The 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 status 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. 6 7 8## Available APIs 9For details about the APIs related to the distributed data object, see [Distributed Data Object](../reference/apis/js-apis-data-distributedobject.md). 10 11### Creating a Distributed Data Object Instance 12 13Call **createDistributedObject()** to create a distributed data object instance. You can specify the attributes of the instance in **source**. 14 15 16**Table 1** API for creating a distributed data object instance 17| Package| API| Description| 18| -------- | -------- | -------- | 19| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.<br>- **source**: attributes of the **distributedObject** set.<br>- **DistributedObject**: returns the distributed object created.| 20 21### Generating a Session ID 22 23Call **genSessionId()** to generate a session ID randomly. The generated session ID can be used to set the session ID of a distributed data object. 24 25**Table 2** API for generating a session ID randomly 26| Package| API| Description| 27| -------- | -------- | -------- | 28| ohos.data.distributedDataObject| genSessionId(): string | Generates a session ID, which can be used as the session ID of a distributed data object.| 29 30### Setting a SessionID for Distributed Data Objects 31 32Call **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. 33 34**Table 3** API for setting a session ID 35| Class| API| Description| 36| -------- | -------- | -------- | 37| DistributedDataObject | setSessionId(sessionId?: string): boolean | Sets a session ID for distributed data objects.<br> **sessionId**: session ID of a distributed object in a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.| 38 39### Observing Data Changes 40 41Call **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. 42 43**Table 4** APIs for observing data changes of a distributed data object 44| Class| API| Description| 45| -------- | -------- | -------- | 46| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void | Subscribes to data changes.| 47| DistributedDataObject| off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void | Unsubscribes from data changes. <br>**Callback**: specifies callback used to return changes of the distributed data object. If this parameter is not specified, all callbacks related to data changes will be unregistered.| 48 49### Observing Online or Offline Status 50 51Call **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. 52 53**Table 5** APIs for observing status changes of a distributed data object 54| Class| API| Description| 55| -------- | -------- | -------- | 56| DistributedDataObject| on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }>): void | Subscribes to the status changes of a distributed data object.| 57| DistributedDataObject| off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }>): void | Unsubscribes from status changes of a distributed data object.| 58 59 60 61## How to Develop 62 63The following example shows how to implement a distributed data object synchronization. 64 651. Import the @ohos.data.distributedDataObject module to the development environment. 66 ```js 67 import distributedObject from '@ohos.data.distributedDataObject' 68 ``` 69 702. Obtain a distributed data object instance. 71 72 The sample code is as follows: 73 ```js 74 var local_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true, 75 parent:undefined, list:undefined}); 76 var sessionId = distributedObject.genSessionId(); 77 ``` 78 79 803. Add the synchronization network. The data objects in the synchronization network include the local and remote objects. 81 82 The sample code is as follows: 83 84 ```js 85 // Local object 86 var local_object = distributedObject.createDistributedObject({name:"jack", age:18, isVis:true, 87 parent:{mother:"jack mom",father:"jack Dad"},list:[{mother:"jack mom"}, {father:"jack Dad"}]}); 88 local_object.setSessionId(sessionId); 89 90 // Remote object 91 var remote_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true, 92 parent:undefined, list:undefined}); 93 remote_object.setSessionId(sessionId); 94 // After learning that the device goes online, the remote object synchronizes data. That is, name changes to jack and age to 18. 95 ``` 96 974. Observe the data changes of the distributed data object. You can subscribe to data changes of the peer object. When the data in the peer object changes, a callback will be called to return the data changes. 98 99 The sample code is as follows: 100 101 ```js 102 function changeCallback(sessionId, changeData) { 103 console.info("change" + sessionId); 104 105 if (changeData != null && changeData != undefined) { 106 changeData.forEach(element => { 107 console.info("changed !" + element + " " + local_object[element]); 108 }); 109 } 110 } 111 112 // To refresh the page in changeCallback, correctly bind (this) to the changeCallback. 113 local_object.on("change", this.changeCallback.bind(this)); 114 ``` 115 1165. 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). 117 118 The sample code is as follows: 119 ```js 120 local_object.name = "jack"; 121 local_object.age = 19; 122 local_object.isVis = false; 123 local_object.parent = {mother:"jack mom",father:"jack Dad"}; 124 local_object.list = [{mother:"jack mom"}, {father:"jack Dad"}]; 125 ``` 126 127 >  **NOTE**<br> 128 > For the distributed data object of the complex type, only the root attribute can be modified. The subordinate attributes cannot be modified. Example: 129 ```js 130 // Supported modification. 131 local_object.parent = {mother:"mom", father:"dad"}; 132 // Modification not supported. 133 local_object.parent.mother = "mom"; 134 ``` 135 1366. Access the distributed data object. Obtain the distributed data object attribute, which is the latest data on the network. 137 138 The sample code is as follows: 139 ```js 140 console.info("name " + local_object["name"]); 141 ``` 1427. 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. 143 144 The sample code is as follows: 145 ```js 146 // Unregister the specified data change callback. 147 local_object.off("change", changeCallback); 148 // Unregister all data change callbacks. 149 local_object.off("change"); 150 ``` 1518. 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. 152 The sample code is as follows: 153 ```js 154 function statusCallback(sessionId, networkId, status) { 155 this.response += "status changed " + sessionId + " " + status + " " + networkId; 156 } 157 158 local_object.on("status", this.statusCallback); 159 ``` 1609. Unsubscribe from the status changes of the distributed data object. You can specify the callback to unregister. If you do not specify the callback, this API unregisters all callbacks of this distributed data object. 161 162 The sample code is as follows: 163 ```js 164 // Unregister the specified status change callback. 165 local_object.off("status", statusCallback); 166 // Unregister all status change callbacks. 167 local_object.off("status"); 168 ``` 16910. Remove a distributed data object from the synchronization network. Data changes on the local object will not be synchronized to the removed distributed data object. 170 171 The sample code is as follows: 172 ```js 173 local_object.setSessionId(""); 174 ``` 175## Development Example 176 177The following example is provided for you to better understand the development of distributed data objects: 178 179- [Distributed Notepad](https://gitee.com/openharmony/distributeddatamgr_objectstore/tree/master/samples/distributedNotepad) 180 181 182When an event of the Notepad app occurs on a device, such as a note is added, the tile or content of a note is changed, or the event list is cleared, the change will be synchronized to other devices in the trusted network. 183 184
