Copy constructor for result set and entity

Summary

These changes support a better handling of the ResultSet and Entity objects when their owners are to be deleted (e.g. in clients which delete transansaction due to end of the scope of a function while they return an entity or the resultset of said transaction)

These changes are needed for caosdb-julialib!12 (merged)

The server is just being updated for version-compatibility reasons: caosdb-server!31 (merged)

Focus

• Refactoring of the ResultSet and Entity class' copy constructors (amd a general clean-up of the Entity constructor)
• Additional Transaction::ReleaseResultSet and ResultSet::release_at methods which release the unique_ptr from their owning objects.

Test Environment

• CPP Integration tests in caosdb-cppinttest!15 (merged)
• Julia integration tests in

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

@@ -196,6 +196,14 @@ public:
   [[nodiscard]] virtual auto size() const noexcept -> int = 0;
   [[nodiscard]] virtual auto at(const int index) const -> const Entity & = 0;
   [[nodiscard]] virtual auto mutable_at(int index) const -> Entity * = 0;
+  /**
+   * Return the Entity at the given index.
+   *
+   * This method releases the entity from the underlying collection and thus
+   * leaves the ResultSet in a corrupted state.
+   *
+   * This method can be called only once for each index.
+   */
   [[nodiscard]] virtual auto release_at(int index) -> Entity * = 0;
   auto begin() const -> iterator;
   auto end() const -> iterator;
@@ -217,6 +225,11 @@ private:
 
 class AbstractMultiResultSet : public ResultSet {
 public:
+  /**
+   * Copy Constructor.
+   *
+   * Copies the underlying collection of entities.
+   */
   inline AbstractMultiResultSet(const AbstractMultiResultSet &original) {
     for (const Entity &entity : original) {
       this->items.push_back(std::make_unique<Entity>(entity));
@@ -232,9 +245,20 @@ public:
   [[nodiscard]] inline auto mutable_at(int index) const -> Entity * override {
     return this->items.at(index).get();
   }
+  /**
+   * Return the Entity at the given index.
+   *
+   * This method releases the entity from the underlying collection and thus
+   * leaves the ResultSet in a corrupted state.
+   *
+   * This method can be called only once for each index.
+   */
   [[nodiscard]] inline auto release_at(int index) -> Entity * override {
     return this->items.at(index).release();
   }
+  /**
+   * Remove all entities from this result set.
+   */
   inline auto clear() noexcept -> void { this->items.clear(); }
 
 protected:
@@ -375,14 +399,38 @@ public:
    */
   [[nodiscard]] inline auto GetStatus() const noexcept -> TransactionStatus { return this->status; }
 
+  /**
+   * Return the ResultSet of this transaction.
+   *
+   * Note: If this method is called before the transaction has terminated
+   * (GetStatus().GetCode() < 0) this method has undefined behavior.
+   *
+   * Instead, do Execute() or WaitForIt() and only call this method afterwards.
+   */
   [[nodiscard]] inline auto GetResultSet() const noexcept -> const ResultSet & {
     if (!this->result_set) {
-      // TODO(tf) Discuss. This condition implies a programming error. Should we handle it?
+      CAOSDB_LOG_ERROR(logger_name)
+        << "GetResultSet was called before the transaction has terminated. This is a programming "
+           "error of the code which uses the transaction.";
+      // TODO(tf) This is a really bad SegFault factory. When the transaction
+      // terminates and the result_set is being overriden, the unique_ptr
+      // created here will be deleted and any client of the return ResultSet
+      // will have a SegFault.
       this->result_set = std::make_unique<MultiResultSet>(std::vector<std::unique_ptr<Entity>>());
     }
     return *(this->result_set.get());
   }
 
+  /**
+   * Return the ResultSet of this transaction.
+   *
+   * This method releases the ResultSet from the transaction leaving it in a
+   * currupted state.
+   *
+   * This method can be called only once and only after the transaction has terminated.
+   *
+   * Otherwise, this method has undefined behavior.
+   */
   [[nodiscard]] inline auto ReleaseResultSet() noexcept -> const ResultSet * {
     this->status = TransactionStatus::SPOILED();
     return this->result_set.release();