| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | // SPDX-FileCopyrightText: 2023 Carl Zeiss Microscopy GmbH | ||
| 2 | // | ||
| 3 | // SPDX-License-Identifier: MIT | ||
| 4 | |||
| 5 | #pragma once | ||
| 6 | |||
| 7 | #include <memory> | ||
| 8 | #include <string> | ||
| 9 | #include <cstdint> | ||
| 10 | #include <vector> | ||
| 11 | #include "IDbStatement.h" | ||
| 12 | #include "IEnvironment.h" | ||
| 13 | |||
| 14 | /// This interface gathers the "database operation" we use in libimgdoc2. The goal is that | ||
| 15 | /// this interface is database-agnostic, i.e. can be implemented for different databases, and | ||
| 16 | /// that differences in database are abstracted at this level. | ||
| 17 | class IDbConnection | ||
| 18 | { | ||
| 19 | public: | ||
| 20 | /// Information about a database column. | ||
| 21 | struct ColumnInfo | ||
| 22 | { | ||
| 23 | std::string column_name; ///< Name of the column. | ||
| 24 | |||
| 25 | /// Type of the column. Currently, this is a string, an no effort so far has been done to | ||
| 26 | /// 'canonicalize" this information. | ||
| 27 | std::string column_type; | ||
| 28 | }; | ||
| 29 | |||
| 30 | /// Information about an index. Currently, we just report the name, if would be desirable to query | ||
| 31 | /// what is indexed. | ||
| 32 | struct IndexInfo | ||
| 33 | { | ||
| 34 | std::string index_name; ///< Name of the index | ||
| 35 | }; | ||
| 36 | public: | ||
| 37 | /// Executes the given SQL statement and does *not* read any data returned from the database. | ||
| 38 | /// \param sql_statement The SQL statement (in UTF8). | ||
| 39 | virtual void Execute(const char* sql_statement) = 0; | ||
| 40 | |||
| 41 | /// Executes the specified statement and does *not* read any data returned from the database. | ||
| 42 | /// Optionally, the number of rows modified by the statement is returned. This works for | ||
| 43 | /// INSERT, UPDATE, and DELETE statements. | ||
| 44 | /// C.f. https://sqlite.org/c3ref/total_changes.html . | ||
| 45 | /// | ||
| 46 | /// \param [in,out] statement The statement to be executed. | ||
| 47 | /// \param [in,out] number_of_rows_modified (Optional) If non-null and if successful, the number of rows modified is given here. | ||
| 48 | virtual void Execute(IDbStatement* statement, std::int64_t* number_of_rows_modified = nullptr) = 0; | ||
| 49 | virtual std::int64_t ExecuteAndGetLastRowId(IDbStatement* statement) = 0; | ||
| 50 | |||
| 51 | /// Prepare a SQL statement - the statement is compiled into an internal representation, and a | ||
| 52 | /// statement-object is returned. | ||
| 53 | /// \param sql_statement The SQL statement (in UTF8). | ||
| 54 | /// \returns The newly constructed statement-object. | ||
| 55 | virtual std::shared_ptr<IDbStatement> PrepareStatement(const std::string& sql_statement) = 0; | ||
| 56 | |||
| 57 | virtual bool StepStatement(IDbStatement* statement) = 0; | ||
| 58 | |||
| 59 | virtual void BeginTransaction() = 0; | ||
| 60 | virtual void EndTransaction(bool commit) = 0; | ||
| 61 | virtual bool IsTransactionPending() const = 0; | ||
| 62 | |||
| 63 | /// Gets information about the specified table. | ||
| 64 | /// TODO: Note that (in current implementation) this method returns an empty vector in case that the | ||
| 65 | /// table does not exists (so an empty table and a non-existing table is indistinguishable). | ||
| 66 | /// | ||
| 67 | /// \param table_name Name of the table. | ||
| 68 | /// \returns The table information - a vector describing the columns of the table. | ||
| 69 | virtual std::vector<ColumnInfo> GetTableInfo(const char* table_name) = 0; | ||
| 70 | |||
| 71 | /// Gets a list of existing indices for the specified table. | ||
| 72 | /// | ||
| 73 | /// \param table_name Name of the table. | ||
| 74 | /// | ||
| 75 | /// \returns The indices which exist for the specified table. | ||
| 76 | virtual std::vector<IDbConnection::IndexInfo> GetIndicesOfTable(const char* table_name) = 0; | ||
| 77 | |||
| 78 | 544 | virtual ~IDbConnection() = default; | |
| 79 | |||
| 80 | [[nodiscard]] virtual const std::shared_ptr<imgdoc2::IHostingEnvironment>& GetHostingEnvironment() const = 0; | ||
| 81 | |||
| 82 | public: | ||
| 83 | // no copy and no move (-> https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c21-if-you-define-or-delete-any-copy-move-or-destructor-function-define-or-delete-them-all ) | ||
| 84 | 272 | IDbConnection() = default; | |
| 85 | IDbConnection(const IDbConnection&) = delete; // copy constructor | ||
| 86 | IDbConnection& operator=(const IDbConnection&) = delete; // copy assignment | ||
| 87 | IDbConnection(IDbConnection&&) = delete; // move constructor | ||
| 88 | IDbConnection& operator=(IDbConnection&&) = delete; // move assignment | ||
| 89 | |||
| 90 | public: | ||
| 91 | 1492 | void Execute(const std::string& sql_statement) | |
| 92 | { | ||
| 93 | 1492 | this->Execute(sql_statement.c_str()); | |
| 94 | 1492 | } | |
| 95 | }; | ||
| 96 |