diff --git a/zh-cn/device-dev/subsystems/Readme-CN.md b/zh-cn/device-dev/subsystems/Readme-CN.md index 865ade93f480923591801ec3edea7d614c2f9a44..1978419bb79233ff32b602348e4ef6daec72a099 100755 --- a/zh-cn/device-dev/subsystems/Readme-CN.md +++ b/zh-cn/device-dev/subsystems/Readme-CN.md @@ -40,10 +40,13 @@ - [唤醒词识别SDK的开发示例](subsys-aiframework-demo-sdk.md) - [唤醒词识别插件的开发示例](subsys-aiframework-demo-plugin.md) - [唤醒词识别配置文件的开发示例](subsys-aiframework-demo-conf.md) -- [数据管理](subsys-database.md) - - [关系型数据库](subsys-database-relational.md) - - [关系型数据库概述](subsys-database-relational-overview.md) - - [关系型数据库开发指导](subsys-database-relational-guide.md) +- [数据管理](subsys-data.md) + - [关系型数据库](subsys-data-relational-database.md) + - [关系型数据库概述](subsys-data-relational-database-overview.md) + - [关系型数据库开发指导](subsys-data-relational-database-guide.md) + - [轻量级数据存储](subsys-data-storage.md) + - [轻量级数据存储概述](subsys-data-storage-overview.md) + - [轻量级数据存储开发指导](subsys-data-storage-guide.md) - [Sensor服务](subsys-sensor.md) - [Sensor服务子系概述](subsys-sensor-overview.md) - [Sensor服务子系使用指导](subsys-sensor-guide.md) diff --git a/zh-cn/device-dev/subsystems/figure/zh-cn_image_0000001192123772.png b/zh-cn/device-dev/subsystems/figure/zh-cn_image_0000001192123772.png new file mode 100755 index 0000000000000000000000000000000000000000..6b0ac3897c71d9e3ad8fd0194bbd95d53cd04445 Binary files /dev/null and b/zh-cn/device-dev/subsystems/figure/zh-cn_image_0000001192123772.png differ diff --git a/zh-cn/device-dev/subsystems/subsys-data-relational-database.md b/zh-cn/device-dev/subsystems/subsys-data-relational-database.md old mode 100644 new mode 100755 index 85fe45cec40241feb6e2c5272b8247549ebb0170..cbe417ae578add8f7994d44d2557e13a80f83f5e --- a/zh-cn/device-dev/subsystems/subsys-data-relational-database.md +++ b/zh-cn/device-dev/subsystems/subsys-data-relational-database.md @@ -1,7 +1,5 @@ # 关系型数据库 -- **[关系型数据库概述](subsys-database-relational-overview.md)** - -- **[关系型数据库开发指导](subsys-database-relational-guide.md)** - +- **[关系型数据库概述](subsys-data-relational-database-overview.md)** +- **[关系型数据库开发指导](subsys-data-relational-database-guide.md)** diff --git a/zh-cn/device-dev/subsystems/subsys-data-storage-guide.md b/zh-cn/device-dev/subsystems/subsys-data-storage-guide.md new file mode 100755 index 0000000000000000000000000000000000000000..8d3f4e2725e8986d33f9e0c2b7a74748d47b24db --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-data-storage-guide.md @@ -0,0 +1,195 @@ +# 轻量级数据存储开发指导 + +## 场景介绍 + +轻量级数据存储功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用可以通过Preferences的API进行数据操作。 + +## 接口说明 + +轻量级存储为应用提供key-value键值型的文件数据处理能力，支持应用对数据进行轻量级存储及查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括字符串型、布尔型、整数型、长整型、浮点型、双精度类型和字符串数组。 + +**创建存储实例** + +读取指定文件，将数据加载到Preferences实例，即可创建一个存储实例，用于数据操作。 + +**表 1** 轻量级数据存储实例创建接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| PreferencesHelper | static std::shared_ptr GetPreferences(const std::string &path, int &errCode); | path：应用程序内部数据存储路径。
errCode：错误码。
返回值：轻量级存储实例。 | + +**存入数据** + +通过Put系列方法，可以增加或修改Preferences实例中的数据。 + +**表 2** 轻量级偏好数据库存入接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| Preferences | int PutInt(const std::string &key, int value); | key：将要存储的key名称，不能为空。
value：将要存储的value。
返回值：错误码。 | +| Preferences | int PutString(const std::string &key, const std::string &value); | key：将要存储的key名称，不能为空。
value：将要存储的value。
返回值：错误码。 | +| Preferences | int PutBool(const std::string &key, bool value); | key：将要存储的key名称，不能为空。
value：将要存储的value。
返回值：错误码。 | +| Preferences | int PutLong(const std::string &key, int64_t value); | key：将要存储的key名称，不能为空。
value：将要存储的value。
返回值：错误码。 | +| Preferences | int PutFloat(const std::string &key, float value); | key：将要存储的key名称，不能为空。
value：将要存储的value。
返回值：错误码。 | +| Preferences | int PutDouble(const std::string &key, double value); | key：将要存储的key名称，不能为空。
value：将要存储的value。
返回值：错误码。 | +| Preferences | int PutStringSet(const std::string &key, const std::set\ &value); | key：将要存储的key名称，不能为空。
value：将要存储的。
返回值：错误码。 | + +**读取数据** + +通过调用Get系列方法，可以读取Preferences中的数据。 + +**表 3** 轻量级数据读取接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| Preferences | bool GetBool(const std::string &key, bool defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | +| Preferences | std::string GetString(const std::string &key, const std::string &defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | +| Preferences | bool GetBool(const std::string &key, bool defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | +| Preferences | float GetFloat(const std::string &key, float defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | +| Preferences | double GetDouble(const std::string &key, double defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | +| Preferences | int64_t GetLong(const std::string &key, int64_t defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | +| Preferences | std::set\ GetStringSet(const std::string &key, std::set\ &defValue); | key：要获取的存储key名称，不能为空。
defValue：若获取失败或value不存在返回此默认值。
返回值：value。 | + +**数据持久化** + +通过执行flush或者flushSync方法，应用可以将缓存的数据再次写回文本文件中进行持久化存储。 + +**表 5** 轻量级数据数据持久化接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| Preferences | void Flush(); | 将Preferences实例通过异步线程回写入文件中。 | +| Preferences | int FlushSync(); | 将Preferences实例通过同步线程回写入文件中，并返回错误码。 | + +**订阅数据变化** + +订阅数据变化需要指定PreferencesObserver作为回调方法。订阅的key的值发生变更后，当执行flush方法时，PreferencesObserver被回调。 + +**表 5** 轻量级数据变化订阅接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| Preferences | void RegisterObserver(std::shared_ptr preferencesObserver); | preferencesObserver：需要订阅的回调对象实例。 | +| Preferences | void UnRegisterObserver(std::shared_ptr preferencesObserver); | preferencesObserver：需要注销订阅的回调对象实例。 | + +**删除数据文件** + +通过调用以下两种接口，可以删除数据实例或对应的文件。 + +**表 6** 轻量级数据存储删除接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| PreferencesHelper | int DeletePreferences(const std::string &path); | 将Preferences实例从内存中移除，同时删除其在设备上的持久化文件。path：应用程序内部数据存储路径。
返回值：错误码。 | +| PreferencesHelper | int RemovePreferencesFromCache(const std::string &path); | 仅将Preferences实例从内存中移除。path：应用程序内部数据存储路径。
返回值：错误码。 | + +## 开发步骤 + +1. 准备工作，引入preferences以及相关的头文件到开发环境。 + + ``` C++ + 头文件路径：//distributeddatamgr_appdatamgr/interfaces/innerkits/native_preferences/include + ``` + +2. 获取Preferences实例。 + + 读取指定文件，将数据加载到Preferences实例，用于数据操作。 + + ``` C++ + int errCode = E_OK; + Preferences pref = PreferencesHelper::GetPreferences(PREF_TEST_PATH + "test.xml", errCode); // PREF_TEST_PATH须为应用沙箱路径。 + EXPECT_EQ(errCode, E_OK); + ``` + + +3. 存入数据。 + + 使用Preferences put方法保存数据到缓存的实例中。 + + ```C++ + pref->PutString("test", "remove"); + ``` + +4. 读取数据。 + + 使用Preferences get方法读取数据。 + + ``` C++ + std::string ret = pref->GetString("test", "defaultValue"); + EXPECT_EQ(ret, "remove"); + ``` + + +5. 数据持久化。 + + 应用存入数据到Preferences实例后，可以通过flush或者flushSync方法将Preferences实例回写到文件中。 + + ```C++ + int err = pref->FlushSync(); + EXPECT_EQ(ret, E_OK); + ``` + + +6. 订阅数据变化。 + + 应用订阅数据变化需要指定PreferencesObserver作为回调方法。订阅的key的值发生变更后，当执行flush或者flushSync方法时，PreferencesObserver被触发回调。不再需要PreferencesObserver时请注销。 + + 自定义类，实现PreferencesObserver接口： + ``` C++ + class PreferencesObserverCounter : public PreferencesObserver { + public: + virtual ~PreferencesObserverCounter(); + void OnChange(Preferences &preferences, const std::string &key) override; + + std::atomic_int notifyTimes; + static const std::vector NOTIFY_KEYS_VECTOR; + }; + + PreferencesObserverCounter::~PreferencesObserverCounter() {} + + void PreferencesObserverCounter::OnChange(Preferences &preferences, const std::string &key) + { + for (auto it = NOTIFY_KEYS_VECTOR.cbegin(); it != NOTIFY_KEYS_VECTOR.cend(); it++) { + if (key.compare(*it)) { + notifyTimes++; + break; + } + } + } + + const std::vector PreferencesObserverCounter::NOTIFY_KEYS_VECTOR = { PreferencesTest::KEY_TEST_INT_ELEMENT, + PreferencesTest::KEY_TEST_LONG_ELEMENT, PreferencesTest::KEY_TEST_FLOAT_ELEMENT, + PreferencesTest::KEY_TEST_BOOL_ELEMENT, PreferencesTest::KEY_TEST_STRING_ELEMENT }; + ``` + + 订阅数据变化，并触发执行回调方法： + ``` C++ + std::shared_ptr counter = + std::shared_ptr(new PreferencesObserverCounter()); + pref->RegisterObserver(counter); // 注册数据变化的回调。 + + pref->PutString(PreferencesTest::KEY_TEST_STRING_ELEMENT, "test"); + pref->Flush(); // 触发执行counter的onChanged回调方法。 + EXPECT_EQ(static_cast(counter.get())->notifyTimes, 1); + + /* same value */ + pref->PutInt(PreferencesTest::KEY_TEST_INT_ELEMENT, 2); + pref->PutString(PreferencesTest::KEY_TEST_STRING_ELEMENT, "test"); + pref->Flush(); + EXPECT_EQ(static_cast(counter.get())->notifyTimes, 2); + + pref->UnRegisterObserver(counter); // 注销注册数据变化的回调。 + ``` + + +7. 删除指定文件。 + + 从使用PreferencesHelper内存中移除指定文件对应的Preferences单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。 + + ``` C++ + pref = nullptr; + int ret = PreferencesHelper::DeletePreferences("/data/test/test"); + EXPECT_EQ(ret, E_OK); + ``` + + diff --git a/zh-cn/device-dev/subsystems/subsys-data-storage-overview.md b/zh-cn/device-dev/subsystems/subsys-data-storage-overview.md new file mode 100755 index 0000000000000000000000000000000000000000..a4830a9c807017d7f106c9fcb61e546e52417bd1 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-data-storage-overview.md @@ -0,0 +1,31 @@ +# 轻量级数据存储概述 + +轻量级数据存储适用于对Key-Value结构的数据进行存取和持久化操作。应用获取某个轻量级存储对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用减少对持久化文件的读写频率。 + +## 基本概念 + +- **Key-Value数据结构** + + 一种键值结构数据类型。Key是不重复的关键字，Value是数据值。 + +- **非关系型数据库** + + 区别于关系数据库，不保证遵循ACID（Atomic、Consistency、Isolation及Durability）特性，不采用关系模型来组织数据，数据之间无关系。 + + +## 运作机制 + +1. 应用通过指定Preferences文件将其中的数据加载到Preferences实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个Preferences实例，直到应用主动从内存中移除该实例或者删除该Preferences文件。 +2. 应用获取到Preferences文件对应的实例后，可以从Preferences实例中读取数据，或者将数据存入Preferences实例中。通过调用flush或者flushSync方法可以将Preferences实例中的数据回写到文件里。 + +**图 1** 轻量级数据存储运作机制 + + +![](figure/zh-cn_image_0000001192123772.png) + +## 约束与限制 + +- 因Preferences实例会加载到内存中，建议存储的数据不超过一万条，并及时清理不再使用的实例，以便减少非内存开销。 +- 数据中的key为string类型，要求非空且字符长度不超过80个。 +- 当数据中的value为string类型时，允许为空，字符长度不超过8192个。 + diff --git a/zh-cn/device-dev/subsystems/subsys-data-storage.md b/zh-cn/device-dev/subsystems/subsys-data-storage.md new file mode 100755 index 0000000000000000000000000000000000000000..62031452c5b74f2635f97cc3a9d92eeb8717764b --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-data-storage.md @@ -0,0 +1,5 @@ +# 轻量级数据存储 + +- **[轻量级数据存储概述](subsys-data-storage-overview.md)** + +- **[轻量级数据存储开发指导](subsys-data-storage-guide.md)** diff --git a/zh-cn/device-dev/subsystems/subsys-data.md b/zh-cn/device-dev/subsystems/subsys-data.md old mode 100644 new mode 100755 index 149691099546d0f4e6b16dfe789a68fce6c7b1ca..5e1f5fb2764ee8c82db4f71b1215f352d4aa6067 --- a/zh-cn/device-dev/subsystems/subsys-data.md +++ b/zh-cn/device-dev/subsystems/subsys-data.md @@ -1,5 +1,6 @@ # 数据管理 -- **[关系型数据库](subsys-database-relational.md)** +- **[关系型数据库](subsys-data-relational-database.md)** +- **[轻量级数据存储](subsys-data-storage.md)** diff --git a/zh-cn/device-dev/subsystems/subsys.md b/zh-cn/device-dev/subsystems/subsys.md old mode 100644 new mode 100755 index aa174c8457746cf5e552bff26c572d36ab402f3b..5c874980f028f17e2375a31fd3bc4f8faccd2b16 --- a/zh-cn/device-dev/subsystems/subsys.md +++ b/zh-cn/device-dev/subsystems/subsys.md @@ -4,6 +4,7 @@ - **[分布式远程启动](subsys-remote-start.md)** - **[图形图像](subsys-graphics.md)** - **[媒体](subsys-multimedia.md)** +- **[数据管理](subsys-data.md)** - **[公共基础](subsys-utils.md)** - **[AI框架](subsys-aiframework.md)** - **[Sensor服务](subsys-sensor.md)**