1 /*
2  * Copyright (c) 2024 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 NATIVE_RDB_TRANSACTION_H
17 #define NATIVE_RDB_TRANSACTION_H
18 
19 #include <tuple>
20 #include <utility>
21 #include <vector>
22 #include <functional>
23 
24 #include "abs_rdb_predicates.h"
25 #include "result_set.h"
26 #include "rdb_common.h"
27 #include "rdb_errno.h"
28 #include "rdb_types.h"
29 #include "rdb_visibility.h"
30 #include "values_bucket.h"
31 #include "values_buckets.h"
32 
33 namespace OHOS::NativeRdb {
34 class Connection;
35 class API_EXPORT Transaction {
36 public:
37     /**
38      * @brief Use Fields replace std::vector<std::string> columns.
39      */
40     using Fields = std::vector<std::string>;
41 
42     /**
43      * @brief Use Values replace std::vector<ValueObject> args.
44      */
45     using Values = std::vector<ValueObject>;
46 
47     /**
48      * @brief Use Row replace ValuesBucket.
49      */
50     using Row = ValuesBucket;
51 
52     /**
53      * @brief Use Rows replace std::vector<Row>.
54      */
55     using Rows = std::vector<Row>;
56 
57     /**
58      * @brief Use Rows replace std::vector<Row>.
59      */
60     using RefRows = ValuesBuckets;
61 
62     /**
63      * @brief Use Resolution replace ConflictResolution.
64      */
65     using Resolution = ConflictResolution;
66 
67     static constexpr Resolution NO_ACTION = ConflictResolution::ON_CONFLICT_NONE;
68 
69     enum TransactionType : int32_t {
70         DEFERRED,
71         IMMEDIATE,
72         EXCLUSIVE,
73         TRANS_BUTT,
74     };
75 
76     using Creator = std::function<std::pair<int32_t, std::shared_ptr<Transaction>>(
77         int32_t type, std::shared_ptr<Connection> connection, const std::string&)>;
78 
79     static std::pair<int32_t, std::shared_ptr<Transaction>> Create(
80         int32_t type, std::shared_ptr<Connection> connection, const std::string &name);
81     static int32_t RegisterCreator(Creator creator);
82 
83     virtual ~Transaction() = default;
84 
85     virtual int32_t Commit() = 0;
86     virtual int32_t Rollback() = 0;
87     virtual int32_t Close() = 0;
88 
89     /**
90      * @brief Inserts a row of data into the target table.
91      *
92      * @param table Indicates the target table.
93      * @param row Indicates the row of data {@link ValuesBucket} to be inserted into the table.
94      * @param resolution Indicates the {@link ConflictResolution} to insert data into the table.
95      */
96     virtual std::pair<int32_t, int64_t> Insert(const std::string &table, const Row &row,
97                                                Resolution resolution = NO_ACTION) = 0;
98 
99     /**
100      * @brief Inserts a batch of data into the target table.
101      *
102      * @param table Indicates the target table.
103      * @param rows Indicates the rows of data {@link ValuesBucket} to be inserted into the table.
104      */
105     virtual std::pair<int32_t, int64_t> BatchInsert(const std::string &table, const Rows &rows) = 0;
106 
107     /**
108      * @brief Inserts a batch of data into the target table.
109      *
110      * @param table Indicates the target table.
111      * @param values Indicates the rows of data {@link ValuesBuckets} to be inserted into the table.
112      */
113     virtual std::pair<int32_t, int64_t> BatchInsert(const std::string &table, const RefRows &rows) = 0;
114 
115     /**
116      * @brief Updates data in the database based on specified conditions.
117      *
118      * @param table Indicates the target table.
119      * @param row Indicates the row of data to be updated in the database.
120      * The key-value pairs are associated with column names of the database table.
121      * @param whereClause Indicates the where clause.
122      * @param args Indicates the where arguments.
123      */
124     virtual std::pair<int, int> Update(const std::string &table, const Row &row, const std::string &where = "",
125                                        const Values &args = {}, Resolution resolution = NO_ACTION) = 0;
126 
127     /**
128      * @brief Updates data in the database based on a a specified instance object of AbsRdbPredicates.
129      *
130      * @param values Indicates the row of data to be updated in the database.
131      * The key-value pairs are associated with column names of the database table.
132      * @param predicates Indicates the specified update condition by the instance object of {@link AbsRdbPredicates}.
133      */
134     virtual std::pair<int32_t, int32_t> Update(const Row &row, const AbsRdbPredicates &predicates,
135                                                Resolution resolution = NO_ACTION) = 0;
136 
137     /**
138      * @brief Deletes data from the database based on specified conditions.
139      *
140      * @param table Indicates the target table.
141      * @param whereClause Indicates the where clause.
142      * @param args Indicates the where arguments.
143      */
144     virtual std::pair<int32_t, int32_t> Delete(const std::string &table, const std::string &whereClause = "",
145                                                const Values &args = {}) = 0;
146 
147     /**
148      * @brief Deletes data from the database based on a specified instance object of AbsRdbPredicates.
149      *
150      * @param predicates Indicates the specified update condition by the instance object of {@link AbsRdbPredicates}.
151      */
152     virtual std::pair<int32_t, int32_t> Delete(const AbsRdbPredicates &predicates) = 0;
153 
154     /**
155      * @brief Queries data in the database based on SQL statement.
156      *
157      * @param sql Indicates the SQL statement to execute.
158      * @param args Indicates the selection arguments.
159      * @param preCount IIndicates whether to calculate the count during query.
160      */
161     virtual std::shared_ptr<ResultSet> QueryByStep(const std::string &sql, const Values &args = {},
162         bool preCount = true) = 0;
163 
164     /**
165      * @brief Queries data in the database based on specified conditions.
166      *
167      * @param predicates Indicates the specified query condition by the instance object of {@link AbsRdbPredicates}.
168      * @param columns Indicates the columns to query. If the value is empty array, the query applies to all columns.
169      * @param preCount IIndicates whether to calculate the count during query.
170      */
171     virtual std::shared_ptr<ResultSet> QueryByStep(const AbsRdbPredicates &predicates, const Fields &columns = {},
172         bool preCount = true) = 0;
173 
174     /**
175      * @brief Executes an SQL statement that contains specified parameters and
176      *        get two values of type int and ValueObject.
177      *
178      * @param sql Indicates the SQL statement to execute.
179      * @param args Indicates the {@link ValueObject} values of the parameters in the SQL statement.
180      */
181     virtual std::pair<int32_t, ValueObject> Execute(const std::string &sql, const Values &args = {}) = 0;
182 
183 private:
184     static inline Creator creator_;
185 };
186 }
187 #endif
188