Lightweight Data Store Development

When to Use

The lightweight data store is ideal for storing lightweight and frequently used data, but not for storing a large amount of data or data with frequent changes. The application data is persistently stored on a device in the form of files. Note that the instance accessed by an application contains all data of the file. The data is always loaded to the memory of the device until the application removes it from the memory. The application can perform data operations using the Preferences APIs.

Available APIs

The lightweight data store provides applications with data processing capability and allows applications to perform lightweight data storage and query. Data is stored in key-value pairs. Keys are of the string type, and values can be of the string, Boolean, integer, long integer, float, double, or string array type.

Creating a Preferences Instance

Create a Preferences instance for data operations. A Preferences instance is created after data is read from a specified file and loaded to the instance.

Table 1 API for creating a Preferences instance

Writing Data

Call the put() method to add or modify data in a Preferences instance.

Table 2 APIs for writing data

Reading Data

Call the get() method to read data from a Preferences instance.

Table 3 APIs for reading data

Storing Data Persistently

Call the flush() or flushSync method to write the cached data back to its text file for persistent storage.

Table 4 APIs for data persistence

Observing Data Changes

Specify PreferencesObserver as the callback to subscribe to data changes. When the value of the subscribed key is changed and the flush() method is executed, PreferencesObserver will be invoked.

Table 5 APIs for subscribing to data changes

Deleting Data

Use the following APIs to delete a Preferences instance or data file.

Table 6 APIs for deleting data

How to Develop

1. Import the Preferences module and related header files to the development environment.

   Header file path: //distributeddatamgr_appdatamgr/interfaces/innerkits/native_preferences/include
   

2. Create a Preferences instance.

   Read the specified file and load its data to the Preferences instance for data operations.

   int errCode = E_OK;
   Preferences pref = PreferencesHelper::GetPreferences(PREF_TEST_PATH + "test.xml", errCode); // PREF_TEST_PATH must be the application sandbox path.
   EXPECT_EQ(errCode, E_OK);
   

3. Write data.

   Use the put() method of the Preferences class to write data to the cached Preferences instance.

   pref->PutString("test", "remove");
   

4. Read data.

   Use the get() method of the Preferences class to read data.

   std::string ret = pref->GetString("test", "defaultValue");
   EXPECT_EQ(ret, "remove");
   

5. Store data persistently.

   Use the flush() or flushSync() method to flush data in the Preferences instance to its file.

   int err = pref->FlushSync();
   EXPECT_EQ(ret, E_OK);
   

6. Subscribe to data changes.

   Specify PreferencesObserver as the callback to subscribe to data changes for an application. When the value of the subscribed key is changed and the flush() or flushSync() method is executed, PreferencesObserver will be invoked. Unregister the PreferencesObserver when it is no longer required.

   Customize a class to implement the PreferencesObserver:

   class PreferencesObserverCounter : public PreferencesObserver {
   public:
   virtual ~PreferencesObserverCounter();
   void OnChange(Preferences &preferences, const std::string &key) override;
   
       std::atomic_int notifyTimes;
       static const std::vector<std::string> 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<std::string> 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 };
   

   Subscribe to data changes and invoke the callback:

   std::shared_ptr<PreferencesObserver> counter =
       std::make_shared<PreferencesObserverCounter>();
   pref->RegisterObserver(counter); // Register a callback to return data changes.
   
   pref->PutString(PreferencesTest::KEY_TEST_STRING_ELEMENT, "test");
   pref->Flush(); // Trigger the onChanged callback of the counter.
   EXPECT_EQ(static_cast<PreferencesObserverCounter *>(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<PreferencesObserverCounter *>(counter.get())->notifyTimes, 2);
   
   pref->UnRegisterObserver(counter); // Unregister the callback for data changes.
   

7. Delete the specified file.

   Delete the Preferences singleton of the specified file from the memory, and delete the specified file, its backup file, and damaged files. After the specified files are deleted, the application cannot use that instance to perform any data operation. Otherwise, data inconsistency will occur. The deleted data and files cannot be restored.

   pref = nullptr;
   int ret = PreferencesHelper::DeletePreferences("/data/test/test");
   EXPECT_EQ(ret, E_OK);