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 100644 index 0000000000000000000000000000000000000000..af94bae6f120f4ee8def8d9b2d255f34c7a36c7d 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 index 85fe45cec40241feb6e2c5272b8247549ebb0170..cbe417ae578add8f7994d44d2557e13a80f83f5e 100644 --- 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 100644 index 0000000000000000000000000000000000000000..bd4238fb1af4ba2ceb60afaa69547e4bbd1acdba --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-data-storage-guide.md @@ -0,0 +1,194 @@ +# 轻量级数据存储开发指导 + +## 场景介绍 + +轻量级数据存储主要用于保存应用的一些常用配置信息，并不适合存储大量数据和频繁改变数据的场景。用户的数据保存在文件中，可以持久化的存储在设备上。需要注意的是用户访问的实例包含文件所有数据，并一直加载在设备的内存中，并通过Preferences的API进行数据操作。 + +## 接口说明 + +轻量级存储为应用提供key-value键值型的文件数据处理能力，支持应用对数据进行轻量级存储及查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型、长整型、浮点型、双精度类型和字符数组。 + +**创建存储实例** + +读取指定文件，将数据加载到Preferences实例，用于数据操作。 + +**表 1** 轻量级数据存储实例创建接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| PreferencesHelper | static std::shared_ptr GetPreferences(const std::string &path, int &errCode); | path：应用程序内部数据存储路径。
errCode：错误码。
返回值：轻量级存储实例。 | + +**查询数据** + +通过调用Get系列方法，可以查询Preferences中的数据。 + +**表 2** 轻量级数据查询接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| Preferences | bool GetBool(const std::string &key, bool defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | +| Preferences | std::string GetString(const std::string &key, const std::string &defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | +| Preferences | bool GetBool(const std::string &key, bool defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | +| Preferences | float GetFloat(const std::string &key, float defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | +| Preferences | double GetDouble(const std::string &key, double defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | +| Preferences | int64_t GetLong(const std::string &key, int64_t defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | +| Preferences | std::set\ GetStringSet(const std::string &key, std::set\ &defValue); | key：要获取的存储key名称，它不能为空。
defValue：默认返回值。
返回值：value。 | + +**插入数据** + +通过Put系列方法，可以增加或修改Preferences实例中的数据，执行flush或者flushSync方法可以将Preferences实例持久化。 + +**表 3** 轻量级偏好数据库插入接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| 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：要存储的。
返回值：错误码。 | + +**订阅数据变化** + +订阅数据变化需要指定PreferencesObserver作为回调方法。订阅的key的值发生变更后，当执行flush方法时，PreferencesObserver被回调。 + +**表 4** 轻量级数据变化订阅接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| Preferences | void RegisterObserver(std::shared_ptr preferencesObserver); | preferencesObserver：需要订阅的回调对象实例。 | +| Preferences | void UnRegisterObserver(std::shared_ptr preferencesObserver); | preferencesObserver：需要注销订阅的回调对象实例。 | + +**删除数据文件** + +通过调用以下两种接口，可以删除数据实例或对应的文件。 + +**表 5** 轻量级数据存储删除接口 + +| 类名 | 方法名 | 描述 | +| --- | ----- | ----| +| PreferencesHelper | int DeletePreferences(const std::string &path); | path：应用程序内部数据存储路径。
返回值：错误码。 | +| PreferencesHelper | int RemovePreferencesFromCache(const std::string &path); | path：应用程序内部数据存储路径。
返回值：错误码。 | + +## 开发步骤 + +1. 准备工作，引入preferences以及相关的头文件到开发环境。 + +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实例，使用Preferences get方法读取数据。 + + ``` C++ + pref->PutString(PreferencesTest::LONG_KEY + 'x', "test"); + pref->PutString("", "test"); + pref->Flush(); + + std::string ret = pref->GetString(PreferencesTest::LONG_KEY + 'x', "defaultValue"); + EXPECT_EQ(ret, "defaultValue"); + ret = pref->GetString("", "defaultValue"); + EXPECT_EQ(ret, "defaultValue"); + + pref->PutString(PreferencesTest::LONG_KEY, "test"); + pref->PutString(PreferencesTest::KEY_TEST_STRING_ELEMENT, "test"); + pref->Flush(); + + ret = pref->GetString(PreferencesTest::LONG_KEY, "defaultValue"); + EXPECT_EQ(ret, "test"); + ret = pref->GetString(PreferencesTest::KEY_TEST_STRING_ELEMENT, "defaultValue"); + EXPECT_EQ(ret, "test"); + ``` + + +4. 保存数据，并写入文件。 + + 首先获取指定文件对应的Preferences实例，使用Preferences put方法保存数据到缓存的实例中，通过flush或者flushSync方法将Preferences实例写入文件。 + + ```C++ + pref->PutString("test", "remove"); + pref->Flush(); + + std::string ret = pref->GetString("test", "defaultValue"); + EXPECT_EQ(ret, "remove"); + + pref->Delete("test"); + pref->Flush(); + ret = pref->GetString("test", "defaultValue"); + EXPECT_EQ(ret, "defaultValue"); + ``` + + +5. 订阅数据变化。 + + 应用订阅数据变化需要指定PreferencesObserver作为回调方法。订阅的key的值发生变更后，当执行flush或者flushSync方法时，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(); + 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); + ``` + + +6. 删除指定文件。 + + 从内存中移除指定文件对应的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 100644 index 0000000000000000000000000000000000000000..35acda7b8a1862254812ee4dacc377145acd5a6b --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-data-storage-overview.md @@ -0,0 +1,32 @@ +# 轻量级数据存储概述 + +轻量级数据存储适用于对Key-Value结构的数据进行存取和持久化操作。应用运行时全量数据将会被加载在内存中的，使得访问速度更快，存取效率更高。如果对数据持久化，数据最终会落盘到文本文件中，建议在开发过程中减少落盘频率，即减少对持久化文件的读写次数。 + +## 基本概念 + +- **Key-Value数据结构** + + 一种键值结构数据类型。Key是不重复的关键字，Value是数据值。 + +- **非关系型数据库** + + 区别于关系数据库，不保证遵循ACID（Atomic、Consistency、Isolation及Durability）特性，不采用关系模型来组织数据，数据之间无关系，扩展性好。 + + +## 运作机制 + +1. 本模块提供轻量级数据存储的操作类，应用通过这些操作类操作数据。 +2. 应用可以将指定Preferences文件的内容加载到Preferences实例，同一进程中每个文件仅有一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到应用主动从内存中移除该实例或者删除该Preferences文件。 +3. 获取到Preferences文件对应的实例后，应用可以从Preferences实例中读取数据，或者将数据写入Preferences实例中。通过调用flush或者flushSync方法可以将Preferences实例中的数据回写到文件里。 + +**图 1** 轻量级数据存储运作机制 + + +![](figure/zh-cn_image_0000001192123772.png) + +## 约束与限制 + +- 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 100644 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 index 149691099546d0f4e6b16dfe789a68fce6c7b1ca..5e1f5fb2764ee8c82db4f71b1215f352d4aa6067 100644 --- 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 index aa174c8457746cf5e552bff26c572d36ab402f3b..5c874980f028f17e2375a31fd3bc4f8faccd2b16 100644 --- 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)**