1 /* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef KVSTORE_H 17 #define KVSTORE_H 18 19 #include <map> 20 #include "kvstore_observer.h" 21 #include "types.h" 22 23 namespace OHOS { 24 namespace DistributedKv { 25 class API_EXPORT KvStore { 26 public: 27 /** 28 * @brief Constructor. 29 */ 30 API_EXPORT KvStore() = default; 31 32 /** 33 * @brief Forbidden copy constructor. 34 */ 35 KvStore(const KvStore &) = delete; 36 37 /** 38 * @brief Forbidden copy constructor. 39 */ 40 KvStore &operator=(const KvStore &) = delete; 41 42 /** 43 * @brief Destructor. 44 */ ~KvStore()45 API_EXPORT virtual ~KvStore() {} 46 47 /** 48 * @brief Get kvstore name of this kvstore instance. 49 * @return The kvstore name. 50 */ 51 virtual StoreId GetStoreId() const = 0; 52 53 /** 54 * @brief Put one entry with key-value into kvstore. 55 * 56 * Mutation operations. 57 * Key level operations. 58 * Mutations are bundled together into atomic commits. If a transaction is in 59 * progress, the list of mutations bundled together is tied to the current 60 * transaction. If no transaction is in progress, mutations will be a unique transaction. 61 * 62 * @param key The key, key length should not be greater than 256, and can not be empty. 63 * @param value The value, value size should be less than IPC transport limit, and can not be empty. 64 * @return Return SUCCESS for success, others for failure. 65 */ 66 virtual Status Put(const Key &key, const Value &value) = 0; 67 68 /** 69 * @brief Put a list of entries to kvstore. 70 * 71 * all entries will be put in a transaction, 72 * if entries contains invalid entry, PutBatch will all fail. 73 * entries's size should be less than 128 and memory size must be less than IPC transport limit. 74 * 75 * @param entries The entries. 76 * @return Return SUCCESS for success, others for failure. 77 */ 78 virtual Status PutBatch(const std::vector<Entry> &entries) = 0; 79 80 /** 81 * @brief Delete one entry in the kvstore. 82 * @param key The key, key length should not be greater than 256, and can not be empty. 83 * @return Return SUCCESS for success, others for failure. 84 * delete non-exist key still return KEY NOT FOUND error. 85 */ 86 virtual Status Delete(const Key &key) = 0; 87 88 /** 89 * @brief Delete a list of entries in the kvstore. 90 * 91 * key length should not be greater than 256, and can not be empty. 92 * if keys contains invalid key, all delete will fail. 93 * keys memory size should not be greater than IPC transport limit, and can not be empty. 94 * 95 * @param keys The keys. 96 * @return Return SUCCESS for success, others for failure. 97 * delete key not exist still return success, 98 */ 99 virtual Status DeleteBatch(const std::vector<Key> &keys) = 0; 100 101 /** 102 * @brief Start transaction. 103 * 104 * all changes to this kvstore will be in a same transaction 105 * and will not change the store until #Commit() or #Rollback() is called. 106 * before this transaction is committed or rollbacked, 107 * all attemption to close this store will fail. 108 * 109 * @return Return SUCCESS for success, others for failure. 110 */ 111 virtual Status StartTransaction() = 0; 112 113 /** 114 * @brief Commit current transaction. 115 * 116 * all changes to this store will be done after calling this method. 117 * any calling of this method outside a transaction will fail. 118 * 119 * @return Return SUCCESS for success, others for failure. 120 */ 121 virtual Status Commit() = 0; 122 123 /** 124 * @brief Rollback current transaction. 125 * 126 * all changes to this store during this transaction will be rollback after calling this method. 127 * any calling of this method outside a transaction will fail. 128 * 129 * @return Return SUCCESS for success, others for failure. 130 */ 131 virtual Status Rollback() = 0; 132 133 /** 134 * @brief Subscribe kvstore to watch data change in the kvstore. 135 * 136 * OnChange in he observer will be called when data changed, with all the changed contents. 137 * client is responsible for free observer after and only after call UnSubscribeKvStore. 138 * otherwise, codes in sdk may use a freed memory and cause unexpected result. 139 * 140 * @param type Strategy for this subscribe, default right now. 141 * @param observer Callback client provided, client must implement KvStoreObserver and 142 * override OnChange function, when data changed in store, 143 * OnChange will called in Observer. 144 * @return Return SUCCESS for success, others for failure. 145 */ 146 virtual Status SubscribeKvStore(SubscribeType type, std::shared_ptr<KvStoreObserver> observer) = 0; 147 148 /** 149 * @brief Unsubscribe kvstore to un-watch data change in the kvstore. 150 * 151 * after this call, no message will be received even data change in the kvstore. 152 * client is responsible for free observer after and only after call UnSubscribeKvStore. 153 * otherwise, codes in sdk may use a freed memory and cause unexpected result. 154 * 155 * @param type Strategy for this subscribe, default right now. 156 * @param observer Callback client provided in #SubscribeKvStore(). 157 * @return Return SUCCESS for success, others for failure. 158 */ 159 virtual Status UnSubscribeKvStore(SubscribeType type, std::shared_ptr<KvStoreObserver> observer) = 0; 160 161 /** 162 * @brief Backup the store to a specified backup file. 163 * @param file Target file of backup. 164 * @param baseDir Root path of store manager. 165 * @return Return SUCCESS for success, others for failure. 166 */ 167 virtual Status Backup(const std::string &file, const std::string &baseDir) = 0; 168 169 /** 170 * @brief Restore the store from a specified backup file. 171 * @param file The file of backup data. 172 * @param baseDir Root path of store manager. 173 * @return Return SUCCESS for success, others for failure. 174 */ 175 virtual Status Restore(const std::string &file, const std::string &baseDir) = 0; 176 177 /** 178 * @brief Delete the backup files. 179 * @param files Files the list of backup file to be delete. 180 * @param baseDir Root path of store manager. 181 * @param status Result of delete backup 182 * @return Return SUCCESS for success, others for failure. 183 */ 184 virtual Status DeleteBackup(const std::vector<std::string> &files, const std::string &baseDir, 185 std::map<std::string, DistributedKv::Status> &status) = 0; 186 }; 187 } // namespace DistributedKv 188 } // namespace OHOS 189 #endif // KVSTORE_H 190