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

@@ -124,6 +124,9 @@ 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;
@@ -131,6 +134,12 @@ 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;
@@ -145,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;
@@ -171,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);