F multi retrieve

Summary

Implements multi-entity retrieval caosdb/customers/lfpb/management#393

See tests in caosdb-cppinttest!4 (merged)

Focus

• Most relevant changes are in include/caosdb/transaction.h and src/caosdb/transaction.cpp.
• New class MultiResultSet represents a result set with multiple entities. Is this a good name?
• New enum TransactionType restricts the kind of sub-transactions (Insert, Delete, Retrieve) which can be added to a transaction.
• Macros are used to check whether InsertEntity, DeleteById or RetrieveById can be called on a transaction (given the TransactionStatus and 'TransactionType`).

Test Environment

Test with server in branch f-grpc-f-multi-retrieve

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related Issues
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

include/caosdb/transaction.h

@@ -33,6 +33,7 @@
 #include "google/protobuf/util/json_util.h" // for MessageToJsonString, Jso...
 #include <stdexcept>
 #include <iterator>
+// IWYU pragma: no_include <ext/alloc_traits.h>
 #include <memory> // for shared_ptr, unique_ptr
 #include <string> // for string
 #include <vector> // for vector
@@ -119,8 +120,13 @@ using caosdb::transaction::TransactionStatus;
 using WrappedResponseCase =
   caosdb::entity::v1alpha1::TransactionResponse::WrappedResponseCase;
 
+class Transaction;
+
 static const std::string logger_name = "caosdb::transaction";
 
+/**
+ * Abstract base class for the results of a Transaction.
+ */
 class ResultSet {
 public:
   virtual ~ResultSet() = default;
@@ -128,34 +134,16 @@ public:
   [[nodiscard]] virtual auto At(const int index) const -> const Entity & = 0;
 };
 
+/**
+ * Container with results of a transaction.
+ *
+ * In contrast to UniqueResult, this one can also hold multiple entities or zero
+ * entities.
+ */
 class MultiResultSet : public ResultSet {
 public:
   ~MultiResultSet() = default;
-  explicit inline MultiResultSet(MultiTransactionResponse *response) {
-    auto responses = response->mutable_responses();
-    Entity *entity = nullptr;
-    for (auto sub_response : *responses) {
-      switch (sub_response.wrapped_response_case()) {
-      case WrappedResponseCase::kRetrieveResponse:
-        entity = new Entity(
-          sub_response.mutable_retrieve_response()->release_entity());
-        break;
-      case WrappedResponseCase::kInsertResponse:
-
-        entity = new Entity(sub_response.release_insert_response());
-        break;
-      case WrappedResponseCase::kDeleteResponse:
-        entity = new Entity(sub_response.release_delete_response());
-        break;
-      default:
-        // TODO(tf) Updates
-        break;
-      }
-      if (entity) {
-        this->entities.push_back(std::unique_ptr<Entity>(entity));
-      }
-    }
-  }
+  explicit MultiResultSet(MultiTransactionResponse *response);
   [[nodiscard]] inline auto Size() const noexcept -> int override {
     return this->entities.size();
   }
@@ -166,6 +154,12 @@ public:
   std::vector<std::unique_ptr<Entity>> entities;
 };
 
+/**
+ * Container with the single result of a transaction.
+ *
+ * In contrast to MultiResultSet, this one guarantees to hold exactly one
+ * entity.
+ */
 class UniqueResult : public ResultSet {
 public:
   ~UniqueResult() = default;
@@ -192,14 +186,21 @@ private:
  */
 class Transaction {
 public:
+  /**
+   * The transaction type restricts the kind of sub-transaction which may be
+   * added to a transaction (insertion, update, deletion, retrieval).
+   *
+   * @note MIXED_READ_AND_WRITE and MIXED_WRITE transaction are not supported
+   * yet.
+   */
   enum TransactionType {
-    NONE,
-    READ_ONLY,
-    INSERT,
-    UPDATE,
-    DELETE,
-    MIXED_WRITE,
-    MIXED_READ_AND_WRITE
+    NONE,                /// Unspecified or not specified yet.
+    READ_ONLY,           /// Only retrievals (by id, by query)
+    INSERT,              /// Only insertions
+    UPDATE,              /// Only updates
+    DELETE,              /// Only deletions
+    MIXED_WRITE,         /// Only insertions, deletions, updates
+    MIXED_READ_AND_WRITE /// all kind of transaction.
   };
   Transaction(std::shared_ptr<EntityTransactionService::Stub> service_stub);