Merge branch 'feature/collection.IsFullyLoaded' into develop

JeremyCaney · JeremyCaney · commit 48859589cbb0 · 2021-01-19T10:53:34.000-08:00
Introduced an `IsFullyLoaded` property to both the `TopicRelationshipMultiMap` and `TopicReferenceDictionary` collections. If, during `ITopicRepository.Load()`, a `Target_TopicID` cannot be discovered within the scoped topic graph—either from the e.g. `GetTopics` call, or from the `referenceTopic` graph—then `IsFullyLoaded` is set to `false`, indicating that the in-memory collection doesn't fully represent the saved state of the `Topic`. In this case, when `ITopicRepository.Save()` is called, `UpdateRelationships` and/or `UpdateReferences` will disable `DeleteUnmatched` in order to protect against a scenario where these target topics are inadvertently deleted.

This should be a rare scenario. Nevertheless, it helps safeguard against potential data integrity issues when loading individual topics or topic branches with a missing or incomplete `referenceTopic` parameter.
diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs
@@ -364,8 +364,11 @@ private static void SetRelationships(this SqlDataReader reader, TopicIndex topic
         related                 = topics[targetTopicId];
       }
 
-      // Bypass if either of the objects are missing
-      if (related is null) return;
+      // Bypass if the target object is missing
+      if (related is null) {
+        current.Relationships.IsFullyLoaded = false;
+        return;
+      }
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Set relationship on object
@@ -417,8 +420,11 @@ private static void SetReferences(this SqlDataReader reader, TopicIndex topics,
         referenced              = topics[targetTopicId.Value];
       }
 
-      // Bypass if either of the objects are missing
-      if (referenced is null) return;
+      // Bypass if the target object is missing
+      if (referenced is null) {
+        current.References.IsFullyLoaded = false;
+        return;
+      }
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Set relationship on object
diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs
@@ -684,7 +684,7 @@ private static void PersistRelations(Topic topic, SqlDateTime version, SqlConnec
           command.AddParameter("RelationshipKey", key);
           command.AddParameter("RelatedTopics", targetIds);
           command.AddParameter("Version", version.Value);
-          command.AddParameter("DeleteUnmatched", true);
+          command.AddParameter("DeleteUnmatched", topic.Relationships.IsFullyLoaded);
 
           command.ExecuteNonQuery();
 
@@ -743,7 +743,7 @@ private static void PersistReferences(Topic topic, SqlDateTime version, SqlConne
         command.AddParameter("TopicID", topicId);
         command.AddParameter("ReferencedTopics", references);
         command.AddParameter("Version", version.Value);
-        command.AddParameter("DeleteUnmatched", true);
+        command.AddParameter("DeleteUnmatched", topic.References.IsFullyLoaded);
 
         command.ExecuteNonQuery();
 
diff --git a/OnTopic/References/TopicReferenceDictionary.cs b/OnTopic/References/TopicReferenceDictionary.cs
@@ -9,6 +9,7 @@
 using OnTopic.Attributes;
 using OnTopic.Internal.Diagnostics;
 using OnTopic.Internal.Reflection;
+using OnTopic.Repositories;
 
 namespace OnTopic.References {
 
@@ -61,11 +62,33 @@ public TopicReferenceDictionary(Topic parent) {
     public int Count => _storage.Count;
 
     /*==========================================================================================================================
-    | IsReadOnly
+    | IS READ ONLY?
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <inheritdoc/>
     public bool IsReadOnly => false;
 
+    /*==========================================================================================================================
+    | IS FULLY LOADED?
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Determines whether or not the collection was fully loaded from the persistence store.
+    /// </summary>
+    /// <remarks>
+    ///   <para>
+    ///     When loading an individual <see cref="Topic"/> or branch from the persistence store, it is possible that topic
+    ///     references may not be fully available. In this scenario, updating topic references while e.g. deleting unmatched
+    ///     relationships can result in unintended data loss. To account for this, the <see cref="IsFullyLoaded"/> property '
+    ///     tracks whether a collection was fully loaded from the persistence store; if it wasn't, the <see cref="
+    ///     ITopicRepository"/> should not deleted unmatched topic references.
+    ///   </para>
+    ///   <para>
+    ///     The <see cref="IsFullyLoaded"/> property defaults to <c>true</c>. It should be set to <c>false</c> during the <see cref="
+    ///     ITopicRepository.Load(String?, Topic?, Boolean)"/> method if any members of the collection cannot be mapped back to
+    ///     a valid <see cref="Topic"/> reference in memory.
+    ///   </para>
+    /// </remarks>
+    public bool IsFullyLoaded { get; set; } = true;
+
     /*==========================================================================================================================
     | ITEM
     \-------------------------------------------------------------------------------------------------------------------------*/
diff --git a/OnTopic/References/TopicRelationshipMultiMap.cs b/OnTopic/References/TopicRelationshipMultiMap.cs
@@ -7,6 +7,7 @@
 using System.Collections.Generic;
 using OnTopic.Collections;
 using OnTopic.Internal.Diagnostics;
+using OnTopic.Repositories;
 
 namespace OnTopic.References {
 
@@ -210,6 +211,28 @@ internal void SetTopic(string relationshipKey, Topic topic, bool? markDirty, boo
 
     }
 
+    /*==========================================================================================================================
+    | IS FULLY LOADED?
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Determines whether or not the collection was fully loaded from the persistence store.
+    /// </summary>
+    /// <remarks>
+    ///   <para>
+    ///     When loading an individual <see cref="Topic"/> or branch from the persistence store, it is possible that the
+    ///     relationships may not be fully available. In this scenario, updating relationships while e.g. deleting unmatched
+    ///     relationships can result in unintended data loss. To account for this, the <see cref="IsFullyLoaded"/> property
+    ///     tracks whether a collection was fully loaded from the persistence store; if it wasn't, the <see cref="
+    ///     ITopicRepository"/> should not deleted unmatched relationships.
+    ///   </para>
+    ///   <para>
+    ///     The <see cref="IsFullyLoaded"/> property defaults to <c>true</c>. It should be set to <c>false</c> during the <see cref="
+    ///     ITopicRepository.Load(String?, Topic?, Boolean)"/> method if any members of the collection cannot be mapped back to
+    ///     a valid <see cref="Topic"/> reference in memory.
+    ///   </para>
+    /// </remarks>
+    public bool IsFullyLoaded { get; set; } = true;
+
     /*==========================================================================================================================
     | METHOD: IS DIRTY?
     \-------------------------------------------------------------------------------------------------------------------------*/
