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|
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.|
### 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<string>}>): void | Subscribes to data changes.|
| DistributedDataObject| off(type: 'change', callback?: Callback<{sessionId:string,fields:Array<string>}>): void | Unsubscribes from data changes.|
### 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.
// 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.
5. Modifies object attributes. The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types).
> 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.
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");
```
10. Remote 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.
The distributed data object management framework is an object-oriented in-memory data management framework. It provides application developers with basic data object management capabilities, such as creating, querying, deleting, modifying, and subscribing to in-memory objects. This management framework also provides distributed capabilities to implement data object collaboration for the same application between multiple devices that form a Super Device.
## Key Concepts
-**Distributed in-memory database**
The distributed in-memory database caches data in the memory, so that applications can quickly access data. This database, however, does not store data persistently. If the database is closed, the data is not retained.
-**Distributed data object**
A distributed data object is an encapsulation of the JS object type. Each distributed data object instance creates a data table in the in-memory database. The in-memory databases created for different applications are isolated from each other. Reading or assigning values to distributed data objects is automatically mapped to the **put** or **get** operation of the corresponding database.
The distributed data object can be in the following states in its lifecycle:
-** Uninitialized**: The distributed data object is not instantiated or has been destroyed.
-** Local**: The data table is created, but the data cannot be synchronized.
-** Distributed**: The data table is created, there are at least two online with the same session ID, and data can be synchronized across devices. If the device is offline or the session ID is empty, the distributed data object changes to the local state.
## Working Principles
The distributed data objects are encapsulated into JS objects in distributed in-memory databases, which allows the distributed data objects to be operated in the same way as local variables. The system automatically implements cross-device data synchronization.
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Creates a **distributedObject** instance. You can specify the attribute of the instance in **source**. This method returns the **distributedObject** instance created.
** System Capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
-**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| object | source | Yes| Attribute of the **distributedObject** instance to create.|
Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network. To remove a device from the distributed network, set this parameter to "" or leave it unspecified. If **true** is returned, the session ID is set successfully.
** System Capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
-**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| sessionId | string | No| ID of a distributed object on a trusted network.|
Subscribes to the data changes of this distributed object.
** System Capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
-**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to subscribe to. The value is **change**, which indicates data change events.|
| callback | Callback<{sessionId:string,fields:Array<string>}> | Yes| Callback used to return the data changes of the distributed object. In the callback, **sessionId** indicates the session ID of the distributed object, and **fields** indicates the attributes of the object.|
Unsubscribes from the data changes of this distributed object.
** System Capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
-**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to unsubscribe from. The value is **change**, which indicates data change events.|
| callback | Callback<{sessionId:string,fields:Array<string>}> | No| Callback used to return changes of the distributed object. If this parameter is not specified, all callbacks related to data changes will be unregistered.|
Subscribes to the status changes (online or offline) of this distributed object.
** System Capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
-**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to subscribe to. The value is "status", which indicates the status (online or offline) change events.|
| callback | Callback<{sessionId:string,networkId:string,status:'online'\|'offline'}> | Yes| Callback used to return the status changes of the distributed object. In the callback, **sessionId** indicates the session ID of the distributed object, and **status** indicates the online or offline status of the distributed object.|
Unsubscribes from the status (online or offline) changes of the distributed object.
** System Capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
-**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to subscribe to. The value is "status", which indicates the status (online or offline) change events.|
| callback | Callback<{sessionId:string,networkId:string,status:'online'\|'offline'}> | No| Callback used to return the status changes. If this parameter is not specified, all the status change callbacks will be unregistered.|
